240 lines
7.2 KiB
Markdown
240 lines
7.2 KiB
Markdown
---
|
||
created: "2026-03-22"
|
||
updated: "2026-03-22"
|
||
type: resource
|
||
tags: [resource, openclaw, ai-agent, discord, howto, homelab]
|
||
source: "实际创建 xhs-creator agent 的过程总结 + skill review 后改进"
|
||
---
|
||
|
||
# OpenClaw Agent 创建指南
|
||
|
||
## 概述
|
||
|
||
基于创建小红书 agent (xhs-creator) 的实际经验，总结 OpenClaw agent 创建的完整流程。Claude Code 有对应的自动化 skill (`openclaw-create-agent`)，说"创建一个 xxx agent"即可触发。
|
||
|
||
## 前置准备
|
||
|
||
### 1. 创建 Discord Bot
|
||
|
||
1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
|
||
2. New Application > 命名 > Create
|
||
3. Bot 页面 > Reset Token > 复制 token
|
||
4. 开启 **Message Content Intent**（Privileged Gateway Intents 下）
|
||
5. 生成邀请链接：OAuth2 > URL Generator > 勾选 `bot` > 权限选择 Send Messages, Read Message History, Add Reactions
|
||
6. 用链接把 bot 邀请到目标 Discord 服务器
|
||
|
||
### 2. 获取 Discord ID
|
||
|
||
需要开启开发者模式（用户设置 > 高级 > 开发者模式）：
|
||
|
||
| 信息 | 获取方式 |
|
||
|------|---------|
|
||
| Guild ID | 右键服务器图标 > 复制服务器 ID |
|
||
| Channel ID | 右键文字频道 > 复制频道 ID |
|
||
| Bot User ID | Base64 解码 token 第一段（`.` 之前）|
|
||
| Owner User ID | `964122056163721286`（固定值） |
|
||
|
||
Bot User ID 解码方法：
|
||
|
||
```bash
|
||
echo "TOKEN第一段" | base64 -d
|
||
# 例如: echo "MTQ4NTMwNTQyOTcxMzA5NjkzNw" | base64 -d
|
||
# 输出: 1485305429713096937
|
||
```
|
||
|
||
## 创建步骤
|
||
|
||
### Step 1: Pre-flight 检查
|
||
|
||
验证 agent ID 是否已被占用：
|
||
|
||
```bash
|
||
ssh yiukai@192.168.68.108 'node -e "
|
||
const cfg = JSON.parse(require(\"fs\").readFileSync(\"/home/yiukai/.openclaw/openclaw.json\", \"utf8\"));
|
||
const exists = cfg.agents.list.some(a => a.id === \"AGENT_ID\");
|
||
console.log(exists ? \"CONFLICT\" : \"OK\");
|
||
"'
|
||
```
|
||
|
||
### Step 2: 创建目录
|
||
|
||
```bash
|
||
ssh yiukai@192.168.68.108 "mkdir -p ~/.openclaw/workspace-{agent-id} ~/.openclaw/agents/{agent-id}/agent"
|
||
```
|
||
|
||
### Step 3: 编写 Bootstrap 文件
|
||
|
||
**重要**: 所有 .md 文件放在 **workspace** 目录（`~/.openclaw/workspace-{agent-id}/`），**不是** agentDir。agentDir 只放 JSON 配置文件（auth-profiles.json, models.json），由系统自动管理。
|
||
|
||
**AGENTS.md** -- 操作指令、能力定义、工作流程。必须包含：
|
||
|
||
1. 身份声明 -- 一句话说明 agent 是谁、专注什么
|
||
2. 核心能力 -- 3-5 个编号章节，具体描述
|
||
3. 工作流程/输出模板 -- agent 产出的结构化格式
|
||
4. 约束条件 -- 明确不做什么
|
||
|
||
**SOUL.md** -- 人格、语气、边界。保持简短（20-30行）：
|
||
|
||
1. 身份 -- 一行角色描述
|
||
2. 语气 -- 3-4 条沟通风格
|
||
3. 语言 -- 主要使用的语言
|
||
4. 边界 -- 3-4 条拒绝做的事
|
||
|
||
可选文件：
|
||
- `TOOLS.md` -- 用户自定义工具说明
|
||
- `BOOTSTRAP.md` -- 一次性引导（运行后自动删除）
|
||
- `IDENTITY.md` -- 名称/风格
|
||
- `USER.md` -- 用户画像
|
||
|
||
### Step 4: 更新 openclaw.json（三部分）
|
||
|
||
使用 Node.js 脚本通过 SSH 原子更新，确保 JSON 有效性：
|
||
|
||
#### 4a. Agent 条目 (`agents.list`)
|
||
|
||
```json
|
||
{
|
||
"id": "agent-id",
|
||
"name": "agent-id",
|
||
"workspace": "/home/yiukai/.openclaw/workspace-agent-id",
|
||
"agentDir": "/home/yiukai/.openclaw/agents/agent-id/agent",
|
||
"model": "kimi-coding/k2p5",
|
||
"identity": { "name": "显示名称" },
|
||
"groupChat": {
|
||
"mentionPatterns": ["<@!?BOT_USER_ID>", "中文名称", "英文简称", "BOT_USER_ID"]
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `id` | Yes | 唯一标识符，用于 binding 和命令引用 |
|
||
| `workspace` | Yes | agent 的工作目录，存放会话数据 |
|
||
| `agentDir` | Yes | AGENTS.md/SOUL.md 所在目录 |
|
||
| `model` | No | 覆盖 `agents.defaults.model.primary` |
|
||
| `identity.name` | Yes | 在消息中显示的名称 |
|
||
| `groupChat.mentionPatterns` | No | 群聊中触发 agent 的模式 |
|
||
| `subagents.allowAgents` | No | 允许调用的子 agent 列表 |
|
||
|
||
#### 4b. Discord 账户 (`channels.discord.accounts`)
|
||
|
||
```json
|
||
"account-id": {
|
||
"name": "显示名称",
|
||
"enabled": true,
|
||
"token": "DISCORD_BOT_TOKEN",
|
||
"groupPolicy": "open",
|
||
"streaming": "off",
|
||
"guilds": {
|
||
"GUILD_ID": {
|
||
"requireMention": false,
|
||
"users": ["964122056163721286", "BOT_USER_ID"],
|
||
"channels": { "CHANNEL_ID": { "allow": true } }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `groupPolicy` | `open` = 允许所有，`allowlist` = 仅白名单，`disabled` = 禁用 |
|
||
| `requireMention` | `true` = 共享频道需 @mention，`false` = 独占频道直接响应 |
|
||
| `users` | 白名单，必须包含 owner ID 和 bot 自身 ID |
|
||
| `streaming` | `off` / `partial` / `full` |
|
||
|
||
#### 4c. Binding (`bindings`)
|
||
|
||
```json
|
||
{ "agentId": "agent-id", "match": { "channel": "discord", "accountId": "account-id" } }
|
||
```
|
||
|
||
### Step 5: 验证
|
||
|
||
配置支持热重载，保存后自动生效。检查日志：
|
||
|
||
```bash
|
||
ssh yiukai@192.168.68.108 'journalctl --user -u openclaw-gateway --since "30 sec ago" --no-pager | grep -iE "agent-id|error|reload"'
|
||
```
|
||
|
||
三个成功指标（全部出现才算成功）：
|
||
|
||
1. `[reload] config change detected` -- 热重载触发
|
||
2. `[discord] [agent-id] starting provider` -- bot 连接 Discord
|
||
3. `channels resolved: GUILD_ID/CHANNEL_ID` -- 频道解析成功
|
||
|
||
如果热重载未触发：
|
||
|
||
```bash
|
||
ssh yiukai@192.168.68.108 'systemctl --user restart openclaw-gateway'
|
||
```
|
||
|
||
## 可选扩展
|
||
|
||
### 添加 Skills
|
||
|
||
```bash
|
||
ssh yiukai@192.168.68.108 "mkdir -p ~/.openclaw/skills/skill-name"
|
||
# 然后写 SKILL.md（含 frontmatter: name, description, requires, install）
|
||
```
|
||
|
||
### 添加 Cron 定时任务
|
||
|
||
通过 Node.js 脚本添加到 `cron.entries`，或使用 CLI：
|
||
|
||
```bash
|
||
openclaw cron add --agent agent-id --schedule "0 8 * * 1-5" \
|
||
--message "任务内容" --deliver discord:CHANNEL_ID
|
||
```
|
||
|
||
### 启用 Agent 间通信
|
||
|
||
1. 添加 agent ID 到 `tools.agentToAgent.allow` 列表
|
||
2. 在调用方 agent 设置 `subagents.allowAgents`
|
||
3. 共享频道中所有协作 agent 设置 `requireMention: true`
|
||
|
||
## 实际案例
|
||
|
||
### xhs-creator（2026-03-22）
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| Agent ID | `xhs-creator` |
|
||
| 显示名称 | 小红薯 |
|
||
| Discord Bot | @小红书牛马 |
|
||
| Guild | 小红书 (`1485305839379021871`) |
|
||
| Channel | general (`1485305839828074620`) |
|
||
| Bot User ID | `1485305429713096937` |
|
||
| 模型 | kimi-coding/k2p5 |
|
||
| requireMention | false（独占频道） |
|
||
| 用途 | 小红书内容创作、话题分析、笔记撰写 |
|
||
|
||
## 排障指南
|
||
|
||
### Bot 无响应
|
||
|
||
1. 检查 bot 是否已邀请到服务器
|
||
2. 检查 Message Content Intent 是否开启
|
||
3. 检查 `enabled: true`
|
||
4. 检查 users 白名单是否包含你的 ID (`964122056163721286`)
|
||
5. 查看日志：`journalctl --user -u openclaw-gateway -f`
|
||
6. 检查 token 是否有效（可能已过期需重新生成）
|
||
|
||
### 多 Agent 协作
|
||
|
||
- 在同一 Guild 的同一频道放多个 agent
|
||
- 所有 agent 设置 `requireMention: true` 避免同时响应
|
||
- 配置 `subagents.allowAgents` 允许 agent 间通信
|
||
- 配置 `tools.agentToAgent.allow` 列表
|
||
|
||
## Claude Code 自动化
|
||
|
||
对应 skill: `~/.claude/skills/openclaw-create-agent/SKILL.md`
|
||
|
||
触发方式：告诉 Claude "创建一个 xxx agent" / "add agent" / "new bot"，提供 token、Guild ID、Channel ID 即可自动完成全部步骤。
|
||
|
||
## Related
|
||
|
||
- [[OpenClaw-Skill-Reference]]
|
||
- [[OpenClaw 部署配置分析]]
|
||
- [[OpenClaw Stock Agent 配置详情]]
|