OpenClaw Agent Builder

为 OpenClaw 创建和配置 AI Agent 的完整指南。OpenClaw 使用基于工作空间的 Agent 架构，每个 Agent 拥有独立的会话、配置和上下文文件。

核心架构

~/.openclaw/
├── openclaw.json # 主配置文件
├── agents/ # Agent 会话存储
│ ├── /
│ │ ├── agent/ # Agent 配置
│ │ └── sessions/ # 会话历史 (JSONL)
│ └── main/ # 默认主 Agent
├── workspace/ # 主工作空间
│ ├── AGENTS.md # 工作流指令
│ ├── SOUL.md # 角色人格定义
│ ├── TOOLS.md # 工具使用说明
│ ├── USER.md # 用户配置
│ ├── MEMORY.md # 长期记忆 (仅主会话)
│ ├── memory/ # 每日记忆文件
│ └── .learnings/ # 学习日志
└── skills/ # 技能目录

何时使用

场景	方案
需要专用 Agent 处理特定领域任务	创建新 Agent
需要隔离会话历史

使用多 Agent 路由 | | 不同任务需要不同模型/工具配置 | 配置 Agent 专属设置 | | 团队协作需要独立上下文 | 创建团队 Agent | | 多人共用 Gateway 但需要私密对话 | 配置 dmScope: per-channel-peer | | 同一用户跨频道保持会话连续 | 配置 identityLinks | | 飞书/钉钉群需要绑定特定 Agent | 配置 bindings + requireMention |

可选机制选择器

不是每个 Agent 都需要以下所有机制。根据实际需求选择：

机制	使用时机	配置位置
Bindings	需要精确控制消息路由到哪个 Agent	bindings[]
dmScope

多人使用同一个聊天账号，需要隔离私密对话 | session.dmScope |
| identityLinks | 同一用户在多个频道联系你，希望共享会话 | session.identityLinks |
| sendPolicy | 阻止某些会话类型的消息发送（如 cron 任务不回复） | session.sendPolicy |
| session.maintenance | 高频率会话，需要自动清理过期会话 | session.maintenance |
| threadBindings | Discord/Slack 线程需要独立会话 | session.threadBindings |
| sandbox | 运行不受信代码或需要安全隔离 | agents[].sandbox |
| tools allow/deny | 限制 Agent 可使用的工具（如家庭 Agent 不允许写文件） | agents[].tools |
| Feishu 群绑定 | 飞书特定群组需要特定 Agent 响应 | channels.feishu.groups |

机制配置示例

1. Bindings - 消息路由

json5
{
agents: {
list: [
{ id: home, workspace: ~/.openclaw/workspace-home },
{ id: work, workspace: ~/.openclaw/workspace-work },
],
},
bindings: [
// 飞书特定用户 → work Agent
{ agentId: work, match: { channel: feishu, peer: { kind: direct, id: ou_xxx } } },
// 飞书特定群组 → work Agent
{ agentId: work, match: { channel: feishu, peer: { kind: group, id: oc_xxx } } },
// WhatsApp 默认 → home Agent
{ agentId: home, match: { channel: whatsapp } },
],
}

2. dmScope - DM 会话隔离

json5
{
session: {
// 多人共用一个 WhatsApp 号，每人独立会话
dmScope: per-channel-peer,
// 同一用户跨频道合并会话
identityLinks: {
alice: [telegram:123456789, feishu:ou_xxx],
},
},
}

3. 飞书群组配置

json5
{
channels: {
feishu: {
dmPolicy: pairing,
groupPolicy: allowlist,
groupAllowFrom: [ocgroup1, ocgroup2],
groups: {
oc_group1: {
requireMention: true, // 需要 @机器人
allowFrom: [ouuser1, ouuser2], // 允许控制命令的用户
},
},
},
},
}

4. Agent 工具限制

json5
{
agents: {
list: [
{
id: family,
workspace: ~/.openclaw/workspace-family,
sandbox: { mode: all, scope: agent },
tools: {
allow: [read, exec],
deny: [write, edit, apply_patch, browser],
},
},
],
},
}

5. 会话维护

json5
{
session: {
maintenance: {
mode: enforce,
pruneAfter: 30d, // 30 天后清理
maxEntries: 500, // 最多 500 个会话
rotateBytes: 10mb, // sessions.json 超过 10MB 时轮转
},
},
}

快速参考

创建新 Agent 流程

1. 1. 创建工作空间

bash mkdir -p ~/openclaw-workspaces/ cd ~/openclaw-workspaces/ openclaw setup --workspace .

1. 2. 创建 Bootstrap 文件

bash # 必需文件 touch AGENTS.md SOUL.md TOOLS.md USER.md # 可选：初次运行引导 touch BOOTSTRAP.md

1. 3. 注册 Agent

bash openclaw agents create --workspace ~/openclaw-workspaces/

1. 4. 配置模型

bash openclaw agents config --model anthropic/claude-sonnet-4-5-20250929

核心配置文件

AGENTS.md - 工作流指令

定义 Agent 的行为规范、工作流程和自动化规则。

markdown

你的工作空间

每次会话前

1. 1. 阅读 SOUL.md — 你是谁
2. 阅读 USER.md — 你帮助谁
3. 阅读 memory/YYYY-MM-DD.md — 最近上下文

安全规则

• - 不泄露私密数据
• 破坏性操作前必须询问
• 使用 trash 而非 rm

工具使用

• - 检查技能的 SKILL.md
• 本地配置写在 TOOLS.md

SOUL.md - 角色人格

定义 Agent 的身份、语气、边界和原则。

markdown

你的身份

你是谁

• - 名称：[Agent 名称]
• 角色：[专业领域]
• 语气：[专业/友好/简洁]

原则

• - 主动但不打扰
• 准确优于快速
• 不确定时询问

TOOLS.md - 工具说明

记录工具的使用细节、集成要点和本地配置。

markdown

工具配置

本地工具

• - 浏览器：browser.enabled: true
• 沙箱：sandbox.enabled: false

集成细节

• - 数据库连接字符串
• API 端点配置
• 认证凭据位置

USER.md - 用户配置

定义用户偏好、联系方式和特殊需求。

markdown

用户信息

联系方式

• - 首选频道：WhatsApp / Telegram / Discord
• 时区：Asia/Shanghai
• 语言：中文

偏好

• - 回复风格：简洁/详细
• 主动检查：每日 2-4 次

Agent 目录结构

主 Agent (main)

~/.openclaw/agents/main/
├── agent/
│ ├── auth.json # 认证令牌
│ └── models.json # 模型配置
└── sessions/
└── .jsonl # 会话历史

专用 Agent

~/.openclaw/agents//
├── agent/
│ ├── auth.json
│ └── models.json
└── sessions/
└── .jsonl

多 Agent 路由

OpenCl