Openclaw Agent Builder
by @a12591771
Use when creating OpenClaw agents, configuring workspaces, multi-agent routing, session isolation, or channel bindings.
clawhub install openclaw-agent-builder📖 About This Skill
name: openclaw-agent-builder description: Use when creating OpenClaw agents, configuring workspaces, multi-agent routing, session isolation, or channel bindings. metadata: openclaw: emoji: "🦞" homepage: https://docs.openclaw.ai/concepts/agent.md
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 - 消息路由
{
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 会话隔离
{
session: {
// 多人共用一个 WhatsApp 号，每人独立会话
dmScope: "per-channel-peer",
// 同一用户跨频道合并会话
identityLinks: {
alice: ["telegram:123456789", "feishu:ou_xxx"],
},
},
}
#### 3. 飞书群组配置
{
channels: {
feishu: {
dmPolicy: "pairing",
groupPolicy: "allowlist",
groupAllowFrom: ["oc_group1", "oc_group2"],
groups: {
"oc_group1": {
requireMention: true, // 需要 @机器人
allowFrom: ["ou_user1", "ou_user2"], // 允许控制命令的用户
},
},
},
},
}
#### 4. Agent 工具限制
{
agents: {
list: [
{
id: "family",
workspace: "~/.openclaw/workspace-family",
sandbox: { mode: "all", scope: "agent" },
tools: {
allow: ["read", "exec"],
deny: ["write", "edit", "apply_patch", "browser"],
},
},
],
},
}
#### 5. 会话维护
{
session: {
maintenance: {
mode: "enforce",
pruneAfter: "30d", // 30 天后清理
maxEntries: 500, // 最多 500 个会话
rotateBytes: "10mb", // sessions.json 超过 10MB 时轮转
},
},
}
快速参考
创建新 Agent 流程
1. 创建工作空间
mkdir -p ~/openclaw-workspaces/
cd ~/openclaw-workspaces/
openclaw setup --workspace .
2. 创建 Bootstrap 文件
# 必需文件
touch AGENTS.md SOUL.md TOOLS.md USER.md
# 可选：初次运行引导
touch BOOTSTRAP.md
3. 注册 Agent
openclaw agents create --workspace ~/openclaw-workspaces/
4. 配置模型
openclaw agents config --model anthropic/claude-sonnet-4-5-20250929
核心配置文件
AGENTS.md - 工作流指令
定义 Agent 的行为规范、工作流程和自动化规则。
# 你的工作空间每次会话前
1. 阅读 SOUL.md — 你是谁
2. 阅读 USER.md — 你帮助谁
3. 阅读 memory/YYYY-MM-DD.md — 最近上下文安全规则
不泄露私密数据
破坏性操作前必须询问
使用 trash 而非 rm 工具使用
检查技能的 SKILL.md
本地配置写在 TOOLS.md
SOUL.md - 角色人格
定义 Agent 的身份、语气、边界和原则。
# 你的身份你是谁
名称：[Agent 名称]
角色：[专业领域]
语气：[专业/友好/简洁] 原则
主动但不打扰
准确优于快速
不确定时询问
TOOLS.md - 工具说明
记录工具的使用细节、集成要点和本地配置。
# 工具配置本地工具
浏览器：browser.enabled: true
沙箱：sandbox.enabled: false 集成细节
数据库连接字符串
API 端点配置
认证凭据位置
USER.md - 用户配置
定义用户偏好、联系方式和特殊需求。
# 用户信息联系方式
首选频道：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 路由
OpenClaw 支持为不同任务创建隔离的 Agent 会话：
// ~/.openclaw/openclaw.json
{
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: "anthropic/claude-sonnet-4-5-20250929",
timeoutSeconds: 600,
},
// 多 Agent 配置
entries: {
"finance": {
workspace: "~/openclaw-workspaces/finance",
model: "anthropic/claude-sonnet-4-5-20250929",
},
"supervisor": {
workspace: "~/openclaw-workspaces/supervisor",
model: "anthropic/claude-opus-4-5-20250929",
},
},
},
}
会话管理
会话存储
会话历史以 JSONL 格式存储：
~/.openclaw/agents//sessions/.jsonl
会话工具
# 列出所有会话
openclaw sessions list查看会话历史
openclaw sessions history 创建新会话
openclaw sessions new --agent 删除会话
openclaw sessions delete
技能系统
技能加载顺序
1. 工作空间技能 (~/.openclaw/skills)
3. 捆绑技能 (安装包自带) - 最低优先级
技能配置
// ~/.openclaw/openclaw.json
{
skills: {
entries: {
"skill-name": {
enabled: true,
apiKey: "YOUR_API_KEY",
env: {
"API_KEY": "value",
},
config: {
"customSetting": "value",
},
},
},
load: {
watch: true, // 自动刷新技能
watchDebounceMs: 250,
},
},
}
创建自定义技能
mkdir -p ~/.openclaw/skills/
touch ~/.openclaw/skills//SKILL.md
SKILL.md 格式：
---
name: skill-name
description: 使用当...（具体触发条件）
metadata:
{
"openclaw": {
"requires": { "bins": ["uv"], "env": ["API_KEY"] },
},
}
Skill Name
概述
核心原则简述何时使用
触发条件 1
触发条件 2 快速参考
| 场景 | 操作 |
|------|------|
| 情况 A | 执行 X |示例
代码示例或工作流程
Agent Loop 流程
OpenClaw Agent 执行循环：
1. 接收消息 → 2. 加载会话 → 3. 组装上下文 →
4. 构建 Prompt → 5. 模型推理 → 6. 执行工具 →
7. 流式响应 → 8. 持久化会话
Hook 点
{
hooks: {
// Agent 生命周期
"agent:bootstrap": ["script.sh"],
"agent_end": ["script.sh"],
// 工具执行
"before_tool_call": ["script.sh"],
"after_tool_call": ["script.sh"],
// 消息处理
"message_received": ["script.sh"],
"message_sending": ["script.sh"],
},
}
模型配置
配置模型
# 为 Agent 配置模型
openclaw agents config --model /可用模型
openclaw models list
模型故障转移
{
agents: {
defaults: {
models: [
"anthropic/claude-sonnet-4-5-20250929",
"openai/gpt-4o",
"openrouter/anthropic/claude-3.5-sonnet",
],
},
},
}
沙箱模式
启用沙箱
{
agents: {
defaults: {
sandbox: {
enabled: true,
docker: {
image: "node:22-alpine",
setupCommand: "apk add --no-cache git python3",
},
workspaceRoot: "~/.openclaw/sandboxes",
},
},
},
}
沙箱技能要求
技能需要在沙箱内外都存在：
1. 主机：检查二进制文件
2. 沙箱：通过 setupCommand 安装依赖
记忆系统
每日记忆
mkdir -p ~/.openclaw/workspace/memory
touch ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md
长期记忆
MEMORY.md 仅在主会话加载，用于存储：
记忆升级
当学习具有广泛适用性时，升级到相应文件：
| 学习类型 | 升级到 |
|---------|--------|
| 行为模式 | SOUL.md |
| 工作流改进 | AGENTS.md |
| 工具技巧 | TOOLS.md |
心跳机制
配置心跳
{
agents: {
defaults: {
heartbeat: {
enabled: true,
intervalMinutes: 30,
prompt: "HEARTBEAT.md",
},
},
},
}
心跳检查清单
创建 HEARTBEAT.md：
# 心跳检查[ ] 检查紧急邮件
[ ] 查看 24 小时内日历事件
[ ] 检查天气（如有外出计划）
[ ] 无重要事项回复 HEARTBEAT_OK
常见问题
Agent 无法启动
1. 检查工作空间是否存在
2. 验证 openclaw.json 配置
3. 查看日志：openclaw logs
技能未加载
1. 检查技能名称匹配
2. 验证 enabled: true
3. 确认环境变量/二进制文件存在
会话历史丢失
1. 检查 agents/ 目录
2. 验证 JSONL 文件格式
3. 确认 Agent ID 正确
最佳实践
1. 为专用任务创建独立 Agent - 财务、监控、开发等
2. 使用工作空间技能覆盖捆绑技能 - 自定义行为
3. 定期清理会话历史 - 避免存储膨胀
4. 记录学习日志 - 使用 .learnings/ 目录
5. 配置心跳主动检查 - 而非被动响应
6. 使用沙箱运行不受信代码 - 安全第一
配置请求（交互式）
创建新 Agent 前，向用户请求以下信息：
必填项
1. Agent 名称/ID（用于标识，如：finance, supervisor, dev）
2. 工作空间路径（默认：~/openclaw-workspaces/）
3. 使用场景（如：财务管理、代码开发、群组机器人）
可选项（根据场景询问）
4. 是否需要绑定特定频道/群组？
→ 是：询问频道类型 (feishu/whatsapp/telegram) 和 ID
5. 是否需要多 Agent 路由？
→ 是：询问 bindings 配置
6. 是否需要安全沙箱？
→ 是：配置 sandbox.mode: "all"
7. 是否需要限制工具权限？
→ 是：配置 tools.allow/deny
8. 多人使用同一个聊天账号？
→ 是：配置 dmScope: "per-channel-peer"
9. 同一用户需要跨频道共享会话？
→ 是：配置 identityLinks
请求模板
创建 Agent 配置请求请提供以下信息：
必填：
Agent 名称：[用于标识，如 finance/supervisor]
用途：[简要描述，如"财务管理"或"飞书群组机器人"] 可选：
[ ] 需要绑定特定飞书群/用户
[ ] 需要多 Agent 路由（多个聊天账号）
[ ] 需要安全沙箱隔离
[ ] 需要限制工具权限
[ ] 多人共用聊天账号（需要 dmScope 隔离） 请回复或逐项提供，我将生成完整配置。
部署检查清单
创建新 Agent 后验证：
参考文档：
📋 Tips & Best Practices
Agent 无法启动
1. 检查工作空间是否存在
2. 验证 openclaw.json 配置
3. 查看日志：openclaw logs
技能未加载
1. 检查技能名称匹配
2. 验证 enabled: true
3. 确认环境变量/二进制文件存在
会话历史丢失
1. 检查 agents/ 目录
2. 验证 JSONL 文件格式
3. 确认 Agent ID 正确