1. Ubuntu 上跑 OpenClaw 到底卡在哪Node.js 版本与 API Key 两个坑OpenClaw 是一个跑在本地终端里的 AI Agent 运行时它能接管你的命令行、读写工作区文件、按你配置的模型去执行任务。适合谁适合那些不想把代码和上下文丢给网页版对话框、又希望有个能长期驻留的编码助手的开发者。它本身不产出模型能力模型能力来自你填进去的 API Key所以「装得上」和「连得通」是两件事。我在 Ubuntu 24.04 上从零走了一遍完整链路踩到的坑集中在两处。第一处是 Node.js 版本OpenClaw 要求 Node.js 22 或更高而 Ubuntu 自带的 apt 源里往往是 18 或 20直接npm install -g openclaw会在依赖解析阶段报 engine 不匹配或者装上了但启动时抛SyntaxError。第二处是 API Key 的写入位置和格式OpenClaw 的配置不是简单的环境变量而是一个.openclaw.json里面models.providers和agents.defaults.model要对应上写错一个字段就会出现「模型列表为空」或者请求发出去返回 401。这篇教程按「环境校验 → 安装 → 初始化 → 写 Key → 启动验证 → 排错」的顺序走每条命令都能直接复制。你不需要提前懂 Node.js 生态只要有一台能联网的 Ubuntu 机器和终端就行。全程大约 15 分钟其中 nvm 下载和 npm 全局安装占大头。需要提前说明的是OpenClaw 的模型接入走的是标准 OpenAI 兼容协议或 Anthropic Messages 协议所以任何提供这两种协议的服务都能填进去。下面配置示例里我用 TaoToken 的接入点作为演示因为它的 Base URL 和 Key 获取路径比较清晰你换成自己的服务商时只要改baseUrl和apiKey两个字段即可。2. 前置准备Ubuntu 环境校验与 TaoToken 接入信息获取在敲任何安装命令之前先花两分钟确认系统底子。打开终端依次执行下面三条把结果记下来。# 查看 Ubuntu 版本要求 24.04 及以上 lsb_release -a # 查看当前 Node.js 版本如果低于 22 就需要重装 node --version # 查看 npm 版本 npm --version如果node --version输出的是v18.x或v20.x不要试图用apt upgrade硬升Ubuntu 的 nodejs 包和 npm 包版本是绑定的升级容易把 npm 弄坏。正确做法是用 nvm 管理多版本这也是下一步要做的。如果输出command not found说明根本没装同样走 nvm 路线。接下来准备 API Key。OpenClaw 本身不带模型你需要一个能提供 OpenAI 兼容接口或 Anthropic Messages 接口的服务。以 TaoToken 为例接入信息有三个要素缺一不可要素说明示例值Base URL接口根地址不带具体路径https://taotoken.net/apiAPI Key身份凭证形如sk-开头在控制台生成Model ID模型标识填进配置的id字段claude-sonnet-4-6等获取路径是先访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录然后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建 API Key最后到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 复制那串sk-开头的字符串。复制后先粘到记事本里后面配置要用两次。注意API Key 只在创建时完整显示一次关掉页面就看不到了。如果没存下来直接删掉重建一个不要试图找回。模型 ID 怎么确定进模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 能看到当前可用的模型列表把你要用的那个名字记下来。配置里models.providers下的models[].id必须和这个名称完全一致大小写敏感。3. 可复制配置nvm 装 Node.js 22 与 OpenClaw 全局安装这一步分三小段装 nvm、用 nvm 装 Node.js 22、全局装 OpenClaw。每段都有验证命令跑完确认再进下一段。3.1 安装 nvm 并加载# 下载并执行 nvm 安装脚本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置让 nvm 命令生效 source ~/.bashrc # 验证 nvm 是否可用 nvm --version如果nvm --version报command not found说明~/.bashrc里没写入 nvm 的初始化段。手动补一行echo export NVM_DIR$HOME/.nvm ~/.bashrc echo [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh ~/.bashrc source ~/.bashrc3.2 用 nvm 安装 Node.js 22# 安装 Node.js 22 最新版 nvm install 22 # 设为默认版本新开终端也生效 nvm alias default 22 # 验证 node --version npm --versionnode --version应该输出v22.x.x或更高。如果还是旧版本检查nvm current输出的是不是 22不是就nvm use 22切过去。3.3 全局安装 OpenClawnpm install -g openclawlatest # 验证安装 openclaw --versionopenclaw --version能输出版本号就说明二进制已经进 PATH 了。如果报command not found执行npm config get prefix看全局路径通常是~/.nvm/versions/node/v22.x.x/bin确认这个路径在echo $PATH里。3.4 初始化并写入 API Key 配置先跑初始化向导它会装 Gateway 服务并生成默认配置openclaw onboard --install-daemon向导跑完后配置文件在~/.openclaw/.openclaw.json。用编辑器打开openclaw config edit把下面这段 JSON 作为配置骨架填进去。注意baseUrl填 TaoToken 的 API 地址apiKey填你复制的sk-串models[].id填你在模型列表里看到的名称{ models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key粘贴在这里, api: anthropic-messages, models: [ { id: claude-sonnet-4-6, name: claude-sonnet-4-6 (TaoToken), reasoning: false, input: [text], contextWindow: 200000, maxTokens: 8192 } ] } } }, agents: { defaults: { model: { primary: taotoken/claude-sonnet-4-6, fallbacks: [] }, workspace: /home/你的用户名/.openclaw/workspace } }, gateway: { port: 18789, mode: local, bind: loopback, auth: { mode: token, token: 自动生成的一串token } } }三个字段的对应关系必须记牢providers下的键名这里是taotoken要和agents.defaults.model.primary的前缀一致写成taotoken/claude-sonnet-4-6models[].id要和模型服务商那边的名称完全一致api字段决定用哪种协议Anthropic 系模型填anthropic-messagesOpenAI 系填openai-completions。提示workspace路径里的用户名要换成你自己的用whoami命令查。这个目录不存在的话 OpenClaw 启动时会自动创建。4. 启动 Gateway 并验证请求成功配置写完后启动 Gateway 服务# 前台启动方便看日志 openclaw gateway # 或者指定端口 openclaw gateway --port 18789看到类似Gateway listening on 127.0.0.1:18789的输出就说明服务起来了。另开一个终端用 curl 直接打接口验证模型是否连通curl -X POST http://127.0.0.1:18789/v1/messages \ -H Content-Type: application/json \ -H x-api-key: 你的gateway token \ -d { model: claude-sonnet-4-6, max_tokens: 64, messages: [{role: user, content: 只回复两个字通了}] }如果返回 JSON 里content字段有文本内容说明整条链路打通了Gateway 收到请求 → 按配置转发到 TaoToken → 模型返回 → 原路返回。如果返回 401检查x-api-key是不是 Gateway 的 token 而不是模型服务的 Key如果返回model not found检查models[].id拼写。常用管理命令整理成表方便日常操作命令作用openclaw gateway start后台启动 Gatewayopenclaw gateway stop停止 Gatewayopenclaw gateway status查看运行状态openclaw channels list列出已配置的渠道openclaw config edit编辑配置文件openclaw onboard重新跑初始化向导验证通过后你就可以在 OpenClaw 的交互界面里直接对话了。想先确认模型能力可以到模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试几条 prompt确认返回质量符合预期再投入日常使用。如果打算长期跑编码任务或 Agent 工作流Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有对应的额度方案比按次调用更适合高频场景。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错信息对照排查每条都给出定位方法和修复动作。报错一401 Unauthorized或invalid api key这是最高频的。先分清是哪个 Key 报的错。Gateway 本身有 token 鉴权模型服务商也有 Key两个都叫 Key 容易混。判断方法看报错发生在 curl 的哪一层。如果 curl 连 Gateway 就 401是 Gateway token 错了去配置文件gateway.auth.token字段核对。如果 Gateway 返回的 JSON 里error.message提到上游是模型 Key 错了去models.providers.taotoken.apiKey核对。还有一种情况是 Key 复制时带了空格或换行。用下面命令检查grep apiKey ~/.openclaw/.openclaw.json | cat -A如果行尾出现$之外的^M或多余空格手动删掉。Key 必须是sk-开头的一整串中间不能断行。报错二local proxy failed或ECONNREFUSED 127.0.0.1:18789这个报错说明客户端连不上 Gateway通常是 Gateway 没起来或者端口被占。先查状态openclaw gateway status ss -tlnp | grep 18789如果ss显示端口被别的进程占了换端口启动openclaw gateway --port 18790同时把客户端配置里的地址也改掉。如果 Gateway 状态是 stopped看日志找原因journalctl --user -u openclaw-gateway -n 50日志里如果有EADDRINUSE就是端口冲突有permission denied就是 workspace 目录权限问题用chmod 755修。报错三reading choices或Cannot read properties of undefined (reading choices)这个报错几乎都是协议不匹配。choices是 OpenAI Chat Completions 响应里的字段如果你配的是 Anthropic 系模型却把api写成了openai-completionsOpenClaw 按 OpenAI 格式去解析 Anthropic 的响应自然找不到choices。反过来也一样。修复方法确认模型属于哪个协议族。Claude 系走anthropic-messagesGPT 系和大多数国产模型走openai-completions。改完配置后必须重启 Gateway配置不会热加载openclaw gateway stop openclaw gateway start报错四OAuth相关提示或token expired如果你在配置里用了mode: token而不是mode: api_keyOpenClaw 会走 OAuth 流程需要浏览器授权。本地无头环境跑不了浏览器就会卡住。解决办法是改用 API Key 模式把auth.profiles里的mode从token改成api_key然后重新填 Key。如果你确实需要 OAuth得在有图形界面的机器上先完成授权再把生成的凭证文件拷过来。报错五engine unsupported或安装时EBADENGINE这是 Node.js 版本不够。回到第 3 节用nvm install 22重装然后nvm use 22切换再重新npm install -g openclawlatest。注意 nvm 切换后全局包是隔离的旧版本 Node 下装的 openclaw 不会自动迁移必须在新版本下重装。排查时有个通用技巧把 Gateway 日志级别调高能看到完整的请求和响应体。在配置文件里加{ logging: { level: debug } }重启后日志会打印每次请求的 URL、header 和响应状态401 和协议错误一眼就能定位。6. 把配置固化下来接入文档与后续扩展跑通之后建议做两件事避免下次重装时重新踩坑。第一件是把~/.openclaw/.openclaw.json备份到别处但备份前把apiKey和gateway.auth.token替换成占位符别把明文 Key 传到公开仓库。第二件是记下你的三要素组合Base URL、Model ID、协议类型。换服务商时只改这三个其他结构不动。如果你要接入更多模型做 fallback在models.providers下加新的 provider 块然后在agents.defaults.model.fallbacks数组里按优先级排列。比如主模型用 Claude备用用国产模型主模型超时或报错时自动切换。fallback 的写法是provider键名/model的id和 primary 格式一致。完整的接入参数说明和更多配置项可以对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 逐项核对文档里对api字段的可选值、contextWindow的填法都有说明。API Keys 管理页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以随时吊销旧 Key 重建怀疑泄露时第一时间去那里操作。最后提醒一个实操细节OpenClaw 的 Gateway 默认绑定loopback也就是只有本机能访问。如果你想让局域网内其他机器连过来把gateway.bind改成0.0.0.0但务必同时确认gateway.auth.mode是token且 token 足够复杂否则等于把模型接口裸奔在网络上。改完重启 Gateway 生效。