kai/knowledge-base

Fork 0

Files

Yaojia Wang decd5509bc Update

2026-03-22 18:16:25 +01:00

7.1 KiB

Raw Blame History

created, updated, type, tags, source

created

updated

type

OpenClaw Agent 创建指南

概述

基于创建小红书 agent (xhs-creator) 的实际经验，总结 OpenClaw agent 创建的完整流程。Claude Code 有对应的自动化 skill (openclaw-create-agent)，说"创建一个 xxx agent"即可触发。

前置准备

1. 创建 Discord Bot

访问 Discord Developer Portal
New Application > 命名 > Create
Bot 页面 > Reset Token > 复制 token
开启 Message Content Intent（Privileged Gateway Intents 下）
生成邀请链接：OAuth2 > URL Generator > 勾选 bot > 权限选择 Send Messages, Read Message History, Add Reactions
用链接把 bot 邀请到目标 Discord 服务器

2. 获取 Discord ID

需要开启开发者模式（用户设置 > 高级 > 开发者模式）：

信息	获取方式
Guild ID	右键服务器图标 > 复制服务器 ID
Channel ID	右键文字频道 > 复制频道 ID
Bot User ID	Base64 解码 token 第一段（`.` 之前）
Owner User ID	`964122056163721286`（固定值）

Bot User ID 解码方法：

echo "TOKEN第一段" | base64 -d
# 例如: echo "MTQ4NTMwNTQyOTcxMzA5NjkzNw" | base64 -d
# 输出: 1485305429713096937

创建步骤

Step 1: Pre-flight 检查

验证 agent ID 是否已被占用：

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: 创建目录

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 -- 操作指令、能力定义、工作流程。必须包含：

身份声明 -- 一句话说明 agent 是谁、专注什么
核心能力 -- 3-5 个编号章节，具体描述
工作流程/输出模板 -- agent 产出的结构化格式
约束条件 -- 明确不做什么

SOUL.md -- 人格、语气、边界。保持简短（20-30行）：

身份 -- 一行角色描述
语气 -- 3-4 条沟通风格
语言 -- 主要使用的语言
边界 -- 3-4 条拒绝做的事

可选文件：

TOOLS.md -- 用户自定义工具说明
BOOTSTRAP.md -- 一次性引导（运行后自动删除）
IDENTITY.md -- 名称/风格
USER.md -- 用户画像

Step 4: 更新 openclaw.json（三部分）

使用 Node.js 脚本通过 SSH 原子更新，确保 JSON 有效性：

4a. Agent 条目 (`agents.list`)

{
  "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`)

"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`)

{ "agentId": "agent-id", "match": { "channel": "discord", "accountId": "account-id" } }

Step 5: 验证

配置支持热重载，保存后自动生效。检查日志：

ssh yiukai@192.168.68.108 'journalctl --user -u openclaw-gateway --since "30 sec ago" --no-pager | grep -iE "agent-id|error|reload"'

三个成功指标（全部出现才算成功）：

[reload] config change detected -- 热重载触发
[discord] [agent-id] starting provider -- bot 连接 Discord
channels resolved: GUILD_ID/CHANNEL_ID -- 频道解析成功

如果热重载未触发：

ssh yiukai@192.168.68.108 'systemctl --user restart openclaw-gateway'

可选扩展

添加 Skills

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：

openclaw cron add --agent agent-id --schedule "0 8 * * 1-5" \
  --message "任务内容" --deliver discord:CHANNEL_ID

启用 Agent 间通信

添加 agent ID 到 tools.agentToAgent.allow 列表
在调用方 agent 设置 subagents.allowAgents
共享频道中所有协作 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 无响应

检查 bot 是否已邀请到服务器
检查 Message Content Intent 是否开启
检查 enabled: true
检查 users 白名单是否包含你的 ID (964122056163721286)
查看日志：journalctl --user -u openclaw-gateway -f
检查 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 即可自动完成全部步骤。

7.1 KiB Raw Blame History Unescape Escape