1. 先搞清楚 OpenClaw 到底在跑什么OpenClaw 这个项目最近在开发者圈子里被叫成“小龙虾”名字来源已经无从考证但它的定位其实一句话能说清它是一个跑在本地 Node 环境里的 AI 智能体网关gateway。注意这里的三个关键词——本地、Node、网关。很多人第一次接触会误以为它是一个新出的 AI 模型或者是一个开箱即用的聊天软件这两种理解都会让你在配置阶段直接卡死。我先把它的技术本质拆开讲。OpenClaw 本身不生产任何模型能力它做的事情是在你的电脑上启动一个 Node 进程这个进程对外暴露一个 HTTP 服务默认监听 18789 端口对内则负责管理“智能体”的会话状态、工具调用、以及最关键的——把请求转发给真正的模型 API。也就是说它是一个请求编排层而不是模型层。你问它问题它不会自己回答而是把你配置好的 API Key 拿去向真正的模型服务发起调用再把结果流式返回给你。这个架构带来的直接好处是你可以在一个统一的界面里切换不同的模型供应商而不需要为每个供应商单独装一个客户端。坏处也很明显你必须自己准备 API Key并且这个 Key 必须能通。很多新手装完 OpenClaw 发现浏览器里聊不起来90% 的情况不是 OpenClaw 坏了而是 API 通道没配通。那为什么它要设计成 gateway 形态因为智能体场景和普通聊天不一样。普通聊天是一问一答智能体场景里模型需要调用工具、需要保持多轮上下文、需要在不同会话之间隔离状态。如果每个模型供应商都自己实现一套开发者会被重复劳动拖死。OpenClaw 把这一层抽象出来你只需要按它的格式填 Base URL、Key、Model ID剩下的会话管理、流式解析、工具注册它帮你做。适合谁来用如果你只是想找个聊天窗口那确实没必要折腾它。但如果你想让 AI 帮你定时抓网页、批量处理文件、或者把模型能力接进自己的脚本流程里OpenClaw 这种网关形态就比直接调 API 省事得多——它帮你把会话和工具那层脏活干了。接下来我会从 Node 环境准备开始一步步把本地启动、API 接入、连通性验证走完中间踩过的坑也会标出来。2. Node 环境与 TaoToken 前置准备在动手之前先把两件事准备好Node 运行环境和一条能用的 API 通道。这两件事缺一个后面都会卡住。2.1 Node 版本别踩坑OpenClaw 官方要求 Node 22 以上。这个版本要求不是随便写的它用到了较新的 fetch 和流式处理 APINode 20 上跑会报一些莫名其妙的模块错误。你可以先用下面命令确认版本node -v # 期望输出类似 v22.11.0如果版本低于 22去 Node 官网下载 LTS 版本覆盖安装即可。Windows 用户注意安装时勾选“Add to PATH”否则命令行里找不到 node。装完重开一个终端再验证别在旧终端里试。2.2 为什么这里要提 TaoTokenOpenClaw 本身只是个网关它需要指向一个能响应 OpenAI 兼容协议的服务端点。你可以直接填各家厂商的官方地址但那样每换一个模型就要改一次 Key 和 Base URL调试阶段很烦。TaoToken 提供的是统一 Key 和统一 API 通道Base URL 固定为https://taotoken.net/api模型 ID 按需切换。这样你在 OpenClaw 里只需要维护一份配置换模型只改 Model ID 那一行。对智能体场景来说这点很重要你可能会在同一个会话里先用便宜模型做意图识别再用强模型做最终生成。如果每次都要改配置重启调试效率会低到无法接受。统一通道让你可以在配置里一次性写好切换只动一个字段。2.3 拿到 Key 之后先别急着填去控制台创建一个 API Key复制出来先存到临时文本里。注意两点第一Key 只在创建时完整显示一次关掉页面就看不到了第二不要直接把 Key 写进会提交到 Git 的文件里。后面配置环节我会用环境变量的方式注入这样即使配置文件被同步也不会泄露。如果你还没创建 Key可以走这个路径控制台 → API Keys → 新建。创建时给它起个能认出来的名字比如openclaw-local方便以后排查是哪个客户端在调用。3. 可复制的 OpenClaw 配置与启动这一节是全文最核心的部分我会给出可以直接复制的配置片段并说明每个字段对应什么。OpenClaw 的配置读取优先级是环境变量 项目根目录配置文件 全局配置。本地调试建议用项目根目录的配置文件改起来直观。3.1 安装与初始化先全局装 CLI再在你想放配置的目录里初始化npm install -g openclaw mkdir openclaw-lab cd openclaw-lab openclaw initinit会生成一个基础配置文件。如果你用的是较新版本配置文件名可能是openclaw.config.json或settings.json以实际生成的文件名为准。下面给出一份完整的 JSON 配置示例路径与字段名按官方结构对齐{ gateway: { host: 127.0.0.1, port: 18789, cors: true }, providers: { default: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514, protocol: openai } }, agents: { assistant: { provider: default, systemPrompt: 你是一个本地智能体可以调用工具完成任务。, maxTurns: 20 } } }几个关键点解释一下。baseUrl填https://taotoken.net/api注意结尾不要多加斜杠有些版本会把斜杠拼成双斜杠导致 404。apiKey用${TAOTOKEN_API_KEY}这种占位符实际值通过环境变量注入。protocol填openai因为 TaoToken 的通道是 OpenAI 兼容格式OpenClaw 会按这个协议去拼/chat/completions路径。model字段填你要用的模型 ID换模型就改这一行。3.2 注入环境变量并启动Linux/macOS 下export TAOTOKEN_API_KEY你的Key openclaw gatewayWindows PowerShell 下$env:TAOTOKEN_API_KEY你的Key openclaw gateway启动成功后终端会打印监听地址通常是http://127.0.0.1:18789。这时候别关终端另开一个窗口做验证。如果你看到端口被占用的报错说明 18789 已经被别的进程用了改配置里的port字段换一个比如 18790。3.3 关于 CC Switch / Cline MCP / Codex 的三件套如果你后续要把 OpenClaw 和 CC Switch、Cline 的 MCP 配置、或者 Codex 的auth.json打通记住任何一处接入都必须写全三件套Base URL Key Model ID。少任何一个都会在请求阶段报错。以 Codex 的auth.json为例结构大致是{ base_url: https://taotoken.net/api, api_key: 你的Key, model: claude-sonnet-4-20250514 }Cline 的 MCP 配置里则是在 provider 段填这三项。不要只填 Key 就以为能通Base URL 缺失时客户端会默认指向官方地址而你的 Key 在官方那边是无效的结果就是 401。4. 验证请求与成功结果配置写完必须验证通道真的通了。分两步先用 curl 直接打 API确认 Key 和 Base URL 没问题再通过 OpenClaw 的网关发一次请求确认网关层也正常。4.1 直接验证 API 通道curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字通了}], stream: false }如果返回的 JSON 里choices[0].message.content是“通了”说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整、有没有多余空格。如果返回 404检查 Base URL 是不是多写了斜杠或者少写了/api。4.2 通过网关验证打开浏览器访问http://127.0.0.1:18789在输入框里发一句话。正常情况下你会看到流式输出逐字出现。如果页面能打开但发消息没反应打开浏览器开发者工具的 Network 面板看/api/chat这个请求的返回状态。常见的是 500这时候去看 OpenClaw 终端里的日志通常会打印出具体的上游错误。实测下来第一次跑通看到流式输出的时候基本就说明整条链路——Node 进程、网关路由、API 通道、模型响应——全部打通了。后面你要做的只是按需加智能体和工具。5. 本篇常见错误排查这一节按真实报错来对照遇到问题直接搜关键词。401 UnauthorizedKey 无效或没带上。检查环境变量是否在当前终端生效echo $TAOTOKEN_API_KEY看有没有值。Windows 下注意 PowerShell 和 CMD 的环境变量语法不同别混用。local proxy failed / ECONNREFUSED网关连不上上游。多数是 Base URL 写错或者本机网络到不了目标地址。先用 4.1 的 curl 单独验证curl 通了再查 OpenClaw 配置。reading choices of undefined上游返回的结构和预期不符。常见于 Model ID 填错服务端返回了错误对象而不是正常的 choices 数组。把 Model ID 换成确认可用的再试。OAuth 相关报错如果你在配置里误开了 OAuth 模式而通道实际是 API Key 模式就会报这个。检查配置里有没有authType之类的字段被设成了 oauth改回 apiKey。端口占用 EADDRINUSE18789 被占。改配置里的 port或者用lsof -i :18789macOS/Linux找到占用进程处理掉。Node 版本报错报fetch is not defined或类似基本就是 Node 低于 22。升级 Node 后重开终端。排查顺序建议固定成先 curl 验通道 → 再查 OpenClaw 配置 → 最后看网关日志。这个顺序能帮你快速定位问题出在哪一层而不是盲目改配置。6. 把通道固定下来后续接入更省事跑通之后建议把环境变量写进 shell 的启动文件里比如~/.zshrc或~/.bashrc这样每次开终端不用重新 export。配置文件里的 Key 保持占位符形式真实值只存在环境变量里避免误提交。如果你后面要接更多智能体或者换模型只需要改配置里的model字段Base URL 和 Key 都不用动。这就是统一通道的价值——把认证和路由这两件容易出错的事收敛到一个地方。需要新建 Key 或者查看用量走控制台接入细节和字段说明看接入文档想先验证模型响应质量可以直接在模型对话里试如果是长期跑编码类智能体Coding Plan 的额度模型会更合适。最后留一个实用习惯每次改完配置先用 4.1 的 curl 打一发确认通道没被改坏再启动网关。这个动作花不了十秒但能省掉大量“到底是配置错了还是网关错了”的排查时间。