---
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 配置详情]]