1. Ubuntu 本地部署 OpenClaw 到底难在哪Node.js 版本与依赖链的坑OpenClaw 是一个可以跑在本地机器上的智能体运行时它能对接大模型 API、管理会话、加载技能适合想把 AI 助手私有化部署、又不想依赖云端托管环境的开发者。这篇教程面向的是在 Ubuntu 上从零开始部署 OpenClaw 的完整链路重点解决 Node.js/npm 版本核对、依赖安装、配置文件定位与启动验证这几个最容易卡住的环节同时把模型通道统一接到 TaoToken 的 API 上省去到处申请 Key 的麻烦。很多人第一次装 OpenClaw 失败不是因为它本身复杂而是环境没对齐。Ubuntu 系统预装的 Node.js 往往是旧版本npm 也可能停留在 8.x 甚至更早而 OpenClaw 依赖的某些 npm 包比如带原生模块的 sharp在旧运行时上编译会直接报错。我试过在一台 Ubuntu 22.04 的机器上直接用 apt 装的 nodejs结果npm install -g openclaw卡在 node-gyp 编译阶段日志里全是 Python 和 gcc 相关的报错折腾半天才发现是 Node 版本太低。所以整条链路的核心逻辑是先把系统基础依赖补齐编译工具链、证书、下载工具再用 NodeSource 源装一个受支持的 Node.js 版本然后通过 npm 全局安装 OpenClaw最后用 onboard 向导或手动配置的方式把模型通道指向 TaoToken启动网关并验证请求能正常返回。这里有个关键点要提前说清楚OpenClaw 本身不绑定任何一家模型服务商它通过 provider 配置来对接不同的 API 端点。TaoToken 提供的是统一的 Key 和 API 通道你只需要在配置里把 baseUrl 指向 TaoToken 的 API 地址填上申请到的 Key再指定模型 ID就能让 OpenClaw 走这条通道调用模型。这样做的好处是你不需要在 OpenClaw 里分别配置 DeepSeek、OpenAI 等多个 provider一个通道搞定。适合跟着做的读者有基本 Linux 命令行操作经验能在终端里执行 sudo 命令理解什么是环境变量和配置文件。如果你之前没接触过 Node.js 项目部署也没关系每一步我都会给出完整命令和预期输出照着敲就行。环境要求方面操作系统建议 Ubuntu 22.04这个版本的依赖兼容性验证最充分二进制构建的坑最少。Node.js 需要 v22.22.3 以上或 v24.xnpm 需要 11.x 以上。内存建议 2GB 起步因为 npm 全局安装和后续网关运行都会占用一定资源。磁盘空间预留 2GB 左右主要给 node_modules 和日志。在开始之前先确认你的机器能正常访问外网因为安装过程需要从 npm 仓库和 NodeSource 源下载包。如果你在公司内网环境可能需要提前配置好 npm 的 registry 镜像。另外确保你有 sudo 权限因为安装系统依赖和启用 corepack 都需要提权。这一节先把整体思路和前置条件讲清楚下一节进入 TaoToken 的 Key 申请和通道准备然后才是具体的环境配置和 OpenClaw 安装步骤。整个流程走下来大概 20 到 30 分钟取决于网络速度。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在装 OpenClaw 之前先把模型通道准备好。TaoToken 的作用是提供一个统一的 API 入口你申请一个 Key就能通过它调用多种模型不需要在每个模型服务商那里单独注册和充值。对于 OpenClaw 这种需要频繁切换模型做测试的场景统一通道能省不少事。首先打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号后进入控制台。在控制台里找到 API Keys 管理页面创建一个新的 Key。创建时建议给 Key 起一个能识别用途的名字比如openclaw-local方便后续管理。Key 创建后会显示一次复制下来保存好后面配置 OpenClaw 时要用。拿到 Key 之后你需要确认两件事Base URL 和可用的模型 ID。TaoToken 的 API 地址是 https://taotoken.net/api 这个地址在 OpenClaw 的 provider 配置里会用到。模型 ID 方面你可以在控制台的模型列表里查看当前可用的模型常见的有 deepseek-chat、deepseek-reasoner 等。记下你要用的模型 ID配置时填进去。这里要提醒一点不要把 Key 直接硬编码在会提交到 Git 仓库的配置文件里。OpenClaw 的配置文件通常放在用户目录下的隐藏文件夹里比如~/.openclaw/这个位置不会被 Git 追踪相对安全。但如果你要把配置分享给别人记得先把 Key 替换成占位符。TaoToken 的计费方式是按 token 用量计费你可以在控制台里看到每次请求的 token 消耗和费用明细。对于本地部署的 OpenClaw建议先在控制台里设置一个用量提醒或限额避免调试过程中意外消耗过多。调试阶段用 deepseek-chat 这类性价比高的模型就够了等流程跑通再换更强的模型。如果你之前已经在用其他模型服务商的 API想迁移到 TaoToken只需要把 baseUrl 和 apiKey 换掉模型 ID 对应调整即可。OpenClaw 的 provider 配置支持多个 provider 并存你可以保留原有的配置新增一个 TaoToken 的 provider然后在会话里切换使用。关于 API 通道的稳定性TaoToken 提供的是标准 OpenAI 兼容接口OpenClaw 的openai-completions类型可以直接对接。这意味着你不需要装额外的适配插件配置里指定api为openai-completions就能正常工作。如果你遇到 401 错误优先检查 Key 是否复制完整、有没有多余空格如果遇到连接超时检查网络是否能正常访问 TaoToken 的 API 地址。准备好 Key 和模型 ID 后就可以进入下一节开始配置 Ubuntu 环境和安装 OpenClaw 了。整个前置准备大概 5 分钟主要是注册和复制 Key 的时间。3. 可复制配置Ubuntu 环境检查与 OpenClaw 安装全流程这一节是实操的核心部分每一步都给出完整命令和预期结果。建议按顺序执行遇到报错先看下一节的排查清单。3.1 系统更新与基础依赖安装先更新系统包索引并升级已安装的包sudo apt update sudo apt upgrade -y然后安装基础依赖这些包在后续编译原生模块和下载安装脚本时会用到sudo apt install -y git curl wget build-essential ca-certificates gnupggit 用于拉取源码curl 用于下载安装脚本build-essential 提供 gcc、g、make 等编译工具链ca-certificates 保证 HTTPS 证书校验正常gnupg 用于验证软件源签名。这一步如果网络慢可以换国内镜像源但 Ubuntu 22.04 默认源通常够用。3.2 安装 Node.js 24用 NodeSource 官方源安装 Node.js 24这是目前 OpenClaw 支持最充分的版本curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs安装完成后启用 corepack这样可以用仓库指定的 pnpm 版本sudo corepack enable验证运行时版本node -v npm -v git --version预期输出node 版本为 v24.x或 v22.22.3npm 为 11.x 以上git 为 2.34.1 以上。如果 node -v 显示的是旧版本先卸载再重装sudo apt remove -y nodejs然后重新执行 3.2 节的安装命令。3.3 配置 npm 全局目录并安装 OpenClaw为了避免全局安装时的权限问题先把 npm 的全局目录设到用户目录下mkdir -p $HOME/.npm-global npm config set prefix $HOME/.npm-global echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后设置 npm 镜像源加速下载npm config set registry https://registry.npmmirror.com安装 OpenClawnpm install -g openclawlatest安装完成后验证openclaw --version which openclaw预期能看到版本号如 2026.7.1-2和可执行文件路径在~/.npm-global/bin/openclaw。如果which openclaw找不到检查 PATH 是否包含~/.npm-global/bin可以执行echo $PATH确认。3.4 初始化配置用 onboard 向导或手动配置OpenClaw 提供交互式 onboard 向导执行openclaw onboard --install-daemon在向导中当提示选择 auth method 时选择手动输入 API key 的方式。这里不要填模型服务商的原生 Key而是填 TaoToken 的 Key。模型名称先随便填一个占位后面用手动配置覆盖。如果你更喜欢直接写配置文件可以跳过向导直接编辑~/.openclaw/config.json路径以实际安装为准可以用openclaw config path查看。下面是一个完整的 provider 配置片段把 TaoToken 作为模型通道接入{ models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, api: openai-completions, models: [ { id: deepseek-chat, name: DeepSeek Chat, contextWindow: 131072, maxTokens: 8192 }, { id: deepseek-reasoner, name: DeepSeek Reasoner, contextWindow: 131072, maxTokens: 8192 } ] } } } }如果你用命令行方式写入配置可以用openclaw config set命令把上面的 JSON 作为参数传入注意用单引号包裹避免 shell 转义openclaw config set models.providers.taotoken {baseUrl:https://taotoken.net/api,apiKey:你的TaoToken Key,api:openai-completions,models:[{id:deepseek-chat,name:DeepSeek Chat,contextWindow:131072,maxTokens:8192}]} --strict-json写入成功后会提示Updated models.providers.taotoken并且说明改动不需要重启网关即可生效。3.5 重启网关并验证模型列表配置写完后重启网关服务openclaw gateway restart预期输出包含Restarted systemd service: openclaw-gateway.service。然后列出已配置的模型openclaw models list --provider taotoken预期能看到taotoken/deepseek-chat和taotoken/deepseek-reasoner状态为 configured。如果列表为空检查配置文件路径是否正确、JSON 格式有没有语法错误。3.6 启动会话做一次实际请求执行openclaw进入交互式会话或者用命令行直接发一条测试消息openclaw chat --message 你好测试一下连接如果配置正确你会看到模型返回的回复状态行显示tokens 0/131k开始计数。这一步确认了从本地 OpenClaw 到 TaoToken 通道再到模型的完整链路是通的。4. 验证请求与成功结果从启动日志到 token 计数配置写完后最关键的一步是实际发一次请求确认整条链路真的通了。很多人配置看起来没问题但一请求就报错所以这一节把验证过程拆细给出预期输出和判断标准。先确认网关服务在运行systemctl status openclaw-gateway.service预期看到active (running)如果显示 failed用journalctl -u openclaw-gateway.service -n 50查看最近 50 行日志定位报错原因。然后检查模型列表openclaw models list --provider taotoken正常输出应该类似Model Input Ctx Local Auth Tags taotoken/deepseek-chat text 131k no yes default,configured taotoken/deepseek-reasoner text 131k no yes看到configured和Auth yes说明 Key 已经被识别通道可用。如果 Auth 显示 no说明 Key 没读到检查配置文件里的 apiKey 字段。接下来发一条实际请求。进入交互式会话openclaw在提示符后输入你好我是本地部署测试请回复确认收到。预期模型会返回一段回复同时状态行显示connected | idle agent main | session main | taotoken/deepseek-chat | tokens 12/131k (0%)token 计数从 0 开始增长说明请求和响应都正常走通了。如果状态行一直显示tokens ?/1.0m或者报Unknown model说明模型 ID 没匹配上回到配置里检查 models 数组里的 id 是否和请求时用的模型名一致。如果你想用命令行一次性测试不进入交互模式openclaw chat --message ping --model taotoken/deepseek-chat预期返回模型的回复内容退出码为 0。如果返回非零退出码看终端输出的错误信息对照下一节的排查清单。还有一个验证点是检查请求是否真的走了 TaoToken 通道。你可以在 TaoToken 控制台的用量页面查看最近的请求记录如果能看到对应时间点的 token 消耗说明请求确实经过了这个通道。这一步能排除配置写错但恰好命中了其他 provider 的情况。对于长时间运行的场景建议把网关设为开机自启sudo systemctl enable openclaw-gateway.service这样机器重启后 OpenClaw 会自动拉起不需要手动执行openclaw gateway restart。验证自启是否生效可以重启机器后执行systemctl status openclaw-gateway.service确认状态。如果一切正常到这里本地 OpenClaw 就已经跑通了。你可以继续配置飞书等渠道对接或者加载技能插件扩展功能。核心的模型通道已经稳定后续换模型只需要改配置里的 model id不用动其他部分。5. 常见报错排查401、Unknown model、网关启动失败怎么解这一节把部署过程中最容易遇到的几个报错列出来给出原因和解决方法。遇到问题先在这里对照大部分情况能直接定位。5.1 401 Unauthorized 或 authentication failed报错信息通常长这样Error: 401 Unauthorized {error:{message:Invalid API key,type:authentication_error}}原因TaoToken 的 Key 没填对或者配置文件里的 apiKey 字段有空格、换行、引号转义问题。解决打开配置文件~/.openclaw/config.json检查apiKey字段的值是否和 TaoToken 控制台里复制的一致。注意不要有多余的空格或换行。如果用命令行写入确保 JSON 字符串里的引号正确转义。改完后执行openclaw gateway restart重启网关。5.2 Unknown model: taotoken/deepseek-chat报错信息run error: Unknown model: taotoken/deepseek-chat local ready | error agent main | session main | taotoken/deepseek-chat | tokens ?/1.0m原因配置里的模型 ID 和请求时用的模型名不匹配或者 models 数组里没有这个 id。解决执行openclaw models list --provider taotoken查看实际注册的模型 ID。如果列表为空说明配置没写进去检查openclaw config set命令是否执行成功或者手动编辑配置文件后有没有保存。如果列表里有模型但 ID 不同把请求时的模型名改成列表里的 ID。5.3 local proxy failed 或 connection refused报错信息local proxy failed: dial tcp 127.0.0.1:xxxx: connect: connection refused原因网关服务没启动或者端口被占用。解决先检查服务状态systemctl status openclaw-gateway.service。如果是 stopped执行openclaw gateway restart。如果启动失败看日志journalctl -u openclaw-gateway.service -n 100常见原因是端口冲突可以在配置里改端口或者杀掉占用端口的进程。5.4 reading choices 相关报错报错信息Error: reading choices: unexpected end of JSON input原因API 返回的响应不是预期的 JSON 格式通常是 baseUrl 写错请求打到了错误的端点。解决确认配置里的baseUrl是https://taotoken.net/api不要多加或少加路径。有些服务商的端点需要/v1后缀但 TaoToken 的配置按上面写的即可。改完后重启网关再试。5.5 OAuth 或 auth method 相关报错报错信息Error: OAuth flow failed原因onboard 向导里选了 OAuth 方式但本地环境没有浏览器或者回调地址不通。解决重新执行openclaw onboard在 auth method 选择时改用手动输入 API key 的方式。或者直接跳过向导手动编辑配置文件写入 provider 配置。5.6 npm install 卡在 node-gyp 编译报错信息gyp ERR! build error gyp ERR! stack Error: make failed with exit code: 2原因build-essential 没装全或者 Node 版本不匹配。解决确认sudo apt install -y build-essential已执行。检查node -v是否在支持范围内。如果还是失败尝试清理 npm 缓存后重装npm cache clean --force npm install -g openclawlatest5.7 网关重启后配置没生效现象改了配置文件重启网关后模型列表还是旧的。原因配置文件路径不对改的是另一个文件。解决用openclaw config path查看实际读取的配置文件路径确认你编辑的是同一个文件。有些情况下 OpenClaw 会读取用户目录下的配置而不是系统级配置注意区分。排查时养成看日志的习惯journalctl -u openclaw-gateway.service -f可以实时跟踪日志输出发请求时观察日志里的报错信息比只看终端输出更直接。6. 后续接入与通道管理让本地 OpenClaw 长期稳定跑本地 OpenClaw 跑通之后接下来要考虑的是怎么让它长期稳定运行以及怎么管理模型通道。这一节给几个实用建议都是实际部署中总结出来的。第一件事是把网关设为开机自启前面提过用systemctl enable这里再强调一下。如果你用的是云主机或者经常重启的开发机不开自启的话每次都要手动拉起很容易忘。设置完之后用systemctl is-enabled openclaw-gateway.service确认返回enabled。第二件事是日志轮转。OpenClaw 的网关日志会持续写入时间长了可能占满磁盘。可以配置 logrotate或者定期清理。查看日志大小journalctl -u openclaw-gateway.service --disk-usage如果超过几百 MB用journalctl --vacuum-size100M清理到 100MB 以内。第三件事是 Key 的轮换和管理。TaoToken 控制台里可以创建多个 Key建议给不同用途分配不同的 Key比如一个用于本地调试一个用于生产环境。这样如果某个 Key 泄露只需要禁用那一个不影响其他服务。轮换 Key 时改配置文件里的 apiKey 字段然后openclaw gateway restart即可不需要重装。第四件事是模型切换。随着业务变化你可能需要从 deepseek-chat 换到更强的模型。只需要在配置文件的 models 数组里增加或修改模型 ID然后重启网关。如果新模型在 TaoToken 通道里可用配置里加上对应的 id、name、contextWindow 和 maxTokens 就行。切换时注意 contextWindow 的差异有些模型上下文窗口更小配置里要如实填写否则请求超长会被截断。第五件事是监控用量。TaoToken 控制台提供用量统计你可以定期查看 token 消耗趋势。如果发现某天消耗异常增高检查是不是有异常请求或者配置错误导致重复调用。OpenClaw 的会话日志里也会记录每次请求的 token 数可以对照分析。对于想进一步扩展的读者OpenClaw 支持接入飞书等渠道把本地智能体接到团队协作工具里。接入方式和模型通道配置类似都是在配置文件里增加对应的 provider 或 channel 配置。具体步骤可以参考 OpenClaw 的官方文档或者 TaoToken 的接入文档 https://taotoken.net/api 里面有不同场景的配置示例。最后提醒一点本地部署的优势是数据不出机器但也要注意配置文件里的 Key 安全。不要把~/.openclaw/config.json提交到公开仓库分享配置时先把 Key 替换成占位符。如果机器多人共用给配置文件设置 600 权限chmod 600 ~/.openclaw/config.json这样只有当前用户能读写其他用户无法查看 Key。整个部署流程走下来核心就是环境对齐、配置写对、请求验证这三步。环境用 Ubuntu 22.04 加 Node.js 24 基本不会出大问题配置里 baseUrl 和 apiKey 填对就能通验证时看 token 计数和模型列表确认状态。遇到报错对照第五节的清单大部分能自己解决。跑通之后这套本地 OpenClaw 加 TaoToken 通道的组合可以长期用换模型、加渠道都只需要改配置不用重新部署。
