1. 第一次跑 OpenClaw CLI为什么卡在 openclaw.json刚接触 OpenClaw圈内也叫“龙虾”的开发者大概率会遇到同一个场景照着文档敲下openclaw init终端刷出一堆日志然后停在某个地方不动了或者直接抛出一句config not found/invalid gateway config。你打开目录一看确实生成了一个openclaw.json但里面字段一大堆不知道哪些是必须的、哪些能删、哪些填错了会导致 CLI 起不来。这个问题的本质是OpenClaw 的 CLI 在启动时会先加载openclaw.json作为网关gateway配置骨架校验通过后才去连接模型通道、加载技能skills。新手最容易踩的坑是把“配置文件骨架”和“模型接入配置”混在一起写结果骨架字段缺失CLI 连第一步校验都过不去。这篇面向刚上手 OpenClaw 的开发者聚焦三件事一份可复制的最小openclaw.json骨架、TaoToken 统一 Key/API 通道该填在骨架的哪个位置、以及用 CLI 命令逐项验证配置是否真的生效。目标很明确——让你跑通第一条链路而不是对着报错猜字段。适合人群会用终端、装过 Node 环境、但没系统配过 OpenClaw 网关配置的新手。2. 前置准备TaoToken 统一 Key 与 API 通道在写openclaw.json之前先把模型通道这块准备好。OpenClaw 本身是网关 CLI 的框架它需要一个能对话、能补全的模型后端。我试过把通道统一到 TaoToken 上好处是 Key 和 API 地址只维护一份后面换模型、加技能都不用改多处配置。你需要拿到两样东西一是 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 就是后面填进openclaw.json的凭证。二是 API 基础地址。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base URL 使用。模型对话、coding plan、控制台、API Keys、接入文档这些入口都可以从官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去后按导航找到。注意Key 只创建一次就够不要每个技能都单独建 Key。统一通道的意义就在于“一处配置多处复用”。Key 泄露风险高别写进会提交到 Git 的文件里用环境变量或本地配置文件隔离。如果你后面要做长期编码或 Agent 类任务可以了解下 Coding Plan它更适合持续性的代码生成场景只是验证模型通不通用模型对话页面点几下就能确认。这两条路径和本篇的 CLI 验证是互补的不冲突。3. 可复制的 openclaw.json 最小骨架下面这份骨架是我实测能跑通 CLI 启动的最小集合。字段名以 OpenClaw 官方配置文档为准你可以直接复制把apiKey换成自己的。{ gateway: { name: local-gateway, port: 8787, host: 127.0.0.1 }, providers: [ { id: taotoken, type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ { id: gpt-4o-mini, name: default-chat } ] } ], defaultProvider: taotoken, defaultModel: default-chat, skills: { enabled: true, dir: ./skills } }逐段说明一下方便你理解每个字段为什么在骨架里gateway是网关自身的信息。port和host决定 CLI 本地监听的地址新手保持127.0.0.1和8787即可别急着改端口改了要同步改验证命令。providers是模型通道数组。type填openai-compatible因为 TaoToken 的 API 兼容 OpenAI 风格的请求格式。baseUrl就是上一步的https://taotoken.net/api注意结尾不要多加/v1具体路径由 OpenClaw 内部拼接。apiKey填你的 Key。models里给模型起个别名default-chat这样defaultModel引用它时不用记原始模型 ID换模型只改这一处。skills段控制技能加载。enabled: true打开技能系统dir指向技能目录。新手如果暂时不装技能可以先把enabled设为false减少启动时的变量。提示openclaw.json对 JSON 格式很敏感多一个逗号、少一个引号都会导致解析失败。建议用编辑器的 JSON 校验功能或者保存后用node -e JSON.parse(require(fs).readFileSync(openclaw.json,utf8))先验一遍语法。4. CLI 逐项验证配置是否生效配置文件写完不等于生效。OpenClaw CLI 提供了一组命令可以分层验证。按下面顺序走哪一步失败就停在哪一步排查比一次性启动再看一堆日志高效得多。第一步验证 JSON 语法和骨架结构openclaw config validate这条命令只做静态校验不启动网关。如果输出config is valid说明骨架字段没缺、JSON 没写错。如果报missing required field: gateway.port这类错误就回到上一节对照字段补。第二步验证 provider 通道能否连通openclaw provider test taotoken它会用你配置的baseUrl和apiKey发一个最小请求。成功时返回模型列表或一个简短的响应失败常见的是401Key 错或404baseUrl 路径错。这一步过了说明 TaoToken 通道是通的。第三步启动网关并确认监听openclaw start终端会打印网关启动日志包含监听地址。另开一个终端用 curl 探一下curl -s http://127.0.0.1:8787/health返回{status:ok}之类的健康响应说明网关进程活着。第四步跑一次端到端对话确认模型链路完整openclaw chat 用一句话说明什么是网关如果终端返回了模型生成的回答恭喜第一条链路跑通了。这一步同时验证了 gateway、provider、defaultModel 三段配置的联动。第五步确认技能系统状态openclaw skills list列出已加载的技能。如果skills.enabled是true但列表为空检查dir路径是否存在、里面有没有技能包。新手阶段列表为空不影响主链路可以先放着。5. 本篇常见报错与排查新手在配openclaw.json时报错集中在几个固定位置。下面按“报错信息 → 原因 → 动作”整理方便你对号入座。Error: config file not foundCLI 没在当前目录找到openclaw.json。确认你在项目根目录执行命令或者用openclaw --config /path/to/openclaw.json显式指定路径。SyntaxError: Unexpected token }JSON 语法错误通常是多逗号或漏引号。用第 3 节的node -e命令定位到具体行。401 UnauthorizedapiKey无效或过期。去 TaoToken 控制台重新生成一个 Key替换后重跑openclaw provider test。404 Not FoundbaseUrl写错常见的是多写了/v1或少了/api。正确值是https://taotoken.net/api。EADDRINUSE: port 8787 already in use端口被占用。要么关掉占用进程要么改gateway.port改完记得同步改 curl 验证的地址。defaultModel not founddefaultModel引用的别名在models数组里不存在。检查models[].name和defaultModel是否完全一致大小写敏感。skills dir not existskills.dir指向的目录不存在。要么创建目录要么把skills.enabled设为false先跳过。注意排查时一次只改一个字段改完立刻重跑对应的验证命令。同时改多处报错消失了你也不知道是哪处修好的下次还会踩。6. 跑通之后把 Key 和通道固定下来第一条链路跑通后建议做两件收尾的事能省掉后面大量重复劳动。一是把 Key 从openclaw.json里挪出去改用环境变量引用。OpenClaw 支持在配置里写${TAOTOKEN_API_KEY}这类占位符实际值从环境变量读。这样配置文件可以安全地进版本库Key 不会跟着泄露。二是把openclaw.json的骨架部分单独抽一份模板放在项目里。以后新建项目直接复制模板只改providers里的 Key 和模型别名骨架字段不用重新想。TaoToken 的 Key 和 API 通道统一维护一份换模型时只动models数组gateway和skills段完全不用碰。如果你后面要接长期编码任务或 Agent 流程可以在 TaoToken 的 Coding Plan 里看下适合持续调用的方案只是日常验证模型模型对话入口点几下就够。接入细节和字段说明接入文档里有完整对照。把这篇的骨架和验证命令存下来下次配新环境十分钟内能跑通。