1. 从零跑通 OpenClawCLI 安装、Gateway 启动与第一句 Hello 的完整链路OpenClaw 是一个用 TypeScript 写的开源个人 AI 助手框架它能把你日常用的聊天工具Slack、Discord、iMessage、WebChat 等接到一个常驻的 Gateway 进程上再由 Agent Runtime 调度模型和技能来干活。适合谁想在自己机器上跑一个「能收发消息、能调工具、能接多通道」的本地 AI 助手的开发者。这篇不抄官方 Getting Started而是站在架构视角把 CLI 安装、Gateway 启动、第一条消息从发出到回显的调用链讲清楚每一步都给可复制的命令和配置片段。你跟着做完本地会跑通第一句 Hello并且知道这句话在源码里经过了哪些模块。我试过在一台干净的 Linux 机器上从零走一遍踩了几个坑Node 版本、pnpm workspace、Gateway 端口占用下面按顺序说。1.1 环境要求为什么是 Node 22 和 pnpm MonorepoREADME 写得很直接运行时需要 Node 22 以上。原因是 OpenClaw 用了较新的 Node API比如原生 fetch、部分 ESM 加载行为低版本会在启动 Gateway 时直接抛错。先确认版本node -v # 期望输出 v22.x.x 或更高 pnpm -v # 期望 9.x 以上如果 Node 版本不够用 nvm 切一下nvm install 22 nvm use 22仓库是典型的 Monorepo里面有apps/、packages/、skills/等子包用 pnpm workspace 管理。这种结构的好处是内部库可以互相引用共享类型定义和工具函数同时 Gateway、UI、Extensions 又能各自独立构建和测试。全局安装和源码安装对应两种角色全局安装一条命令搞定适合先体验源码安装适合想读实现、改代码的人。你在本地选了哪种某种程度上也决定了你后面读源码的视角。1.2 全局安装一条命令拿到 openclaw CLI最省事的方式是全局装npm install -g openclawlatest # 或者 pnpm add -g openclawlatest装完验证openclaw --version openclaw --help--help会列出子命令onboard、gateway、agent、message等。这里先记住一个架构事实CLI 本身是「薄封装」它不常驻只负责解析参数、读写配置、然后通过 HTTP/WS/RPC 去调用已经在跑的 Gateway。真正长期活着的是 Gateway 守护进程。如果你想从源码构建那就 clone 下来之后跑pnpm install pnpm ui:build pnpm buildui:build单独拎出来是因为 Web 控制台是独立构建产物Gateway 启动时会去读它。2. openclaw onboard 向导模型、认证与守护进程到底写了什么推荐的第一步是跑这个命令openclaw onboard --install-daemon从用户视角看这就是个交互式向导——帮你选模型提供商Anthropic、OpenAI、本地模型等指导你完成 OAuth 或 API Key 配置设好 Gateway 的端口和安全选项再选好要接入的第一批聊天通道。但从架构视角看它做的是「集中写入配置 安装守护进程」两件事。2.1 配置中心初始化模型列表、通道、网关地址向导会生成或更新核心配置文件通常是 JSON/YAML/Env 的组合。内容包括模型列表与优先级后面做 Model Failover 会用到、通道配置Slack App Token、Discord Bot Token、网关监听地址和端口、安全策略比如 DM pairing 策略。模型的认证信息、使用上限、偏好也在这一步落地之后 Agent Runtime 就是靠这些信息选模型和做 Failover 的。一个典型的配置片段长这样路径以实际生成为准这里示意结构{ gateway: { host: 127.0.0.1, port: 18789 }, models: [ { provider: anthropic, model: claude-sonnet-4-20250514, apiKeyEnv: ANTHROPIC_API_KEY, priority: 1 } ], channels: { slack: { enabled: false } } }注意apiKeyEnv这种写法——它不把 Key 明文写进配置而是引用环境变量这是安全上的基本操作。2.2 守护进程安装launchd 与 systemd向导的第二个动作是装守护进程。在 macOS 上它往 launchd 写一个用户级服务在 Linux 上用 user-level systemd 服务。这样一来Gateway 即使你关掉终端也能常驻运行随时响应各种聊天通道的消息。装完之后你可以查状态# Linux systemctl --user status openclaw-gateway # macOS launchctl list | grep openclaw如果你只想临时调试可以强制在前台跑一份 Gatewayopenclaw gateway --port 18789 --verbose--verbose会把事件流和错误日志打到终端排障时非常有用。守护进程版本则是平时默默工作的那一份两者用的是同一套配置。3. Gateway 配置片段与可复制启动参数Gateway 是整个系统的控制平面Control Plane。它管理会话、通道和节点的生命周期负责把事件分发给不同的 Agent 和 Skills也承担安全检查、限流、审计这些活。你可以把它想象成一座城市的交通指挥中心所有的车消息、路通道、路口技能和节点、红绿灯策略最后都要经过这儿。3.1 一份可直接用的 Gateway 配置下面这份配置把监听地址、端口、日志级别、默认模型都写全了你可以直接落到配置文件里路径按你实际安装位置调整通常在用户配置目录下的openclaw/config.json{ gateway: { host: 127.0.0.1, port: 18789, logLevel: info, webConsole: true }, agent: { defaultModel: claude-sonnet-4-20250514, maxContextTokens: 180000 }, security: { dmPairing: strict } }三个关键点host用127.0.0.1只监听本机别一上来就0.0.0.0webConsole打开后能在浏览器看通道、Session、技能、任务状态dmPairing设成strict表示陌生私聊需要配对确认避免被乱发消息。3.2 启动 Gateway 并确认监听openclaw gateway --port 18789 --verbose看到类似下面的输出就说明起来了[gateway] listening on 127.0.0.1:18789 [gateway] web console available at http://127.0.0.1:18789 [gateway] loaded 1 model, 0 channelsloaded 1 model, 0 channels是正常的——你还没接聊天通道。接下来先不接通道直接用 CLI 发一条消息验证链路。4. 验证请求从 CLI 发出第一句 Hello 并看到回显Onboarding 完成、Gateway 起来之后最直接的验证方式是用 CLI 发消息openclaw message send --to 1234567890 --message Hello from OpenClaw这条命令背后发生的事就是本篇要讲的核心链路。CLI 解析参数后通过 HTTP/WS 连到已经在跑的 Gateway把消息投进去。Gateway 收到后resolveSession(msg)找到或创建会话resolveAgentFor(session)为该会话选定 AgentloadContext(session)加载历史对话、记忆agent.think({ msg, context })让 Agent加模型决定下一步executePlan(plan)执行计划可能调用 Skills、Browser、NodessendReply(msg.channel, msg.peer, result)通过对应 Channel 回写结果persistSession(session, msg, result)更新会话状态、写日志。用一段高度简化的伪代码描述 Gateway 侧的主干逻辑// 伪代码Gateway 对入站消息的处理轮廓 async function handleInboundMessage(msg: InboundMessage) { const session await resolveSession(msg); const agent await resolveAgentFor(session); const context await loadContext(session); const plan await agent.think({ msg, context }); const result await executePlan(plan); await sendReply(msg.channel, msg.peer, result); await persistSession(session, msg, result); }而 CLI 侧的主入口逻辑轮廓是这样// 伪代码openclaw CLI 主入口的逻辑轮廓 async function main(argv: string[]) { const cmd parseCommandLine(argv); const config await loadConfig(); switch (cmd.name) { case onboard: await runOnboardingWizard(config); break; case gateway: await startGatewayProcess(config, cmd.options); break; case message: const gw await connectToGateway(config.gatewayUrl); await gw.sendMessage({ to: cmd.to, text: cmd.text }); break; } }这段伪代码刻意淡化了实现细节只想说明几个关键点CLI 本身并不持久驻留它更像「帮你发指令」的一层薄封装长期运行的是 Gateway 守护进程两者通过远程调用对话绝大多数真正的业务逻辑——路由、会话管理、Agent 调用、技能执行——都发生在 Gateway 内部。4.1 用 Web 控制台看事件流打开http://127.0.0.1:18789你能看到刚才那条消息的 Session 记录、模型调用、Token 消耗。这一步很关键——它把「黑盒」变成了「可观测」。开发的时候用它观察事件流和错误日志比翻日志文件快得多。4.2 内置聊天命令不消耗 Token 的快捷控制除了自然语言对话OpenClaw 还内置了一批以/开头的快捷控制命令可以在任意已连接的聊天界面直接发送。这些命令在 Gateway 的消息处理逻辑中会在路由到 Agent 之前被拦截匹配上了就直接执行对应的 Session 操作不进入模型推理流程所以响应几乎是即时的也不消耗 Token。常用命令速查命令作用/status显示当前 Session 状态模型、Token 消耗、Cost 等/new或/reset重置当前 Session清空对话历史/compact压缩 Session 上下文生成摘要释放 Token/think level调整思考深度off minimal low medium high xhigh/verbose on|off开启/关闭详细输出模式/usage off|tokens|full控制每条回复后面附加的用量信息/restart重启 Gateway 进程Owner 专用/activation mention|always切换群组激活方式仅在群组中有效/think用来调整模型的推理深度适用于支持 extended thinking 的模型。简单查询用off复杂的编程或分析问题上high根据任务难度动态调就行。/compact解决的是长对话的 Token 管理问题——当上下文接近模型 Context Window 限制时发一条/compactAgent 会把之前的对话压缩成摘要关键信息不丢Token 空间又释放出来。/usage tokens开启后每条回复末尾会追加用量信息重度使用时拿来盯 API 成本挺好用。相关实现可以在src/gateway/server-chat.ts和src/cli/目录里找到。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth跑这条链路时下面几个报错出现频率最高逐个说清楚。5.1 401 UnauthorizedKey 没读到或模型不匹配最常见的原因是apiKeyEnv引用的环境变量没导出。检查echo $ANTHROPIC_API_KEY如果为空在 shell 配置里加上或者直接在启动 Gateway 前 export。另一个原因是模型名写错——比如配置里写了一个当前账号没权限的模型也会返回 401 或 403。对照配置里的model字段和账号实际可用的模型列表核对一遍。5.2 local proxy failed本地连接被拒这个报错通常出现在 CLI 连 Gateway 的时候。原因一般是 Gateway 没起来或者端口对不上。先确认curl http://127.0.0.1:18789/health如果连不上检查 Gateway 进程是否在跑、--port和配置里的port是否一致。还有一种情况是防火墙拦了本地回环但这种比较少见。5.3 reading choices模型返回结构不符合预期这个报错一般出现在 Agent Runtime 解析模型响应的时候。常见原因是模型返回了非标准结构比如某些兼容层返回的字段名不一样或者流式响应被中途截断。排查方向看 Gateway 的--verbose日志里模型原始返回是什么确认用的模型 ID 和 provider 匹配如果是自建兼容层检查它是否按 OpenAI/Anthropic 的标准格式返回choices字段。5.4 OAuth 回调失败端口或浏览器问题Onboarding 选 OAuth 认证时向导会起一个本地回调端口等浏览器跳转。如果这个端口被占用或者你在无浏览器的环境里跑就会卡住。解决办法换一个回调端口或者改用 API Key 方式认证。在服务器上跑的话API Key 方式更省事。5.5 三件套核对Base URL、Key、Model ID如果你是通过兼容层接入模型记住三件套必须同时对上Base URL 指向正确的服务地址Key 有对应权限Model ID 是服务端认识的名称。任何一个不对都会表现为 401 或 reading choices。把这三个值单独拿出来用 curl 测一遍能快速定位是哪一环的问题。6. 接入与排障把第一句 Hello 跑通之后第一句 Hello 跑通意味着 CLI、Gateway、Agent Runtime、模型调用这条链路是通的。接下来如果你要接真实聊天通道Slack、Discord 等或者想深入源码看 CLI 和 Gateway 的角色划分可以顺着下面两个方向走。CLI 是人机接口层负责解析命令行参数、把用户意图转换成对 Gateway 的 API 调用、展示输出。Gateway 是长驻的中控进程真正管理 Session、通道连接、Agent、技能、Cron、Webhooks。它对外暴露统一的控制接口供 CLI、Web UI、Node 客户端使用。想只复用 Gateway、换掉 CLI 或者自己写一个代价不大——因为两者之间就是标准的 HTTP/WS/RPC 调用。如果你在接入过程中卡在 Key 配置或模型调用上可以先到 API Keys 页面把 Key 管好再对照接入文档把 Base URL、Key、Model ID 三件套核对一遍。想先验证模型本身能不能正常对话用模型对话页面发一条消息试试排除是模型侧还是 Gateway 侧的问题。长期要跑编码类或 Agent 类任务的话Coding Plan 更适合持续调用不用每次手动配。排障时优先看 Gateway 的--verbose日志它会告诉你消息在哪一步断掉。大部分问题集中在三件套不匹配和端口占用上把这两个排查完链路基本就通了。