1. Ubuntu 部署 OpenClaw 前先把 Node.js 运行环境这件事想清楚OpenClaw 是一个跑在 Node.js 上的 AI 助手网关你可以把它理解成一个「本地中枢」它负责连接各种大模型 API、管理会话、调度技能然后通过 Web 控制台或消息渠道跟你交互。适合谁用想在自有服务器上跑一个可控 AI 助手的开发者、需要把模型能力接进内部工具的小团队以及单纯想折腾一下自托管 AI 网关的技术爱好者。它不是什么轻量脚本而是一个需要长期驻留后台的服务所以部署方式直接决定了你后面维护起来是省心还是糟心。很多人第一次在 Ubuntu 上装 OpenClaw卡住的地方往往不是 OpenClaw 本身而是 Node.js 版本和 systemd 服务托管这两件事。Ubuntu 自带的 apt 源里 Node.js 版本通常偏旧直接apt install nodejs装出来的可能是 18.x 甚至更早而 OpenClaw 要求 Node.js 22 以上。版本不对后面npm install -g openclaw要么报 engine 不兼容要么装上了运行时报语法错误。另一个坑是服务托管如果你只是openclaw gateway start手动跑着SSH 一断开进程就没了服务器一重启更是全丢。所以这篇的重点就放在两件事上——把 Node.js 22 装干净用 systemd 把 OpenClaw 托管成开机自启的常驻服务。我试过在一台 2 核 4G 的 Ubuntu 22.04 云主机上从零走一遍整个过程大概十几分钟其中大部分时间花在下载依赖上。下面按顺序来先准备系统基础环境再装 Node.js然后装 OpenClaw 并初始化最后写 systemd unit 文件做服务托管和验证。每一步都给可复制的命令和预期输出你照着敲就行。在开始之前先确认你的 Ubuntu 版本。执行lsb_release -a预期看到Ubuntu 22.04.x LTS或24.04.x LTS。20.04 也能用但建议至少 22.04。硬件方面个人测试 2 核 4G 够跑网关本身如果你打算在本地加载模型权重那内存和显存要另算这篇只讲网关部署不涉及本地模型推理。系统基础工具先补齐避免后面编译原生模块时缺东西sudo apt update sudo apt upgrade -y sudo apt install -y curl git wget build-essential libssl-dev python3 make g libvips-dev libatomic1这里build-essential提供 gcc/g/makelibssl-dev是很多 npm 原生模块编译时要用的libvips-dev跟图像处理相关libatomic1提供原子操作支持。装完这些Node.js 环境准备的地基就打好了。顺手把时间同步确认一下时间不对会导致 HTTPS 证书校验失败后面调模型 API 会莫名其妙报错timedatectl status sudo timedatectl set-ntp true看到System clock synchronized: yes就放心了。这一步很多人忽略但确实是排查「API 调用失败」时经常被翻出来的原因。2. Node.js 22 安装与 TaoToken 接入前置准备Node.js 的安装方式有三种我按推荐程度排一下。第一种是 NodeSource 官方源适合生产环境装完就是系统级的 node 和 npmsystemd 服务调用路径清晰不会出现「手动能跑、服务里找不到 node」的问题。第二种是 nvm适合你机器上还要跑别的 Node 项目、需要多版本切换的场景但要注意 nvm 装出来的 node 在用户目录下systemd 服务里得写绝对路径。第三种是二进制包手动解压适合离线或需要精确控制安装位置的场景维护成本最高。生产部署我建议直接用 NodeSource路径干净。执行curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs装完验证node -v npm -v预期输出v22.x.x和对应的 npm 版本比如v22.14.0和10.9.x。如果node -v还是旧版本说明系统里之前装过 node先sudo apt remove nodejs清掉再重装。接下来是 OpenClaw 的安装。官方提供一键脚本也支持 npm 全局安装。一键脚本会自动检测环境、装依赖适合新手curl -fsSL https://openclaw.ai/install.sh | bash如果你更想自己掌控安装过程用 npm 全局装npm install -g openclawlatest装完跑一下诊断openclaw --version openclaw doctoropenclaw doctor输出No blocking issues found就说明基础环境没问题。如果这里报 Node 版本不兼容回到上一步确认 node 版本。现在说 TaoToken 的前置准备。OpenClaw 本身是个网关它需要接一个大模型后端才能干活。TaoToken 提供统一的模型接入能力你可以在它的控制台里创建 API Key然后把这个 Key 填到 OpenClaw 的模型配置里。具体来说你需要拿到三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/apiAPI Key 去控制台的 API Keys 页面生成Model ID 根据你选的模型填比如claude-sonnet-4-5这类。这里要提醒一句OpenClaw 的模型配置支持 OpenAI 兼容协议TaoToken 的接口正好是兼容格式所以填进去就能用。你不需要改 OpenClaw 的源码只要在配置文件里把 provider 的 baseUrl 指向 TaoToken 就行。这一步做完OpenClaw 就有了「大脑」后面 systemd 托管起来它才能正常响应请求。如果你还没生成 Key先去控制台建一个注意 Key 只在创建时显示一次复制好存起来。模型对话页面可以先测一下 Key 是否可用确认能正常返回再往下走避免后面服务起来了却因为 Key 问题一直报 401。3. 可复制的 OpenClaw 配置与 systemd unit 文件模板OpenClaw 的配置文件默认在~/.openclaw/openclaw.json。初始化向导openclaw onboard会生成一份基础配置但模型接入部分我建议手动改因为向导里的选项不一定覆盖 TaoToken。下面是一份可以直接参考的配置片段路径和字段名跟实际文件保持一致{ gateway: { port: 18789, mode: local, bind: loopback }, models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5 } ] } }, default: taotoken/claude-sonnet-4-5 } }三个关键字段对齐一下Base URL 是https://taotoken.net/apiAPI Key 是你控制台生成的那串Model ID 填你实际要用的模型标识。default字段的格式是provider名/模型id这里就是taotoken/claude-sonnet-4-5。改完保存先别急着起服务用openclaw doctor再跑一遍确认配置能被解析。接下来是 systemd unit 文件。OpenClaw 自带openclaw service install命令但如果你想完全掌控服务定义手动写 unit 文件更透明。在~/.config/systemd/user/目录下创建openclaw-gateway.service[Unit] DescriptionOpenClaw Gateway Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple ExecStart/usr/bin/openclaw gateway --port 18789 Restartalways RestartSec5 WorkingDirectory%h/.openclaw EnvironmentNODE_ENVproduction StandardOutputjournal StandardErrorjournal [Install] WantedBydefault.target几个地方要注意。ExecStart里的路径必须是 node 和 openclaw 的绝对路径用which openclaw确认一下如果是 nvm 装的路径会类似/home/你的用户名/.nvm/versions/node/v22.x.x/bin/openclaw。WorkingDirectory指向配置目录这样 OpenClaw 能找到openclaw.json。Restartalways配合RestartSec5实现崩溃后 5 秒自动拉起。WantedBydefault.target是用户级服务开机自启的关键。写完后重新加载并启用systemctl --user daemon-reload systemctl --user enable openclaw-gateway systemctl --user start openclaw-gateway这里有个容易踩的坑用户级 systemd 服务默认在你登出后就停了。要让它在没登录的情况下也保持运行需要开启 lingersudo loginctl enable-linger $USER执行完可以用loginctl show-user $USER | grep Linger确认输出Lingeryes。这一步不做服务器重启后服务不会自动起来很多人以为 enable 了就万事大吉结果重启后访问不了就是漏了 linger。4. 验证请求从服务状态到模型对话的完整链路服务起来之后先看状态systemctl --user status openclaw-gateway预期看到Active: active (running)下面有进程 ID 和最近的日志行。如果显示failed直接看日志journalctl --user -u openclaw-gateway -n 50 --no-pager日志里最常见的两类错误一是Cannot find module说明 openclaw 路径不对或没装好二是EADDRINUSE说明 18789 端口被占用lsof -i :18789找到占用进程处理掉或者改配置里的端口。服务状态正常后用 OpenClaw 自带的检查命令确认网关运行时openclaw gateway status预期输出里有Runtime: running和RPC probe: ok。如果 RPC probe 失败通常是配置里的 mode 或 bind 设置有问题回到配置文件确认gateway.mode是local、bind是loopback。接下来验证模型链路。最直接的方式是用 OpenClaw 的命令行发一条测试消息openclaw message send --to default --text 你好请回复你的模型名称如果配置正确你会看到模型返回的内容。如果报 401说明 API Key 不对或没生效如果报连接超时检查服务器能不能访问https://taotoken.net/api用curl -I https://taotoken.net/api测一下连通性。Web 控制台也可以验证。默认监听http://127.0.0.1:18789如果你在本地机器上直接浏览器打开如果是远程服务器用 SSH 端口转发ssh -L 18789:127.0.0.1:18789 你的用户名服务器IP然后在本地浏览器访问http://127.0.0.1:18789输入配置里的 token 就能进控制台。在对话框里发一条消息收到回复就说明整条链路通了systemd 拉起服务 → 网关监听端口 → 模型配置指向 TaoToken → API 调用成功返回。再补一个开机自启的验证。重启服务器sudo reboot等机器起来后重新 SSH 上去直接执行systemctl --user status openclaw-gateway如果显示active (running)且启动时间是你重启后的时间说明开机自启生效了。这一步是整个部署的最终验收过了就说明你的 OpenClaw 已经是一个稳定的常驻服务。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth部署过程中有几类报错出现频率特别高我按实际遇到的顺序整理一下每个都给定位方法和处理动作。401 Unauthorized。这个基本都出在模型配置上。现象是服务能起来但一发消息就报 401。先确认openclaw.json里apiKey字段填的是完整的 Key没有多余空格或换行。然后确认baseUrl是https://taotoken.net/api注意结尾不要多加/v1之类的路径OpenClaw 会自己拼接。如果 Key 确认没问题还是 401去控制台看这个 Key 是否被禁用或额度耗尽。改完配置记得systemctl --user restart openclaw-gateway配置不会热加载。local proxy failed。这个报错通常出现在你环境里配了 HTTP 代理但代理不可达的时候。OpenClaw 启动时会读取http_proxy/https_proxy环境变量如果这些变量指向一个已经关掉的代理请求就会失败。检查env | grep -i proxy如果有输出且代理确实不用了在 systemd unit 文件里显式清掉加一行EnvironmentNO_PROXY*或者在[Service]段里UnsetEnvironmenthttp_proxy https_proxy。改完daemon-reload再重启服务。reading choices 相关报错。这类错误一般长这样Cannot read properties of undefined (reading choices)。它说明 OpenClaw 拿到了一个不符合 OpenAI 格式的响应解析choices字段时炸了。原因通常是 baseUrl 指向的接口返回了错误页或非标准 JSON。用 curl 直接打一下接口确认返回结构curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:hi}]}正常应该返回带choices数组的 JSON。如果返回的是 HTML 或错误信息说明 baseUrl 或路径不对回到配置里核对。OAuth 相关报错。如果你在初始化时选了需要 OAuth 的模型提供商但没完成授权流程会看到 token 获取失败之类的提示。处理方式是重新跑openclaw onboard在模型提供商那一步选 TaoToken 这种基于 API Key 的方式避开 OAuth 流程。已经配好的可以手动改openclaw.json把 provider 的type改成openai-compatible填上 baseUrl 和 apiKey。再补一个 systemd 特有的坑服务启动时报status203/EXEC。这是ExecStart路径不对systemd 找不到可执行文件。用which openclaw拿到绝对路径填进去nvm 用户尤其容易遇到因为 nvm 的路径带版本号升级 node 后路径会变。解决办法是在 unit 文件里用固定的绝对路径或者干脆用 NodeSource 装的系统级 node路径稳定在/usr/bin/openclaw。排查完这些你的服务基本就能稳定跑了。如果还有问题journalctl --user -u openclaw-gateway -f实时看日志错误信息通常写得很直白。6. 把 OpenClaw 长期跑起来接入方式与后续维护服务稳定运行之后接下来要考虑的是怎么把它用起来以及长期维护的几个动作。OpenClaw 的接入方式主要有两种Web 控制台和消息渠道。Web 控制台适合调试和日常对话消息渠道适合把 AI 助手接进你的工作流。如果你打算长期用它做编码辅助或 Agent 任务建议了解一下 Coding Plan 这类按周期计费的方式比按量调用更可控适合高频使用场景。日常维护方面几个命令要记牢。更新 OpenClawnpm update -g openclaw systemctl --user restart openclaw-gateway看日志journalctl --user -u openclaw-gateway -f改配置后重启systemctl --user restart openclaw-gateway日志轮转也建议配上避免 journal 占满磁盘。在/etc/systemd/journald.conf里设置SystemMaxUse500M然后sudo systemctl restart systemd-journald。如果你需要从局域网其他设备访问控制台改配置里的gateway.bind为lan并在controlUi.allowedOrigins里加上你的局域网 IP。但记住不要把 18789 端口直接暴露到公网需要远程访问就用 SSH 隧道或反向代理加认证。最后说一个实际经验systemd 用户服务的环境变量跟你的登录 shell 是隔离的。你在.bashrc里export的变量服务里读不到。如果 OpenClaw 依赖某个环境变量一定要写进 unit 文件的Environment行里。这个坑我在第一次配的时候踩过手动跑正常、服务跑就报错查了半天才发现是环境变量没传进去。整套流程走下来你得到的是一台重启后自动拉起、崩溃后自动重启、配置集中在~/.openclaw/openclaw.json的 OpenClaw 网关。后面要换模型改配置重启即可要加消息渠道在控制台里配要升级npm update加重启。部署这件事一次做对后面就省心了。