1. 先把 OpenClaw 的 Gateway 和 Pi SDK 关系讲清楚OpenClaw 是一个自托管、多渠道、以 Gateway 为控制平面的智能体系统。你可以把它理解成一台“常驻的调度中枢”Gateway 负责统一接入消息渠道、节点设备、Web/CLI 控制面再把请求路由到嵌入式智能体运行时而真正执行 Agent Loop 的内核是 Pi SDK。对 Node.js/TypeScript 开发者来说想快速跑通并理解调用关系最小可用链路就是三件事启动 Gateway、让 Gateway 路由到 Pi SDK 运行时、用一次请求验证回显与日志。很多人第一次接触 OpenClaw 会误以为 Pi SDK 是外部进程需要单独起服务再通过 HTTP 调用。实际上官方 Pi 集成文档写得很明确OpenClaw 是直接importPi 的createAgentSession()进入进程内嵌执行而不是把 Pi 当成子进程。这个区别决定了你的调试方式——你不需要去抓两个进程之间的网络包而是要看 Gateway 进程内的日志、会话文件和工具调用链。这篇内容面向的是想快速跑通最小链路的开发者。我会给出可复制的环境变量与启动配置、Gateway 路由与 Pi SDK 调用示例并附三步验证动作本地启动、请求回显、日志核对。全程基于 Node.js 24 推荐、Node 22.14 也支持的运行环境。如果你只是想先看看模型对话效果可以先用模型对话页做一次纯模型验证但要走通 Gateway 到 Pi SDK 的完整链路还是得在本地把 Gateway 跑起来。需要提前说明一个边界OpenClaw 官方安全文档把它的安全姿态定义为“一个 Gateway 对应一个可信边界”并不把“互不信任用户共享同一 Gateway/Agent”视为受支持的安全边界。所以本文的配置默认绑定127.0.0.1不做公网暴露。这一点在后面的排障章节还会再强调因为很多“连不上”和“连上了但不安全”的问题都出在这里。2. TaoToken 前置把模型访问凭证准备好在跑通 Gateway 到 Pi SDK 之前你需要先解决模型访问这一层。OpenClaw 的模型调用最终会走 provider而 provider 需要 Base URL、API Key 和 Model ID 三件套。我这边习惯用 TaoToken 作为统一的模型接入层原因是它的接口形态和主流 OpenAI 兼容协议一致配置进 OpenClaw 的 auth profile 时不需要额外写适配代码。先到官网了解整体能力再进控制台创建 API Key。地址分别是官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建 Key 的时候注意两点。第一Key 只在创建时完整显示一次复制后立刻存进你的密钥管理工具不要直接写进会提交到 Git 的.env。第二如果你打算长期做编码类 Agent 任务可以顺带看一下 Coding Plan 的额度形态避免后面频繁换 Key 打断调试节奏Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteAPI 的基础地址是https://taotoken.net/api注意这个地址不带 UTM 参数直接作为 Base URL 使用。Model ID 按你实际要用的模型填比如对话类、编码类各有对应标识具体以控制台模型列表为准。接入文档在这里配置遇到不确定的字段可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite这里有个容易踩的坑OpenClaw 的 auth profile 支持多 provider、多 profile 加 cooldown 和 fallback chain。你完全可以把 TaoToken 配成主 profile再配一个备用 profile。但要注意 SecretRefs 的解析时机——官方说明是在激活期解析到内存快照运行期不再惰性取密。所以如果你改了环境变量需要触发一次原子热重载或者重启 Gateway否则进程里还是旧快照。3. 可复制配置环境变量、Gateway 启动与 Pi SDK 调用这一节是全文最核心的部分所有片段都可以直接复制。先建目录结构再写配置最后启动。3.1 环境变量与目录准备OpenClaw 默认把状态放在~/.openclaw下。会话转录与路由元数据在~/.openclaw/agents/agentId/sessionscron 作业在~/.openclaw/cron/jobs.json内建 memory 是每个 agent 一个 SQLite 文件日志是 JSONL。先确认 Node 版本node -v # 期望 v22.14.0 及以上推荐 v24.x然后准备环境变量。我建议用.env.local并在.gitignore里排除# .env.local TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的Key OPENCLAW_GATEWAY_HOST127.0.0.1 OPENCLAW_GATEWAY_PORT18789 OPENCLAW_LOG_LEVELdebug注意OPENCLAW_GATEWAY_HOST保持127.0.0.1。官方会阻止“非 loopback 且无 auth”的启动这是保护机制不要为了图方便改成0.0.0.0。3.2 auth profile 配置片段OpenClaw 的模型 auth profile 以文件形式存在。下面是一个 JSON 形态的 profile 配置示例字段名按你本地版本的实际 schema 对齐核心是三件套齐全{ profiles: [ { id: taotoken-primary, provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKeyRef: env:TAOTOKEN_API_KEY, modelId: 你的模型ID, cooldownMs: 30000, maxRetries: 3 } ], fallbackChain: [taotoken-primary] }这里apiKeyRef用env:前缀指向环境变量而不是把 Key 明文写进文件。官方支持 SecretRefs 的 env/file/exec 三种来源env 是最省事的一种。maxRetries默认 3 次、30 秒上限、10% jitter和官方 request 级重试策略一致。如果你更习惯 TOML 风格等价写法如下[[profiles]] id taotoken-primary provider openai-compatible base_url https://taotoken.net/api api_key_ref env:TAOTOKEN_API_KEY model_id 你的模型ID cooldown_ms 30000 max_retries 3 fallback_chain [taotoken-primary]3.3 启动 Gateway配置就位后启动 Gatewaynpx openclaw gateway正常启动后你会看到类似输出Gateway 监听127.0.0.1:18789加载了 auth profile注册了工具与插件context engine 解析成功。如果 context engine 插件注册失败官方明确说不会自动回退到 legacy而是 run 直接失败。所以启动日志里这一行要重点看。3.4 Pi SDK 调用示例Gateway 起来之后智能体执行层就是 Pi SDK 在进程内跑。下面是一个 TypeScript 片段演示如何通过 Gateway 的 WebSocket 控制面发一条消息并观察它路由到嵌入式 Pi 运行时的过程import WebSocket from ws; const ws new WebSocket(ws://127.0.0.1:18789); ws.on(open, () { ws.send( JSON.stringify({ type: message, sessionKey: dm:local:dev, content: 用一句话说明 Gateway 和 Pi SDK 的分工, }) ); }); ws.on(message, (data) { const evt JSON.parse(data.toString()); if (evt.type assistant_delta) { process.stdout.write(evt.delta); } if (evt.type run_complete) { console.log(\n[run complete], evt.usage); ws.close(); } }); ws.on(error, (err) { console.error(ws error:, err.message); });这段代码的关键点是sessionKey。OpenClaw 的 Session Router 会根据 DM/群聊/线程/cron/webhook 生成会话键同一会话先进入session:keylane 保证串行再进入全局 lane 受agents.defaults.maxConcurrent控制。你手动指定dm:local:dev是为了让多次调试落在同一个会话里方便对比上下文。如果你用的是 Claude Code 这类编码 Agent 形态配置逻辑是一样的三件套只是入口不同。可以参考 ClaudeCodeAnthropic 的接入说明ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite4. 三步验证本地启动、请求回显、日志核对配置写完不代表链路通了。我习惯用三步验证法每一步都有明确的通过标准。4.1 第一步本地启动启动 Gateway 后先确认端口在监听curl -s http://127.0.0.1:18789/health如果返回健康状态说明控制面 HTTP 能力正常。这一步失败通常是端口被占用或配置解析报错。端口占用换OPENCLAW_GATEWAY_PORT即可配置解析报错看启动日志里的 schema 校验信息多半是 auth profile 字段名写错。4.2 第二步请求回显用 3.4 的 WebSocket 脚本发一条消息观察是否收到assistant_delta和run_complete。通过标准是能收到流式增量且run_complete里带 usage 信息。如果只收到连接成功但没有 delta说明请求进了队列但 Agent run 没起来去查模型 provider 是否可达。4.3 第三步日志核对OpenClaw 的日志是 JSONL 文件。核对时重点看四类记录入站事件、session key 解析、工具调用、出站投递。官方 Messages 页给出的高层流程是Inbound message - routing/bindings - session key - queue - agent runstreaming tools- outbound replies。你的日志应该能对应上这条链。tail -f ~/.openclaw/logs/*.jsonl | grep -E session|run|tool通过标准是能看到同一个 session key 贯穿入站和出站工具调用有明确的 policy 过滤记录。如果日志里出现session.stuck相关指标说明某个 run 卡住了优先查工具执行是否超时。如果你还想验证纯模型侧是否正常可以先用模型对话页单独发一条排除是模型问题还是 Gateway 问题模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。下面四个是我在调试 OpenClaw Pi SDK 链路时遇到或见别人遇到最多的。5.1 401 Unauthorized最常见的原因是 API Key 没被正确解析。检查顺序环境变量是否在当前 shell 生效、apiKeyRef的env:前缀是否拼对、Gateway 是否在改环境变量后重启过。因为 SecretRefs 是激活期解析到内存快照你export了新 Key 但没重启进程里还是旧值。另外确认 Base URL 是https://taotoken.net/api不要多加路径后缀。5.2 local proxy failed这个报错通常出现在网络层。OpenClaw 默认绑定 loopback如果你在容器里跑127.0.0.1指向的是容器自身而不是宿主机。解决办法是把 Gateway 和调用方放在同一网络命名空间或者用 tailnet 做远程接入。官方支持的远程方式是 SSH tunnel、TLS/WSS、Tailscale Serve/Funnel不要用来源不明的转发工具。5.3 reading choices 相关报错这类报错一般出现在解析模型响应时说明返回体结构和预期不符。优先确认 Model ID 是否填错、provider 是否真的是 OpenAI 兼容形态。如果响应里没有choices字段多半是请求打到了错误的端点。核对接入文档里的请求示例确认路径和 header 都对。5.4 OAuth 相关报错如果你用的是需要 OAuth 的 providertoken 过期会直接报错。OpenClaw 的 auth profile 支持 cooldown 和 fallback但 OAuth 刷新失败不会自动帮你重新授权。处理方式是重新走一次授权流程或者把 TaoToken 这种 Key 形态的 profile 设为主 profile减少 OAuth 依赖。5.5 三件套自查表任何接入类报错先对照这张表检查项正确值常见错误Base URLhttps://taotoken.net/api多写/v1或带 UTMAPI Keyenv:TAOTOKEN_API_KEY引用明文写进配置文件Model ID控制台模型列表里的标识凭记忆手写拼错如果你用的是 CC Switch 或 Cline MCP 这类客户端同样要保证 Base URL、Key、Model ID 三件套完整缺一个都会在初始化阶段报错。6. 继续深入把链路用起来跑通最小链路之后下一步通常是把它接到真实任务上。如果你主要做编码类 Agent长期跑建议用 Coding Plan 的额度形态比按次调用更稳Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite需要管理多个 Key 或查看用量去控制台控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite配置字段拿不准就翻接入文档里面请求示例和参数说明比较全接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一个我自己的经验调试 OpenClaw 时把OPENCLAW_LOG_LEVEL设成debug然后盯住 session key 这一条线。Gateway 到 Pi SDK 的调用关系本质上就是“路由决定会话、会话决定队列、队列决定执行顺序”。你把 session key 的生成和流转看明白了剩下的工具策略、Memory 检索、模型回退都是挂在这条主线上的枝节。