Update
This commit is contained in:
Yaojia Wang
239
4 - Resources/OpenClaw/OpenClaw Agent 创建指南.md
Normal file
239
4 - Resources/OpenClaw/OpenClaw Agent 创建指南.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
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 文件
|
||||
|
||||
在 `~/.openclaw/agents/{agent-id}/agent/` 下创建：
|
||||
|
||||
**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 配置详情]]
|
||||
Reference in New Issue
Block a user