第6章 OpenClaw进阶配置与性能优化

本章前置检查：
□ OpenClaw已成功部署并运行（完成第2章内容）
□ 理解多Agent的基本概念（第3章）
□ 熟练使用Control UI（第5章）
□ 已配置至少一个消息渠道（飞书或Telegram）

本章预估总时长：5小时（含综合实践）

本章难点提示：

6.1节（子Agent的Spawn机制）是本章最需要理解透彻的部分。子Agent和持久Agent是两种完全不同的模式，混淆它们是新手配置多Agent协作失败的首要原因。
6.2节（Cron定时任务）中，时区设置是新手最容易忽略的坑——默认是UTC，如果你希望每天早上8点收到推送，需要显式设置--tz Asia/Shanghai。
6.3节（多渠道精细化路由）的绑定规则遵循“最具体优先”原则，理解这个原则能帮你快速定位路由失败的根因。
6.4节（性能监控与资源优化）的Token优化技巧，建议第5章之后有了Control UI的Usage面板再动手调，效果更直观。

🎯 本章教学目标：掌握子Agent的动态调度和持久Agent的配置方法，熟练使用Cron定时任务实现自动化，灵活配置多渠道路由规则，学会Token优化、Gateway状态监控和多Agent资源管理，能够独立排查OpenClaw常见故障。

6.1 子Agent：动态派发与隔离执行

🎯 本节目标：理解子Agent与持久Agent的区别，掌握子Agent的创建、调度和管理方法。

预计时长：1.5小时

6.1.1 核心认知：先分清持久Agent vs 子Agent

在开始配置之前，我们必须先分清两种多Agent协作模式——混淆这两种模式是多Agent协作配置失败的首要原因。

维度	持久Agent	子Agent（Sub-agent）
核心定义	独立存在的“常驻角色”，有专属配置、记忆空间与频道绑定	从主Agent会话中临时派生的“任务型角色”，依赖主Agent上下文
生命周期	永久运行（除非手动停止）	任务完成后自动归档（会话结束不保留）
配置文件	需配置workspace（独立工作目录）、bindings（路由绑定）	无需单独配置，通过`sessions_spawn`命令动态创建
适用场景	长期协作任务（如资讯收集、日常办公、群聊响应）	单次临时任务（如专项数据处理、短期调研、一次性代码开发）

关键结论：群聊协同、长期分工协作必须用“持久Agent”；临时补充任务（如主Agent处理不过来的单次任务）用“子Agent”-5。同一个项目里，两者完全可以混合使用——团队核心成员用持久Agent常驻，临时任务派发子Agent处理，既不占用常驻资源，又能灵活应对突发需求。

6.1.2 持久Agent的配置（回顾与深化）

我们在第3章已经详细学习了持久Agent的配置（AGENTS.md、SOUL.md、workspace等）。这里补充两个与本章相关的关键点：

1. 独立工作区配置

yaml

# ~/.openclaw/openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "news_collector",
        "workspace": "path/to/news_collector_workspace",
        "model": "anthropic/claude-3-sonnet"
      },
      {
        "id": "content_writer",
        "workspace": "path/to/content_writer_workspace"
      }
    ]
  }
}

每个Agent拥有独立的workspace，意味着记忆、技能、会话状态完全隔离。

2. 多渠道路由绑定

通过bindings字段将不同渠道的消息路由到不同Agent：

yaml

{
  "gateway": {
    "bindings": [
      {"channel": "telegram", "agent": "personal_assistant"},
      {"channel": "discord", "groupId": "guild:123", "agent": "team_assistant"},
      {"channel": "feishu", "groupId": "oc_xxxxx", "agent": "work_assistant"}
    ]
  }
}

路由规则遵循“最具体优先”原则——群组级别的绑定优先于渠道级别的绑定。

6.1.3 子Agent的核心原理

子Agent是从现有Agent运行中派生出来的后台智能体运行。它们在各自独立的会话中运行（agent:<agentId>:subagent:<uuid>），并在完成后将结果回报到请求者的聊天渠道。

每个子Agent运行都会被跟踪为一个后台任务，你可以通过/subagents斜杠命令来检查或控制当前会话的子Agent运行。

子Agent的设计目标：

并行化处理：“研究 / 长任务 / 慢工具”工作不会阻塞主运行
保持隔离：子Agent默认拥有独立的会话和（可选）沙箱隔离
防止滥用：子Agent默认不获得会话工具，不能生成子子Agent（避免无限嵌套）

龙马注：说到“不能生成子子Agent”，这里有一个坑要注意。OpenClaw默认不允许子Agent再派生自己的子Agent。但在较新的版本（如v2026.2.15-beta.1）中，可以通过设置agents.defaults.subagents.maxSpawnDepth: 2来允许子Agent生成自己的子Agent-。不过我建议：除非你真的非常确定需要多层嵌套，否则保持默认就好。嵌套太深，你追查起来会想撞墙。

成本说明：每个子Agent都有自己的上下文和Token使用量。对于繁重或重复的任务，建议为子Agent设置更便宜的模型，让主Agent使用更高质量的模型。配置方式见6.1.7节。

6.1.4 如何创建和调度子Agent

方式一：通过CLI命令

bash

# 基本语法
openclaw subagent spawn <agentId> <task描述>

# 示例：让子Agent执行数据采集任务
openclaw subagent spawn data_collector "抓取今天的热点新闻，保存到临时文件"

# 带模型覆盖
openclaw subagent spawn research_agent "分析沪深300走势" --model anthropic/claude-3-haiku

启动特点：

spawn命令是非阻塞的，会立即返回一个runId
子Agent在后台独立运行，主会话不会被阻塞
完成后，子Agent会将摘要/结果消息自动回报到请求者的聊天渠道

方式二：通过斜杠命令（在聊天会话中）

在任意与OpenClaw的对话中，直接输入：

/subagents spawn research_agent "帮我研究一下最新的AI Agent技术趋势"

其他常用斜杠命令：

命令	用途
`/subagents list`	列出当前会话的所有子Agent运行
`/subagents info <runId>`	查看指定子Agent的详细信息
`/subagents log <runId>`	查看子Agent的执行日志
`/subagents kill <runId>`	强制终止子Agent
`/subagents send <runId> <message>`	向运行中的子Agent发送消息

方式三：通过工具调用（在Skill或Agent工作流中）

在SKILL.md或AGENTS.md中，可以使用sessions_spawn工具以编程方式创建子Agent：

markdown

## 工作流
当用户请求深度研究时：
1. 使用sessions_spawn工具派生子Agent：`{"task": "深度研究主题X"， "agentId": "research_agent"}`
2. 立即返回runId，告知用户“正在后台研究中，稍后通知结果”

sessions_spawn支持以下参数：

参数	说明
`task`（必需）	子Agent要执行的任务描述
`agentId`	在哪个Agent的身份下创建子Agent
`label`	可选的标签，便于识别
`model`	覆盖子Agent使用的模型
`runTimeoutSeconds`	设置超时时间（秒），超时后自动中止
`cleanup`	完成后归档方式：`delete`（立即删除）或`keep`（保留）-1

6.1.5 子Agent的管理与监控

1. 查看子Agent状态

bash

# 列出所有子Agent
openclaw subagent list

# 查看特定子Agent的详细信息
openclaw subagent info <runId>

# 查看子Agent的执行日志
openclaw subagent log <runId>

2. 与运行中的子Agent交互

bash

# 向子Agent发送额外指令
openclaw subagent send <runId> "请补充近一年的数据"

# 调整子Agent的执行方向
openclaw subagent steer <runId> "重点关注国内市场"

3. 控制子Agent生命周期

bash

# 强制终止子Agent
openclaw subagent kill <runId>

# 终止所有子Agent
openclaw subagent kill all

4. 自动归档机制

子Agent会话在agents.defaults.subagents.archiveAfterMinutes分钟后会自动归档（默认：60分钟）-1。归档后，会话会被重命名为*.deleted.<timestamp>，但仍然保留转录文件以备审计。

如果设置了cleanup: "delete"，子Agent会在通告完成后立即归档（仍通过重命名保留转录）。设置runTimeoutSeconds可以强制停止超时的运行，但不会自动归档——会话会保留直到自动归档触发。

龙马注：archiveAfterMinutes这个参数我踩过坑。默认60分钟，但对于一些长时间运行的调研类子Agent来说，60分钟可能太短了。建议根据任务类型预估合理值：数据抓取类30分钟就够了，深度研究类可以设到2小时。另外，如果Gateway重启，待处理的归档计时器会丢失，所以尽量在任务开始时就设置好runTimeoutSeconds作为兜底。

6.1.6 子Agent的认证与权限配置

子Agent的认证按Agent ID解析，而不是按会话类型。这意味着：

子Agent继承了父Agent的认证配置
可以通过agents.list[].subagents按Agent配置特定的子Agent行为

配置子Agent的允许Agent列表：

yaml

# ~/.openclaw/openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "main_assistant",
        "subagents": {
          "allowAgents": ["research_agent", "data_collector"]  // 只允许从这些Agent派生
        }
      }
    ]
  }
}

如果设置allowAgents: ["*"]，则允许从任意Agent派生。默认情况下，子Agent只能从请求者所在的Agent派生。

6.1.7 子Agent的模型配置与成本控制

所有子Agent继承父Agent的默认配置，但可以通过以下方式独立配置子Agent的模型：

yaml

# ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "openai/gpt-4o-mini",  // 子Agent统一使用更便宜的模型
        "thinking": "basic"              // 子Agent的思考级别
      }
    }
  }
}

也可以在单个Agent上覆盖：

yaml

{
  "agents": {
    "list": [
      {
        "id": "main_assistant",
        "subagents": {
          "model": "anthropic/claude-3-haiku"  // 此Agent派生的子Agent使用Haiku
        }
      }
    ]
  }
}

龙马注：子Agent的模型配置是成本优化的利器。主Agent用Claude Opus做高难度决策，子Agent用便宜一档的模型做数据采集和整理。比如让Haiku去抓网页、读文件、跑SQL，主Opus只负责分析结论——效果接近，成本直接砍半甚至更多。

6.1.8 子Agent的界面聚焦（Focus模式）

OpenClaw还提供了一个实用的/focus命令。当子Agent数量较多时，你可以使用/focus将“焦点”切换到某个子Agent：

/focus <subagent-label|session-key|session-id|session-label>

聚焦后，你输入的消息会直接发送给该子Agent，而不是原来的主会话。用/unfocus退出聚焦模式，返回主会话。

这对调试子Agent、或在子Agent运行时需要与它持续沟通的场景非常有用。

6.2 Cron定时任务：让Agent主动干活

🎯 本节目标：掌握Cron定时任务的配置方法，让Agent在指定时间自动执行任务。

预计时长：1小时

6.2.1 为什么需要Cron

传统AI助手依赖于“被动响应”——你不问它不动。Cron让AI从“应答工具”升级为自主执行的7×24智能员工-6。固定时刻、固定周期、一次性提醒必须用Cron定时任务来实现。

Cron的核心特性：

运行在Gateway进程内部（不依赖模型运行时）
作业定义持久化保存在~/.openclaw/cron/jobs.json，重启不会丢失
可以将输出回传到聊天渠道或webhook端点
所有Cron执行都会创建后台任务记录

6.2.2 三种调度类型

类型	CLI标志	示例	说明
一次性	`--at`	`--at "2026-05-01T09:00:00Z"`	指定时间点执行一次；也支持相对时间如`20m`
固定间隔	`--every`	`--every 2h`	每2小时执行一次
Cron表达式	`--cron`	`--cron "0 9 * * *" --tz Asia/Shanghai`	5字段或6字段cron表达式

不带时区的时间戳按UTC处理。要按本地挂钟时间调度，必须显式指定--tz。

⚠️ 常见误区（时区） ：很多新手配置--cron "0 8 * * *"后，发现邮件在UTC时间8点收到，换算成北京时间是下午4点。所以一定要记得加上--tz Asia/Shanghai，否则它默认UTC时区，你的定时任务就会在你预期的时间之后好几个小时才执行。

Cron表达式速查表：

Crontab –	含义
`0 * * * *`	每小时的0分执行
`/15 * * *`	每15分钟执行一次
`0 9 * * 1-5`	工作日上午9点执行
`0 0 1 * *`	每月1日0点执行

6.2.3 实战命令

1. 添加定时任务

bash

# 一次性提醒：30分钟后提醒开会
openclaw cron add --name "Meeting Reminder" --at "30m" --message "30分钟后有团队会议"

# 每日定时任务：每天早上9点生成日报
openclaw cron add --name "Daily Report" --cron "0 9 * * *" --tz Asia/Shanghai --message "请生成今日工作日报"

# 固定间隔：每2小时检查一次新闻
openclaw cron add --name "News Check" --every "2h" --message "请抓取过去2小时的热点新闻并推送摘要"

龙马注：上面--cron "0 9 * * *"这个例子里，如果想把Cron表达式写进配置文件而不是每次打命令，可以按这个格式加："schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" }。写在配置文件里比敲命令行更容易版本控制。

2. 查看和管理定时任务

bash

# 列出所有定时任务
openclaw cron list

# 查看特定任务详情
openclaw cron show <job-id>

# 查看执行历史
openclaw cron runs --id <job-id>

# 删除任务
openclaw cron remove <job-id>

# 立即执行一次任务（测试用）
openclaw cron run <job-id> --now

3. 执行方式（session类型）

Cron任务支持四种执行方式，通过--session参数指定-8：

方式	适用场景
`main`（默认）	下一次心跳轮次执行，适合提醒、系统事件
`isolated`	专用独立会话，适合报告、后台杂务（推荐）
`current`	创建时绑定的会话，适合需要上下文的任务
`session:custom-id`	持久命名的会话，适合需要积累历史的任务

6.2.4 心跳机制（Heartbeat）与Cron的配合

除了Cron，OpenClaw还提供了Heartbeat心跳巡检机制——周期性自主检查，默认每30分钟触发一次，读取HEARTBEAT.md清单批量处理任务。

Heartbeat vs Cron：

机制	特点	适用场景
Cron	时间精确、定时明确	固定时刻、固定周期的精确执行
Heartbeat	模糊巡检、批量处理	多任务合并执行、需要历史上下文的日常检查

心跳配置示例（~/.openclaw/openclaw.json）：

json

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        }
      }
    }
  }
}

每日巡检任务清单示例（HEARTBEAT.md）：

markdown

# 每日自动化检查清单
- 检查邮箱是否存在紧急未读邮件
- 检索未来2小时日历会议并提前提醒
- 监控服务器/服务运行状态并异常告警

龙马注：我当时把Cron和Heartbeat搞混过两轮，后来记住一个粗暴的分类——如果你需要“必须在几点几分执行”，用Cron；如果你需要“每隔一段时间做一堆检查，但没严格几点”，用Heartbeat。

6.2.5 持久化与故障恢复

定时任务的定义存储在~/.openclaw/cron/jobs.json中，运行时执行状态存储在jobs-state.json中。

版本控制的建议：

将jobs.json加入Git追踪（这是任务定义）
将jobs-state.json加入.gitignore（这是运行时状态，不应纳入版本控制）
拆分后，旧版OpenClaw仍可读取jobs.json，但可能会将作业视为全新作业

一次性作业（--at）默认会在成功后自动删除，避免任务列表无限膨胀。

6.3 多渠道精细化路由

🎯 本节目标：掌握多渠道路由规则，实现不同渠道、不同群组绑定不同Agent。

预计时长：1小时

6.3.1 路由的基本原理

OpenClaw的路由是确定性的，由主机配置控制，模型不会选择渠道-。消息的渠道标识决定了它将被哪个Agent处理。

三种路由维度：

路由类型	绑定依据	示例场景
渠道级别	整个通信渠道	所有Telegram消息→个人助手Agent
群组级别	特定群组ID	Discord的#general频道→团队助手Agent
发送者级别	特定用户ID	家人发来的私信→家庭助理Agent

最具体规则优先原则：

群组级别的绑定 > 渠道级别的绑定
如果某个群组有专属配置，该群组的消息会被路由到指定Agent，而不会使用渠道默认配置

6.3.2 路由器配置详解

在~/.openclaw/openclaw.json的gateway.bindings数组中配置绑定规则：

json

{
  "gateway": {
    "bindings": [
      // 渠道级别：所有飞书私信默认由work_assistant处理
      {
        "channel": "feishu",
        "agent": "work_assistant"
      },
      // 群组级别：特定飞书群由team_lead处理（优先级高于渠道级）
      {
        "channel": "feishu",
        "groupId": "oc_5b6799cff4a754c15e5ff3025becc648",
        "agent": "team_lead"
      },
      // 发送者级别：特定用户由personal_assistant处理
      {
        "channel": "telegram",
        "senderId": "123456789",
        "agent": "personal_assistant"
      },
      // Discord频道绑定
      {
        "channel": "discord",
        "groupId": "guild:abc123",
        "agent": "team_assistant"
      },
      // WhatsApp群组绑定
      {
        "channel": "whatsapp",
        "groupId": "1234567890@g.us",
        "agent": "business_assistant"
      }
    ]
  }
}

关键限制：每个群组只能绑定一个Agent，不支持为一个群组配置多个Agent。

龙马注：这个群组绑定的限制我曾踩过坑。当时想把一个飞书群设为默认助手，另一个飞书群设置为专门的研发助手，结果发现第二个群的消息始终不响应——排查半天才发现groupId写错了。群ID不仅包括长字符串，还可能需要带上group:前缀。怎么确认？在群里@你的OpenClaw机器人，发/status，它会返回当前会话的channel和groupId。

6.3.3 多Agent会话隔离与身份链接

不同Agent的会话默认是完全隔离的——Agent A的记忆和上下文不会被Agent B访问，这在多渠道路由的场景下非常关键。

私信与群聊的隔离策略-：

私信（DM）隔离：默认情况下，所有私信共享一个会话，保持连续性。这对个人使用没有问题。
群组隔离：每个群组拥有独立的会话，实现不同团队之间的上下文完全隔离。
跨渠道身份链接：如果同一个人从多个渠道（如Telegram和飞书）同时联系你，可以使用session.identityLinks将他们的渠道身份链接起来，使他们在所有渠道共享同一个会话-。

身份链接配置示例：

json

{
  "session": {
    "identityLinks": [
      {
        "channel": "telegram",
        "senderId": "123456789",
        "linkTo": {
          "channel": "discord",
          "senderId": "987654321"
        }
      }
    ]
  }
}

6.4 性能监控与资源优化

🎯 本节目标：掌握OpenClaw的性能监控工具，学会Token优化和资源配置技巧。

预计时长：1小时

6.4.1 Token消耗监控

大多数性能问题并非来自AI模型本身，而是来自OpenClaw的配置方式。

1. 使用Control UI的Usage面板

第5章已详细介绍，最简单直观的方式——打开Control UI，右侧Usage面板会实时显示本次会话的Token消耗，输入Token数、输出Token数和总计一目了然。

2. 使用命令行查看Token统计

bash

# 查看整体Token使用情况
openclaw stats --today

# 查看特定Agent的Token使用
openclaw stats --agent <agentId> --week

# 查看Token消耗趋势
openclaw stats --verbose --format table

龙马注：我习惯跑一个定时任务每天自动生成Token报告——openclaw cron add --name "Daily Token Report" --cron "0 9 * * *" --tz Asia/Shanghai --message "请汇总昨天的Token使用情况，按Agent分类输出"。这样即使忙起来忘了看，也能每周复盘一次成本结构。

6.4.2 Token优化策略（5条可执行的省钱秘籍）

秘籍一：模型路由——按任务难度分配模型

不是所有任务都需要顶级模型。分类、摘要、格式化等简单任务用小型模型就够了，复杂推理才用高级模型-19。

yaml

# ~/.openclaw/openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "content_creator",
        "model": "openai/gpt-4o",           // 主Agent用高质量模型
        "subagents": {
          "model": "openai/gpt-4o-mini"      // 子Agent用经济型模型
        }
      }
    ]
  }
}

实践数据：子Agent用Haiku做数据采集，主Opus只做分析结论，效果接近，成本减半以上。

秘籍二：短时Tool输出裁剪（contextPruning）

这是实践到后期最有用的一条。contextPruning会按时间裁剪上下文中的tool输出，保持对话精简，可节省20-30%的Token。

yaml

# ~/.openclaw/openclaw.json
{
  "contextPruning": {
    "mode": "cache-ttl",
    "ttl": "5m"          # 超过5分钟的tool输出自动裁剪
  }
}

注意：这只影响发给LLM的上下文，不会删除磁盘上的对话历史记录（.jsonl文件保持完整）。

秘籍三：Memos智能记忆插件

Memos插件通过三大机制节省Token：

智能提取关键信息：自动过滤寒暄、重复表述，仅保存用户偏好、核心需求等有效信息
按需召回相关记忆：仅在需要时提取与当前任务相关的记忆片段
避免重复传输：已保存的关键信息无需反复发送

数据表明Memos能将Token消耗降低77%以上。

秘籍四：时间戳圆整（缓存命中率提升）

OpenClaw默认会在系统提示词中注入动态时间戳，这是缓存失效的头号杀手。每次时间变化，整个系统提示词的缓存都会失效。通过“时间戳圆整”技术，将动态时间按10分钟取整，缓存命中率大幅提升-。

秘籍五：清理冗余记忆

每个会话都会消耗Token，长时间运行后会话数量和记忆内容会不断膨胀：

bash

# 清理指定会话
openclaw session delete --session-id <sessionId>

# 清理所有孤立会话
openclaw session prune --older-than 30d

# 定期归档记忆（不删除，只移出活跃上下文）
openclaw memory archive --agent default

6.4.3 Gateway状态监控

基础监控命令：

bash

# 查看Gateway整体状态
openclaw gateway status

# 查看Gateway详细统计
openclaw gateway stats

# 查看实时事件流
openclaw gateway events --follow

# 检查Gateway健康度
openclaw gateway health

自动诊断工具：

bash

# 标准诊断（90%的问题在这里找到答案）
openclaw doctor

# 自动修复可处理的问题
openclaw doctor --fix

# 激进修复模式
openclaw doctor --repair

# 完整诊断报告（可安全分享）
openclaw status --all

6.4.4 预算限额与成本约束

1. 全局日预算（企业级成本管控）

在~/.openclaw/openclaw.json中添加：

json

{
  "gateway": {
    "budget": {
      "dailyLimit": 500000,      // 每日Token上限50万
      "alertThreshold": 0.9      // 90%用量时预警
    }
  }
}

配置验证：openclaw stats --budget --today

2. 单Agent独立限额

bash

# 进入Agent工作区
cd ~/.openclaw/agents/support-team-01

# 创建限额配置
touch budget.yaml

配置内容示例：

yaml

budget:
  dailyLimit: 100000        # 专属Agent日限额10万Token
  alertWebhook: "https://your-webhook-url"   # 超限告警地址

3. 预算超限自动告警

json

{
  "alerting": {
    "enabled": true,
    "webhook": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
    "conditions": ["daily_usage_90%", "daily_usage_100%"]
  }
}

启用后，预算使用率达到90%和100%时，系统会通过企业微信机器人等渠道自动推送警告信息-29。

6.4.5 并发管理与队列优化

OpenClaw通过一个极小的进程内队列将入站自动回复运行串行化，以防止多个Agent运行发生碰撞，同时仍允许跨会话的安全并行。

队列并发控制配置：

yaml

# ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "maxConcurrent": 4              // 同时运行的会话数（默认4）
    }
  },
  "messages": {
    "queue": {
      "mode": "collect",              // 收集多条消息合并处理
      "debounceMs": 1000,             // 安静等待1秒后再处理
      "cap": 20,                      // 每会话最多排队20条消息
      "drop": "summarize"             // 溢出时总结合并
    }
  }
}

队列模式说明：

模式	效果	适用场景
`collect`	短时间内的多条消息合并为一次处理	日常对话、避免碎片化回复
`followup`	当前轮次结束后加入队列	有序处理，不打断当前任务
`steer`	立即注入当前运行	紧急打断、方向纠正

龙马注：队列设置不能太极端。debounceMs: 1000是个不错的中间值；cap: 20意味着一个会话可以等20条消息——够用了；drop: "summarize"确保不会丢失。如果你发现聊天延迟明显，可以适当调小debounceMs试试。

6.5 故障排查与日志分析

🎯 本节目标：掌握OpenClaw的诊断工具链，能独立排查常见故障。

预计时长：0.5小时

6.5.1 标准诊断命令序列

遇到任何问题时，按以下顺序执行：

bash

# Step 1：检查整体服务状态
openclaw status

# Step 2：检查Gateway运行状态
openclaw gateway status

# Step 3：实时查看日志（保留这个终端窗口）
openclaw logs --follow

# Step 4：执行全面诊断
openclaw doctor

# Step 5：检查通信渠道连通性
openclaw channels status --probe

龙马注：“90%的问题都能从这三条命令的输出中找到答案”说得不夸张——openclaw status --all、openclaw doctor --repair、openclaw logs --follow这三条，基本覆盖了配置错误、端口冲突、API Key失效、渠道连不上这些高频故障。其他命令可以慢慢看日志查，但这三条是底线-35。

6.5.2 常见错误类型速查

错误类型1：服务无法启动

症状	可能原因	解决方案
Gateway启动后立即退出	端口被占用	`lsof -i :18789`确认占用；`kill -9 <PID>`或修改配置中的端口号
配置Schema校验失败	JSON格式错误或字段名拼写错误	`openclaw config unset <错误的键名>`重置，或对照下发的模板检查
Node.js版本过低	需22+	`node --version`确认，用nvm升级

龙马注：重复服务文件的坑我亲身经历过。升级OpenClaw后，系统级和用户级各生成一个服务文件，两个同名服务打架，一个占着端口好好的，另一个每5秒尝试启动、崩溃、重启循环不断——三天内狂崩4671次，但用户级服务又看上去正常，直到发现定时任务全漏跑4天。事后教训：升级完一定要执行systemctl list-units | grep openclaw确认只有一个服务在跑，多余的记得停掉禁用-21。

错误类型2：消息收到但不响应

bash

# 检查日志中是否有"drop"关键字
openclaw logs | grep "drop"

常见原因及解决方案：

原因	解决方案
DM策略限制未批准	检查`pairing list`，确保发送者已获批
群组未@机器人	确认群聊配置中`requireMention`的设置
API Key失效	`openclaw models status --probe`验证provider认证状态
模型配额用尽	切换备用模型或升级额度

6.5.3 日志配置与分析

日志Level设置：

yaml

# ~/.openclaw/openclaw.json
{
  "logging": {
    "level": "info",           // debug/info/warn/error
    "verboseChannels": false,  // 渠道详细日志（排查时打开）
    "maxFileSize": "50mb",
    "maxFiles": 10
  }
}

日志位置：

Linux/WSL2：~/.openclaw/logs/gateway.log
macOS：~/Library/Logs/OpenClaw/gateway.log

龙马注：渠道级别的问题（飞书没回调、消息收不到）不要上来就翻代码，先跑openclaw channels status --probe，大多数时候是配对或权限问题。企微、飞书、钉钉都会定期改变要求，先确认通道连通性再审视代码。

排查三板斧（遇到任何问题，执行以下命令）-35：

bash

openclaw status --all
openclaw doctor --repair
openclaw logs --follow

第6章第1篇综合任务

任务：完成以下所有检查项，记录输出和过程中遇到的问题。

🔰 入门任务（1小时） ：

创建一个子Agent，让它执行一个简单的任务（如“帮我计算50+50”）
使用/subagents list查看该子Agent的运行状态
创建一个Cron定时任务，每5分钟输出一次时间戳到日志
使用openclaw cron list验证任务已创建

🚀 进阶任务（2小时） ：

配置一个持久Agent，并为其绑定一个专门的飞书群组
配置一个子Agent，使用更便宜的模型（如gpt-4o-mini）完成一次数据采集任务
运行openclaw gateway stats查看Gateway统计信息
运行openclaw doctor诊断当前配置，修复任何可修复的问题
在Control UI中查看Token Usage，记录一次对话的Token消耗

🔧 优化任务（1小时） ：

分析你的一次普通对话，使用contextPruning配置将tool输出裁剪到5分钟TTL
对比优化前后的Token消耗变化（通过Usage面板）
运行openclaw security audit检查你当前的配置是否存在安全风险

完成后，保存一份诊断报告，命名为chapter6_diagnosis_report.txt，至少包含：

openclaw status --all的输出片段
你的Cron任务列表
你对Token优化所做的配置调整及效果对比
你遇到的问题和解决方法记录

第6章参考资料与扩展阅读

子智能体——OpenClaw官方文档 https://docs.openclaw.ai/zh-CN/tools/subagents
Sub-agents——OpenClaw官方文档（英文） https://docs.openclaw.ai/tools/subagents
定时任务（Cron）——OpenClaw官方文档 https://docs.openclaw.ai/zh-CN/automation/cron-jobs
命令队列——OpenClaw官方文档 https://docs.openclaw.ai/zh-CN/concepts/queue
玩转OpenClaw｜如何配置多个相互独立的Agent？ https://www.tencentcloud.com/techpedia/142821（配置持久Agent和路由绑定）
Mastering OpenClaw – How to Configure Multiple Independent Agents https://www.tencentcloud.com/techpedia/142826（路由原理和绑定规则）
7×24 AI自动化助手：OpenClaw定时任务精讲 https://developer.aliyun.com/article/1717614（Cron+Heartbeat双机制详解）
OpenClaw 2.6 调教实录：从崩溃 4671 次到省 50% token https://cloud.tencent.cn/developer/article/2629271（contextPruning等9项优化配置）
企业级部署成本控制：OpenClaw每日Token限额与预算预警设置 https://www.php.cn/faq/2350291.html（预算配置完整示例）
OpenClaw 问题排查全指南：从诊断命令到常见错误逐一击破
https://news.qiniu.com/archives/1773197728049（诊断命令序列和常见错误）
ArkClaw 运行快速排查手册
https://www.volcengine.com/docs/87732/2277056?lang=zh（排查三板斧和渠道故障处理）

龙马的评审（模拟）

“第6章的任务写法我很喜欢。很多教材只会教概念，不教‘怎么动手做、能交什么成果’。那种入门任务→进阶任务→优化任务的设计，正好对应三个学习阶段——刚开始时什么都陌生，先跑通最小功能；熟悉了再推配置深度；等全跑通了，最后才考虑成本和性能。这正是一人多Agent公司从‘搭起来’到‘用得好’的必经之路。另外补充一点：openclaw controller命令对于排查多Agent路由问题非常有用，可以显示每个Agent的绑定路由、优先匹配规则和当前会话绑定状态。排查‘消息被哪个Agent处理了’时直接加--verbose看路由决策，比猜配置强很多。”

沈飞的评审（模拟）

“量化场景里，Cron定时任务是用来收盘后跑回测、开盘前做准备的黄金搭档。我系统里有四个Cron：下午3点收盘后拉取成交明细、下午5点做当日损益对比、早晨8:30预热数据环境并归档前一日因子库、9:15推送开盘前风险简报——每个都有时区--tz Asia/Shanghai，千万别忘。另外关于contextPruning，交易Agent的tool输出（如最新报价）时效性极强，5分钟TTL很合适；但风控Agent的持仓数据可能半小时不变，调长TTL可以减少重复传输。Token优化是要权衡的，不同场景不同参数，没有‘万能配方’。”

下一章预告：第三篇开篇（第7章认识Hermes Agent）——从本章的多Agent协作进阶跳入Hermes的深度世界，你将学习Hermes的五层核心架构、闭环学习机制，以及“越用越聪明”的自我进化能力。这是从“连接型AI”到“学习型AI”的跨越，也是第五篇金融量化总攻前最重要的一环。

文章版权归作者所有，未经允许请勿转载。

THE END