AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗原件 ↓仓库 ↗

最近的错误日志 ​

journalctl --since "1 hour ago" --priority err --no-pager | tail -20


## 服务管理

当用户要求重启服务时：
1. 确认服务名称
2. 检查服务当前状态：`systemctl status <service>`
3. 确认用户意图："确定要重启 <service> 吗？"
4. 执行重启：`systemctl restart <service>`
5. 验证重启结果：`systemctl status <service>`
6. 记录操作到日志

第四步：配置路由和定时任务

json5
{
  "agents": {
    "list": [
      {
        "id": "devops",
        "workspace": "~/.openclaw/workspace-devops",
        "model": "anthropic/claude-sonnet-5",
        "skills": ["server-monitor", "summarize"],
      },
    ],
  },
  "bindings": [
    {
      "agent": "devops",
      "channel": "slack",
      "teamId": "T01234567",
      "channelId": "C-ops-channel",
    },
  ],
  "cron": {
    "enabled": true,
  },
}

通过 CLI 添加定时任务：

bash
openclaw cron add --name "health-check" --schedule "*/30 * * * *" \
  --agent devops \
  --prompt "执行服务器健康检查，如果发现异常，通过 Slack 通知 #ops 频道"

openclaw cron add --name "daily-report" --schedule "0 18 * * *" \
  --agent devops \
  --prompt "生成今日运维日报，发送到 Slack #ops 频道"

Agent 开发最佳实践 ​

1. SOUL.md 要具体，不要模糊

markdown
# 差的写法
你是一个助手，帮用户做事。

# 好的写法
你是一个 TypeScript 编程助手。
- 所有代码使用 TypeScript 严格模式
- 遵循 Airbnb 代码风格
- 函数必须有 JSDoc 注释
- 不使用 any 类型

2. 明确定义边界

在 SOUL.md 中明确说明 Agent 不应该做什么：

markdown
## 不要做的事
- 不要执行任何 Shell 命令
- 不要修改系统文件
- 不要回答跟你职责无关的问题
- 不要泄露其他用户的信息

3. 提供错误处理指引

markdown
## 异常处理
- 如果工具调用失败，告诉用户具体的错误信息
- 如果不确定答案，说"我不确定"而不是编造
- 如果用户的请求超出你的能力范围，建议他们联系人工支持

4. 定期审查和优化

每周检查一次：

  • Agent 的响应质量是否符合预期？
  • 有没有误触发或漏触发的情况？
  • Token 消耗是否合理？
  • SOUL.md 是否需要更新？

Agent 调试技巧 ​

开启详细日志 ​

bash
# 启动 Gateway 时开启 Agent 调试
openclaw gateway --verbose --agent-debug

# 或者在配置中开启
json5
{
  "logging": {
    "level": "debug",
  },
}

开启后，你会在日志中看到：

[AGENT] Message received from telegram:chat=-100123456789
[AGENT] Routing: matched binding → agent=social
[AGENT] Loading workspace: ~/.openclaw/workspace-social
[AGENT] Loading SOUL.md (tokens: 320)
[AGENT] Loading MEMORY.md (tokens: 150)
[AGENT] Loading skills: weather, goplaces, summarize
[AGENT] Total system prompt tokens: 1,850
[AGENT] Calling model: openai/gpt-5.2-mini
[AGENT] Model response received (tokens: 120, time: 1.2s)
[AGENT] Sending response to telegram:chat=-100123456789

常见问题排查 ​

问题：消息没有路由到正确的 Agent

排查步骤：

  1. 检查 bindings 配置是否正确：
bash
openclaw agents list

  1. 确认频道 ID 是否正确（Discord 和 Telegram 的 ID 格式不同）

  2. 检查是否有多个 Agent 绑定了同一个频道（先匹配的会生效）

  3. 查看路由日志：

bash
openclaw gateway --verbose 2>&1 | grep "AGENT.*Routing"

问题：Agent 的回复不符合 SOUL.md 的设定

排查步骤：

  1. 确认 SOUL.md 文件路径正确（在 Agent 的工作空间根目录下）

  2. 检查 SOUL.md 是否被正确加载：

bash
openclaw gateway --verbose 2>&1 | grep "Loading SOUL"

  1. SOUL.md 的指令是否太模糊？尝试用更具体的语言

  2. 是否有其他技能的指令覆盖了 SOUL.md 的设定？检查技能优先级

问题：Agent 的工具调用失败

排查步骤：

  1. 检查技能是否正确启用（查看 openclaw.json 中对应 Agent 的 skills 数组配置）

  2. 检查工具依赖是否安装（如 gh、ffmpeg）

  3. 检查权限配置（确认工具在沙箱 allowlist 中）

  4. 查看工具调用日志：

bash
openclaw gateway --verbose 2>&1 | grep "Tool call"

问题：Agent 之间的共享文件不同步

排查步骤：

  1. 确认共享目录存在且两个 Agent 都有读写权限

  2. 检查定时任务的执行顺序（写入 Agent 必须先于读取 Agent 执行）

  3. 查看会话日志（使用 sessions_history 工具或检查 Gateway 日志）

使用 WebChat 调试 ​

WebChat 是调试 Agent 最方便的工具。你可以在浏览器中直接跟任意 Agent 对话：

bash
# 启动 Gateway（如果还没启动）
openclaw gateway --port 18789

# 打开浏览器访问
# http://localhost:18789/chat?agent=coding
# http://localhost:18789/chat?agent=social

通过 URL 参数 ?agent=<agentId> 可以指定跟哪个 Agent 对话，方便逐个测试。

常见问题 ​

Q1：最多能创建多少个 Agent？ ​

没有硬性限制，但每个 Agent 都会占用一些磁盘空间（工作空间、会话历史、记忆文件）。实际使用中，3-5 个 Agent 是比较常见的配置。超过 10 个 Agent 可能会让管理变得复杂。

Q2：Agent 之间能共享记忆吗？ ​

默认不能。每个 Agent 有独立的 MEMORY.md 和每日日志。如果你需要共享某些信息，可以：

  1. 把共享信息写入公共目录（如 ~/.openclaw/shared/）
  2. 在每个 Agent 的 SOUL.md 中指示它读取公共目录
  3. 手动复制记忆文件（不推荐，容易冲突）
  4. 使用 Memory Wiki 插件（memory-wiki，v2026.4.12+ 可用）-- 提供结构化的知识页面层，支持确定性的页面组织和跨 Agent 共享查询。详见官方文档 memory-wiki
  5. 使用 Honcho 后端 -- 支持跨会话、多 Agent 感知的记忆系统

Q3：能不能让一个 Agent 调用另一个 Agent？ ​

可以。OpenClaw 提供了 Sessions 工具来实现 Agent 间的直接通信：

  • sessions_list -- 发现活跃会话
  • sessions_send -- 向另一个会话发消息（支持 reply-back ping-pong 和 announce step 模式）
  • sessions_spawn -- 生成新的 Agent 会话

如果不需要实时通信，也可以使用定时任务 + 共享文件的方式（参见"Agent 间通信机制"章节）。

Q4：删除 Agent 会丢失数据吗？ ​

删除 Agent 会移除 Agent 的状态目录（~/.openclaw/agents/<agentId>/），但不会删除工作空间目录。你的 SOUL.md、记忆文件、技能文件都还在。如果要彻底清理，需要手动删除工作空间目录。

Q5：多个 Agent 绑定同一个频道会怎样？ ​

只有第一个匹配的 Agent 会处理消息。如果你不小心把两个 Agent 绑定到了同一个频道，检查 openclaw.json 中 agents.list 的顺序 -- 排在前面的 Agent 优先匹配。

Q6：Agent 的会话是独立的吗？ ​

是的，完全独立。coding Agent 的对话历史不会出现在 social Agent 的上下文中。这是设计如此 -- 保证每个 Agent 的上下文干净、专注。

Q7：如何迁移 Agent 到另一台机器？ ​

复制以下目录到新机器：

bash
# Agent 状态（认证凭证、会话历史）
~/.openclaw/agents/<agentId>/

# Agent 工作空间（SOUL.md、记忆、技能）
~/.openclaw/workspace-<agentId>/

然后在新机器的 openclaw.json 中添加对应的 Agent 配置。

Q8：多 Agent 模式下 Gateway 的资源消耗会增加吗？ ​

Gateway 本身的资源消耗不会显著增加。Agent 是按需加载的 -- 只有收到消息时才会激活对应的 Agent。空闲的 Agent 不占用 CPU 和内存。主要的额外消耗来自：

  • 磁盘空间：每个 Agent 的工作空间和会话历史
  • AI API 调用：每个 Agent 独立计费

v2026.4.20+ 优化了插件启动性能（冷启动时间降低约 74%，依赖加载时间降低 82-90%），多 Agent 场景下 Gateway 的首次响应速度明显改善。

Q9：能不能动态创建和销毁 Agent？ ​

Agent 的创建需要通过 CLI 命令（openclaw agents add）。但在运行时，Agent 可以通过 sessions_spawn 工具动态生成新的会话，实现临时任务的分发。

下一步 ​

多 Agent 协作搞定！去 09. Docker 部署 学习如何把 OpenClaw 容器化部署到服务器上！