1. Ubuntu 24.04 装 OpenClaw 前，先把 Node.js 与 npm 版本对齐
OpenClaw 是一个跑在终端里的 AI 助手工具，能通过命令行调用大模型、跑代理任务、接聊天通道。它适合谁？适合习惯在 Ubuntu 服务器或本地 WSL 里干活、想用一条命令把模型能力接进工作流的开发者。但很多人第一次装就卡住，问题往往不在 OpenClaw 本身，而在 Node.js 与 npm 的版本没对齐。我实测下来，Ubuntu 24.04.3 LTS 自带的 Node 版本偏旧，直接apt install nodejs拿到的可能是 v18 甚至更低，而 OpenClaw 2026.3.8 这条线要求 Node 22 以上，npm 也要 10 以上，否则安装脚本会在依赖解析阶段直接退出。
先说清楚版本要求。OpenClaw 官方安装脚本会检测 Node.js 主版本，低于 22 会提示不满足。npm 方面，v11 是当前稳定线，v10 也能跑，但 v9 以下会在装某些 ESM 包时报ERR_REQUIRE_ESM。所以第一步不是急着敲安装命令，而是把运行时环境理顺。我建议用 nvm 管理 Node，而不是系统包管理器，原因是 nvm 可以随时切版本，不会污染系统 Python 和 apt 依赖，卸载也干净。
检查当前环境，你可以先跑这三条：
cat /etc/os-release | head -n 2 node -v npm -v如果输出里 Node 是 v22.x、npm 是 11.x，那可以直接跳到下一节。如果 Node 是 v18 或 v20，先装 nvm。nvm 的安装脚本走的是 GitHub raw，国内网络偶尔慢，但一般能成：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完要重新加载 shell 配置，否则nvm命令找不到：
export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"然后装 Node 22 的 LTS 线。我选的是 v22.13.1，这个版本在 Ubuntu 24.04 上编译原生模块没出过问题：
nvm install 22.13.1 nvm alias default 22.13.1 nvm use default验证一下：
node -v # 期望输出 v22.13.1 npm -v # 期望输出 11.9.0 或相近 which nodewhich node应该指向~/.nvm/versions/node/v22.13.1/bin/node，而不是/usr/bin/node。如果指向系统路径，说明 nvm 没生效，检查~/.bashrc里有没有被其他 PATH 覆盖。Git 也建议装上，OpenClaw 的部分插件会拉 git 仓库：
sudo apt update sudo apt install -y git curl build-essential git --versionbuild-essential别省，某些 npm 包带原生扩展，缺 gcc 会在node-gyp阶段报错。到这里，Node.js 与 npm 环境就算对齐了，接下来才是 OpenClaw 本体安装。这一步的坑最多，下一节展开。
2. OpenClaw 安装脚本报 404 与 /dev/tty 报错的定位思路
先说一个我踩过的坑：网上有些教程让你直接npm install -g @openclaw/cli，我照做后返回 404。原因是这个包名已经变更或从未在公共 npm registry 上以该名字发布，所以 404 不是网络问题，是包名不对。正确的路径是走官方一键安装脚本，它会自己处理 npm 包的拉取和链接。
官方脚本命令：
curl -fsSL https://openclaw.ai/install.sh | bash正常输出大概长这样：
OpenClaw Installer ✓ Detected: linux ✓ Node.js v22.13.1 found ✓ Git already installed ✓ OpenClaw npm package installed ✓ OpenClaw installed OpenClaw installed successfully (OpenClaw 2026.3.8 (3caab92))!看到installed successfully就说明核心装完了。但这里有个高频报错：脚本最后阶段可能抛/dev/tty: No such device or address。这不是安装失败，而是脚本想启动交互式向导，但当前会话没有可用的终端设备（比如你在 CI、Docker、或者某些 SSH 非交互模式下跑）。核心 CLI 已经装好了，这个报错可以忽略，后面手动配置即可。
验证安装是否真的成功，跑这三条：
which openclaw openclaw --version openclaw --helpwhich应该输出类似/root/.nvm/versions/node/v22.13.1/bin/openclaw。--version输出OpenClaw 2026.3.8 (3caab92)。--help会列出完整命令，包括onboard、configure、gateway、agent等。如果openclaw命令找不到，八成是 npm 全局 bin 目录没进 PATH。查一下：
npm config get prefix如果 prefix 是~/.nvm/versions/node/v22.13.1，那 bin 在~/.nvm/versions/node/v22.13.1/bin，确认这个路径在$PATH里。没有就手动加：
echo 'export PATH="$HOME/.nvm/versions/node/v22.13.1/bin:$PATH"' >> ~/.bashrc source ~/.bashrc还有个常见疑问：claw命令能不能用？实测下来只有openclaw可用，claw可能是旧版别名。想要短命令可以自己建别名：
echo 'alias claw=openclaw' >> ~/.bashrc source ~/.bashrc文件位置也记一下，方便排障：CLI 在~/.nvm/versions/node/v22.13.1/bin/openclaw，npm 全局包在~/.nvm/versions/node/v22.13.1/lib/node_modules，OpenClaw 状态目录在~/.openclaw/（配置后生成）。知道这三个位置，后面改配置、清缓存都有方向。
安装完成后别急着跑onboard，因为交互式向导在非终端环境会再次触发/dev/tty报错。更稳的做法是直接改配置文件，把 endpoint 和 auth.json 指到统一通道。下一节给可复制的配置片段。
3. 把 endpoint 与 auth.json 改到 TaoToken 统一 Key 通道
OpenClaw 默认会引导你填各家模型的 API Key，但如果你手上有多个模型来源，逐个配很麻烦。更省事的做法是把 endpoint 和 auth.json 统一指向 TaoToken 的 API 通道，一个 Key 走通所有模型。TaoToken 的 API 地址是https://taotoken.net/api，官网在https://taotoken.net/?utm_source=taotoken_aicg_blog_end。注意 API 地址不带 UTM 参数，直接写 base URL 就行。
先看 OpenClaw 的配置目录结构。装完后~/.openclaw/下会有config.toml和auth.json两个关键文件。如果目录不存在，手动建：
mkdir -p ~/.openclawconfig.toml负责 endpoint、模型 ID、网关参数，auth.json负责存 Key。先写config.toml：
# ~/.openclaw/config.toml [gateway] host = "127.0.0.1" port = 8787 [model] provider = "openai-compatible" base_url = "https://taotoken.net/api" model_id = "claude-sonnet-4-20250514" timeout_seconds = 120 [agent] workspace = "~/.openclaw/workspace" max_tokens = 8192这里provider用openai-compatible，因为 TaoToken 的 API 走 OpenAI 兼容协议，大多数客户端都能直接对接。model_id按你实际要用的模型填，比如 Claude 系列或 GPT 系列，具体可用模型在模型对话页面能查到。base_url结尾不要带/v1，OpenClaw 会自己拼路径，带了会变成/v1/v1/chat/completions报 404。
再写auth.json：
{ "openai-compatible": { "api_key": "sk-你的TaoTokenKey", "base_url": "https://taotoken.net/api" } }Key 从控制台的 API Keys 页面生成，生成后只显示一次，记得存好。auth.json权限收紧一点：
chmod 600 ~/.openclaw/auth.json如果你用的是 Claude Code 那套配置习惯，OpenClaw 也支持在config.toml里直接引用环境变量，避免明文写 Key：
[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" model_id = "claude-sonnet-4-20250514" api_key_env = "TAOTOKEN_API_KEY"然后在~/.bashrc里导出：
export TAOTOKEN_API_KEY="sk-你的TaoTokenKey" source ~/.bashrc两种方式选一种就行，环境变量方式更适合多机同步配置。配完检查一下 TOML 语法，OpenClaw 对格式敏感，少个引号会直接启动失败：
openclaw configure --check如果这条命令报config parse error，用python3 -c "import tomllib; tomllib.load(open('$HOME/.openclaw/config.toml','rb'))"快速定位语法问题。配置写对了，下一节验证请求。
4. 验证 OpenClaw 请求：从 gateway 启动到模型对话成功
配置写完，先启动 gateway。gateway 是 OpenClaw 的 WebSocket 网关，agent 和聊天通道都靠它转发请求：
openclaw gateway正常输出会显示监听地址和端口：
Gateway listening on 127.0.0.1:8787 WebSocket endpoint: ws://127.0.0.1:8787/ws如果报EADDRINUSE，说明 8787 被占，改config.toml里的port换个值，比如 8788。gateway 起来后别关这个终端，另开一个窗口跑验证。
最直接的验证是让 OpenClaw 发一次模型请求。用agent命令跑一个简单任务：
openclaw agent --prompt "用一句话说明你现在用的是哪个模型"如果配置正确，几秒内会返回模型输出。这一步能通，说明 endpoint、Key、模型 ID 三件套都对上了。如果卡住不动，加--verbose看请求日志：
openclaw agent --prompt "test" --verbose日志里会打印实际请求的 URL，确认是https://taotoken.net/api/chat/completions而不是别的地址。如果 URL 里出现了/v1/v1，回去检查base_url是不是多写了/v1。
再验证一下模型列表能不能拉到。有些客户端会先请求/models接口：
curl -s https://taotoken.net/api/models \ -H "Authorization: Bearer sk-你的TaoTokenKey" | head -c 500返回 JSON 里有data数组就说明 Key 有效。如果返回 401，Key 错了或没带Bearer前缀。如果返回 404，检查 URL 是不是写成了https://taotoken.net/api/v1/models，去掉/v1。
gateway 和 agent 都通了之后，可以试一下onboard向导做通道集成。但前面说过，非交互终端会报/dev/tty，所以要么在完整终端里跑，要么跳过向导直接手改配置。我一般跳过，因为手改更可控。到这一步，一次可用的 OpenClaw 安装流程就跑通了：Node 22 环境、OpenClaw CLI、TaoToken 统一通道、gateway 启动、agent 请求成功。下一节把常见报错集中排一遍。
5. 常见报错排查：401、local proxy failed 与 reading choices
装 OpenClaw 接 TaoToken 的过程中，报错集中在几个点上。我把真实遇到过的列出来，对照着查能省不少时间。
401 Unauthorized。这个最直接，Key 不对或没传。检查三处：auth.json里的api_key有没有sk-前缀；环境变量方式下TAOTOKEN_API_KEY有没有export且source过；请求头有没有带Authorization: Bearer。如果 Key 是从控制台刚生成的，确认复制完整，没有多余空格。还有一种情况是 Key 被禁用或额度耗尽，去控制台看一眼状态。
local proxy failed。这个报错通常出现在 gateway 启动阶段，意思是本地代理端口起不来。原因可能是端口被占、或者config.toml里host写成了0.0.0.0但防火墙拦了。先换端口，再确认host是127.0.0.1。如果用了系统级代理工具，检查环境变量HTTP_PROXY、HTTPS_PROXY有没有干扰本地回环，有就临时 unset：
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy openclaw gatewayreading choices 报错。完整报错一般是Cannot read properties of undefined (reading 'choices')，意思是客户端拿到了响应但结构不对，找不到choices字段。根因通常是 endpoint 返回了非预期格式，比如把 base URL 指到了网页地址而不是 API 地址，或者模型 ID 写错导致服务端返回错误 JSON。检查base_url是不是https://taotoken.net/api，model_id是不是有效模型名。用 curl 直接打一次确认返回结构：
curl -s https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}]}' | head -c 300返回里有choices数组就说明服务端正常，问题在 OpenClaw 配置侧。
OAuth 相关报错。如果你之前配过 Claude Code 的 OAuth 登录，OpenClaw 可能会尝试复用旧凭据导致冲突。清掉旧状态：
rm -rf ~/.openclaw/auth.json然后重新写auth.json，只保留 TaoToken 的 Key。别让多个认证方式混在一起。
CC Switch / Cline MCP / Codex auth.json 三件套。如果你同时用这些工具，注意它们的配置是独立的。OpenClaw 读的是~/.openclaw/auth.json，Codex 读的是~/.codex/auth.json，别改错文件。三件套的核心都是 Base URL、Key、Model ID，配的时候对齐这三项就不会乱。
排障顺序建议：先 curl 验证 Key 和 endpoint，再查 OpenClaw 配置文件语法，最后看 gateway 日志。大部分问题在前两步就能定位。
6. 后续接入与长期使用建议
装完跑通只是起点。OpenClaw 的gateway和agent适合临时验证，长期用建议把 gateway 做成 systemd 服务，开机自启，崩了自动拉起来。写一个 unit 文件：
# /etc/systemd/system/openclaw-gateway.service [Unit] Description=OpenClaw Gateway After=network.target [Service] Type=simple User=你的用户名 Environment="TAOTOKEN_API_KEY=sk-你的TaoTokenKey" ExecStart=/home/你的用户名/.nvm/versions/node/v22.13.1/bin/openclaw gateway Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target然后：
sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway sudo systemctl status openclaw-gateway这样 gateway 常驻，agent 和聊天通道随时能用。如果你要跑长期编码任务或 Agent 工作流，Coding Plan 那条线更合适，额度和并发比按次调用稳。模型选择上，日常对话用轻量模型，复杂任务切强模型，在config.toml里改model_id就行，不用重装。
最后提醒一点：~/.openclaw/目录会随使用增长，workspace 里的临时文件定期清。auth.json权限保持 600，别提交到 git。Node 版本升级时，nvm 切完记得重装 OpenClaw，因为全局包是绑在具体 Node 版本下的。这套流程我在 Ubuntu 24.04 上复现过多次，按上面的顺序走，基本一次成。
