1. 一条消息进来之后OpenClaw 到底在忙什么很多人第一次接触 OpenClaw会把它当成“能聊天、能调工具、还能跨平台干活”的智能助理。这个理解不算错但只看到了水面上的部分。真正让 OpenClaw 跑起来的是水面下那套围绕 Agent 构建的运行时网关系统也就是 Agent Runtime。你可以先记住一个核心检索词OpenClaw 是一个把消息入口、会话治理、上下文管理、技能调用、持久化存储和多 Agent 协作缝合在一起的 Agent Runtime Gateway。它适合谁适合那些已经用过基础 Agent 框架、想搞清楚“一条消息从进系统到出结果中间到底经历了什么”的开发者。我试过把一条消息从头跟到尾发现它和普通聊天机器人、传统工作流系统的差别不在于会不会聊天而在于背后有一整套完整链路消息接收、协议适配、路由分发、会话隔离、上下文组装、技能注入、流式执行、工具调用、持久化存储以及复杂任务下的多 Agent 协作。假设一个典型场景在钉钉里发来一句“帮我整理今天的重要邮件提炼待办并生成一份给老板的简报”。接下来我们就沿着这条消息看它如何从外部世界的一段文本变成一套真正被 Agent 执行起来的任务链路。整篇文章围绕四条主线展开Agent 调度、Gateway 转发、Skills 扩展、subAgent 协作。每条主线都会给出可复制的配置片段和逐项验证动作目标是让你在本地跑通一次完整调用链理解“小龙虾”各模块如何咬合。2. TaoToken 前置准备把模型入口先接稳在拆解 OpenClaw 内部链路之前有一个前置动作必须先做把模型调用入口接稳。因为 OpenClaw 的 Agent 执行阶段最终要落到一次真实的模型请求上如果这一步不通后面所有链路都只是纸上谈兵。这里我用 TaoToken 作为模型接入层。它的作用是提供一个统一的 API 入口让你在 OpenClaw 的配置里填一个 Base URL 和一个 Key就能把模型请求发出去。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先拿到两样东西API Key 和 Model ID。API Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Model ID 则取决于你想用哪个模型可以在模型对话页面先试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。拿到这两样之后OpenClaw 的模型配置就可以写成下面这样。注意 Base URL 填的是 https://taotoken.net/api 不要多加路径也不要带 UTM 参数因为这是给程序调用的接口地址。{ models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: 你的ModelID } } }这里有个容易踩的坑很多人会把 Base URL 写成 https://taotoken.net/api/v1 或者带上一堆查询参数结果请求直接 404。正确的做法是只填到 /api 这一层剩下的路径由 OpenClaw 的 provider 适配层去拼。如果你用的是 Claude Code 这类需要 Anthropic 协议的工具接入方式略有不同可以参考接入文档里的说明地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里会把 Base URL、Key、Model ID 三件套的填法讲清楚。前置准备做完之后你可以先做一次最小验证用 curl 直接打一次模型对话接口确认 Key 和 Model ID 是通的。命令大概长这样curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { model: 你的ModelID, messages: [{role: user, content: 说一句你好}] }如果返回里有 choices 字段说明模型入口已经通了。这一步看起来简单但它能帮你把“模型不通”和“OpenClaw 配置不对”这两类问题提前分开后面排障会省很多时间。3. Gateway 转发配置可复制的 settings 片段Gateway 是 OpenClaw 的核心运行时。它负责连接管理、请求接入、配置热加载、健康监控这些基础治理工作。换句话说真正让整个系统常驻运行、能接消息、能回消息、能维持状态的不是单个 Agent而是这个 Gateway。在 OpenClaw 里Gateway 的配置通常放在 settings 文件里。下面是一份可以直接复制的最小配置片段路径按你本地实际安装位置调整。我把它写成 TOML 格式因为 OpenClaw 的 Gateway 配置用 TOML 读起来更直观。[gateway] host 127.0.0.1 port 8787 logLevel info hotReload true [gateway.model] provider openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoTokenKey model 你的ModelID [gateway.session] maxConcurrent 8 laneTimeoutMs 120000 [gateway.dedupe] enabled true ttlMinutes 20这份配置里有几个关键点。host 和 port 决定 Gateway 监听在哪里本地调试用 127.0.0.1 就够了。hotReload 打开之后改配置不用重启进程。model 段就是上一节说的三件套Base URL、Key、Model ID。session 段的 maxConcurrent 是全局并发上限laneTimeoutMs 是单条会话车道的超时时间。dedupe 段控制幂等去重ttlMinutes 默认 20 分钟。配置写完之后启动 Gateway你应该能看到类似这样的日志[gateway] listening on 127.0.0.1:8787 [gateway] model provideropenai-compatible baseUrlhttps://taotoken.net/api [gateway] hot reload enabled [gateway] dedupe enabled ttl20m如果日志里 baseUrl 显示的不是你填的地址或者 provider 报 unknown那多半是配置段名写错了。OpenClaw 对配置段的层级比较敏感[gateway.model] 不能写成 [model]。接下来是 Agent 的绑定配置。Gateway 收到消息后要根据绑定规则决定交给哪个 Agent。下面这段 JSON 可以直接放进 bindings 配置里{ bindings: [ { agentId: assistant, match: { channel: dingtalk, accountId: my_bot } }, { agentId: vip-assistant, match: { channel: dingtalk, peer: { id: 1234567890 } } } ] }匹配优先级从高到低是精确对等体匹配、服务器加角色匹配、服务器匹配、通道账户级匹配、通道级匹配、默认 Agent。所以上面这段配置里来自 1234567890 的消息会走 vip-assistant其他走 assistant。Skills 的配置也在这一层。Skills 不是简单的一堆函数列表它更像是“先把一组可用能力的使用说明、调用边界、适用场景告诉模型再在模型决定调用时去连接真实工具实现”。配置片段大概长这样[skills] workspaceDir ~/.openclaw/workspace userDir ~/.openclaw/skills builtinDir ~/.openclaw/builtin-skills pluginDir ~/.openclaw/plugins [skills.safety] profileFilter true sandboxIsolation true subagentInherit true这三层安全策略管道很关键Profile 过滤决定技能能不能被当前 Agent 看到Sandbox 隔离决定技能能不能在受限环境里跑Subagent 继承决定子 Agent 能不能拿到父 Agent 的技能。三者都打开之后一个技能能不能被调用就不只是看它存不存在了。4. 验证请求跑通一次完整调用链配置写完接下来要验证。验证分三步先验证 Gateway 本身活着再验证模型请求能通最后验证一条完整消息能走完 Agent 执行链路。第一步验证 Gateway 健康状态。OpenClaw 一般会暴露一个健康检查接口curl http://127.0.0.1:8787/health正常返回应该是这样的{ status: ok, uptime: 123, model: connected, sessions: 0 }如果 model 显示 disconnected说明 Gateway 到 TaoToken 的请求没通。这时候先回到第 2 节的 curl 验证确认 Key 和 Model ID 没问题再检查 Gateway 配置里的 baseUrl 是不是写成了 https://taotoken.net/api 。第二步验证一次模型请求。OpenClaw 通常会提供一个调试入口让你直接发一条消息给指定 Agentcurl -X POST http://127.0.0.1:8787/debug/message \ -H Content-Type: application/json \ -d { agentId: assistant, sessionKey: assistant:main, text: 帮我整理今天的重要邮件提炼待办 }如果返回里能看到 started 状态然后过一会儿看到流式输出说明 Gateway 转发和 Agent 执行都通了。返回大概长这样{ status: started, sessionKey: assistant:main, messageId: msg_abc123 }第三步验证 subAgent 注册。subAgent 的创建通常走 sessions_spawn 工具。你可以在 Agent 配置里先注册一个子 Agent{ subagents: [ { id: research-agent, model: 你的ModelID, workspace: ~/.openclaw/workspace/research, allowedTools: [memory_search, memory_get, file_read], maxDepth: 2 } ] }注册完之后主 Agent 在遇到复杂任务时就可以 spawn 这个子 Agent。验证方式是发一条会触发拆解的消息然后看日志里有没有 subagent spawned 的记录[agent] main agent decided to spawn subagent [subagent] spawned idresearch-agent sessionKeyagent:assistant:subagent:uuid [subagent] task筛选重要邮件 [subagent] completed, result injected to main session看到这几行说明 subAgent 协作链路也通了。到这里一条完整调用链就跑通了消息进门、协议适配、去重拦截、路由分发、会话排队、上下文组装、技能注入、流式执行、响应投递、状态持久化。5. 常见报错排查401、local proxy failed、reading choices、OAuth链路跑通之后真正的工作才刚开始因为生产环境里出错是常态。下面这几类报错是我在调试 OpenClaw 时遇到频率最高的逐个说清楚怎么排查。第一类401 Unauthorized。这个最直接就是 Key 不对或者没带上。先检查 Gateway 配置里的 apiKey 是不是 sk- 开头有没有多余空格。然后确认请求头里带的是 Authorization: Bearer sk-xxx不是 Authorization: sk-xxx。如果 Key 是从控制台复制的注意别把前后引号也复制进去。还有一种情况是 Key 过期了去 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个。第二类local proxy failed。这个报错通常出现在 Gateway 启动阶段意思是本地代理层没起来。先检查端口是不是被占用了用 lsof -i :8787 看一下。如果端口被占改配置里的 port 就行。还有一种可能是 host 写成了 0.0.0.0 但本地防火墙拦了改成 127.0.0.1 试试。这个报错和模型请求无关纯粹是 Gateway 自身的网络层问题。第三类reading choices 相关报错。这个一般长这样cannot read property choices of undefined。意思是模型返回的响应体里没有 choices 字段。原因通常是 Base URL 写错了请求打到了错误的路径上返回了一个 HTML 错误页而不是 JSON。检查 baseUrl 是不是 https://taotoken.net/api 不要带 /v1也不要带查询参数。另外确认 Model ID 是真实存在的填错模型名有时也会返回非标准响应。第四类OAuth 相关报错。如果你用的是 Claude Code 这类需要 OAuth 的工具可能会遇到 OAuth token expired 或者 invalid grant。这类问题的根源是 OAuth 流程没走完或者 token 过期了。解决办法是重新走一遍授权流程具体步骤在接入文档里有地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意 OAuth 和 API Key 是两套认证体系不要混用。除了这四类还有一个高频问题是上下文溢出。报错大概是 context length exceeded。OpenClaw 对此有自动压缩机制当上下文接近模型限制时会把早期历史分块生成摘要用摘要替换早期历史同时保留最近几轮完整对话。如果压缩后仍然超限系统会尝试切换到上下文更大的模型或者降低 thinking 级别最终回退为提示用户重置会话。你可以在配置里调整压缩阈值[gateway.context] softLimitTokens 4000 hardLimitTokens 32000 compactionEnabled truesoftLimitTokens 是触发记忆刷新的软阈值hardLimitTokens 是硬上限。这两个值要根据你实际用的模型上下文窗口来调不要照搬。6. 把四条主线串起来Agent、Gateway、Skills、subAgent 如何咬合前面五节分别拆了 Gateway 配置、验证请求、报错排查现在把四条主线串起来看一遍你会更清楚“小龙虾”各模块是怎么咬合的。Agent 调度是主线。一条消息进来Gateway 先做协议适配把钉钉、飞书、Slack 这些异构消息清洗成统一的 MsgContext。然后 dispatchInboundMessage 做最终化处理补全缺失字段、标准化格式。接着路由系统根据绑定规则决定交给哪个 Agent生成 sessionKey进入会话车道排队。同一 sessionKey 的消息串行执行确保上下文连贯全局并发上限则防止整个运行时被打爆。Gateway 转发是骨架。它不只是转发请求还承担了去重、拦截、快速响应这些前置治理。去重靠 idempotencyKey格式是 {provider}|{accountId}|{sessionKey}|{peerId}|{threadId}|{messageId}默认 TTL 20 分钟。拦截处理的是 /stop 这类控制命令直接中断对应的 AbortController。快速响应则是先通过 WebSocket 返回 started 状态再异步执行后续处理避免前端一直等最终结果。Skills 扩展是能力层。系统从工作区、用户全局目录、内置目录、插件目录四个来源扫描技能文件然后经过 Profile 过滤、Sandbox 隔离、Subagent 继承三层策略管道最后把可用技能描述格式化为文本注入系统提示词。所以模型不是凭空想象自己能做什么而是在技能描述里判断有没有邮件处理能力、有没有摘要生成能力、需不需要调用子 Agent。subAgent 协作是协作层。主 Agent 遇到复杂任务时通过 sessions_spawn 创建子 Agent。系统先做嵌套深度检查、并发限制检查、允许列表检查、沙箱状态检查通过后生成唯一子会话键 agent:{agentId}:subagent:{uuid}应用模型配置和 thinking 级别为子 Agent 生成专门的系统提示词。子 Agent 完成后结果以内部事件方式重新注入主 Agent 会话供下一轮推理使用。这四条主线咬合在一起就形成了完整的执行链路消息源 → 协议适配 → 路由分发 → 会话构建 → Agent 执行 → 响应投递 → 状态持久化。OpenClaw 真正有价值的地方不是它能不能回答一句话而是它把一条消息从进入系统到完成执行做成了一条可治理、可扩展、可追踪、可恢复的 Agent Runtime 链路。如果你想把这条链路真正跑起来建议按这个顺序操作先去 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 拿 Key再去 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 确认 Model ID然后按第 3 节的配置片段把 Gateway 和 bindings 写好最后用第 4 节的验证命令逐项跑通。遇到报错就翻第 5 节四类高频问题基本能覆盖大部分场景。