1. 为什么要在 Ubuntu 22.04.5 上自己部署 openclawopenclaw小龙虾是一个把本地工作区、模型调用、消息通道和定时任务串起来的智能体网关。它跑在你自己的机器上配置文件、会话记忆、技能脚本都留在本地适合想长期挂机跑编码助手、自动化消息或者多模型切换的人。Ubuntu 22.04.5 是 LTS 版本软件源稳定、systemd 和 ufw 都齐全拿来当 openclaw 的宿主系统很省心。这篇教程面向的是第一次接触 openclaw 的读者你不需要懂 Node 生态只要会复制命令、会改一个 JSON 文件就能在半小时内把网关跑起来并且把模型请求统一指向 TaoToken 的 API 通道。整个过程我会按“装环境 → 装 openclaw → 改 openclaw.json → 重启网关 → 验证 18789 端口 → 排错”的顺序走每一步都给出可直接粘贴的命令和预期输出。需要提前说明的是openclaw 默认监听 18789 端口并且绑定在 loopback 上也就是说它只认本机访问。如果你是在虚拟机或云主机里部署后面要么做 SSH 端口转发要么改 bind 配置这两种方式我都会讲到。另外模型接入部分我会用 TaoToken 的统一 Key 来替换默认的第三方地址这样你后续换模型只需要改一个 baseUrl 和 model id不用动其他逻辑。我试过在一台 2 核 4G 的 Ubuntu 22.04.5 虚拟机上完整走一遍从裸系统到浏览器能打开控制面板大概 20 分钟其中大部分时间花在 npm 安装上。下面开始。2. 前置准备Node 22 环境与 openclaw 安装openclaw 对 Node 版本有硬性要求必须不低于 22。Ubuntu 22.04 自带的 apt 源里 Node 版本偏旧所以要用 NodeSource 的脚本重新装。先更新一下系统包索引再导入 NodeSource 的 22.x 源sudo apt update sudo apt install -y curl ca-certificates curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs装完之后验证版本两个命令都要能正常输出node -v npm -v预期结果类似v22.22.2和10.9.7。如果node -v还是旧版本说明 PATH 里残留了系统自带的 node可以用which node看一下路径正常应该是/usr/bin/node。确认无误后安装 openclawcurl -fsSL https://openclaw.ai/install.sh | bash这个脚本会下载安装包并做全局注册中途会停留一会儿耐心等它跑完。安装结束后用下面的命令确认 CLI 可用openclaw --version openclaw status第一次执行openclaw status时因为还没有配置文件它会提示你运行初始化向导。这里有个分叉点向导会让你选择大模型并输入 Key。如果你打算直接用 TaoToken 的统一通道可以在向导里选择跳过Skip因为后面我们会手动改openclaw.json把 provider 指向 TaoToken 的地址。跳过不会影响安装只是暂时没有可用模型。安装脚本还会在~/.openclaw/下生成默认目录结构包括workspace和配置文件。你可以先看一眼ls -la ~/.openclaw/正常情况下能看到openclaw.json可能还没生成、workspace/等。如果openclaw.json不存在运行一次openclaw config get gateway.port会触发它生成默认配置。接下来就是核心的配置环节。3. 可复制配置openclaw.json 接入 TaoToken 统一通道openclaw 的所有行为都由~/.openclaw/openclaw.json驱动。这个文件分几块agents定义默认工作区和主模型gateway管端口、鉴权和绑定地址models定义 provider 和模型列表auth管认证 profile。我们要做的就是把models.providers里的 baseUrl 和 apiKey 换成 TaoToken 的同时把模型 id 对齐。先备份原文件再写入新内容cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak nano ~/.openclaw/openclaw.json下面是一份可直接使用的配置注意把apiKey换成你在 TaoToken 控制台创建的 Keytoken换成你自己生成的一串随机字符串后面浏览器访问要用{ agents: { defaults: { workspace: /root/.openclaw/workspace, models: { taotoken/claude-sonnet-4-5: {} }, model: { primary: taotoken/claude-sonnet-4-5 }, memorySearch: { enabled: false } } }, gateway: { mode: local, auth: { mode: token, token: 76ad1fb5640e0d990d6c5defa27cc60ff49225fb36f7d209 }, port: 18789, bind: loopback, tailscale: { mode: off, resetOnExit: false }, controlUi: { allowInsecureAuth: true }, nodes: { denyCommands: [ camera.snap, camera.clip, screen.record, contacts.add, calendar.add, reminders.add, sms.send, sms.search ] } }, session: { dmScope: per-channel-peer }, tools: { profile: coding }, models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, api: anthropic-messages, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5, reasoning: true, input: [text, image], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 } ] } } }, auth: { profiles: { taotoken:default: { provider: taotoken, mode: api_key } } }, hooks: { internal: { enabled: true, entries: { boot-md: { enabled: true }, command-logger: { enabled: true }, session-memory: { enabled: true } } } }, wizard: { lastRunAt: 2026-04-02T03:23:50.374Z, lastRunVersion: 2026.4.1, lastRunCommand: configure, lastRunMode: local }, meta: { lastTouchedVersion: 2026.4.1, lastTouchedAt: 2026-04-02T03:30:29.924Z } }几个关键点解释一下。baseUrl填https://taotoken.net/api这是 TaoToken 的统一入口不要在后面加/v1之类的后缀openclaw 会按api字段的协议自己拼接。api字段填anthropic-messages表示走 Anthropic 消息格式如果你要接的是 OpenAI 兼容格式的模型这里改成openai-chat即可。models[].id必须和 TaoToken 侧支持的模型名一致写错会在请求时报model not found。gateway.bind是loopback意味着只监听 127.0.0.1。如果你想让局域网内其他机器直接访问可以改成0.0.0.0但那样必须保证auth.mode是token且 token 足够复杂否则等于把控制面板暴露出去。controlUi.allowInsecureAuth设为 true 是为了在 HTTP 下也能用 token 登录生产环境建议配 HTTPS 后关掉。改完保存用 openclaw 自带的校验命令检查 JSON 语法和字段openclaw validate如果输出config is valid说明格式没问题。如果报字段错误对照上面的结构逐项检查最常见的是漏了逗号或者把models写成了数组。4. 启动网关并验证 18789 端口连通性配置校验通过后重启网关让新配置生效。openclaw 的网关进程有时候会残留所以先彻底杀掉再启动pkill -9 -f openclaw sleep 2 nohup openclaw gateway ~/openclaw.log 21 sleep 3 openclaw dashboard --no-openopenclaw dashboard --no-open会输出一个带 token 的访问地址类似http://127.0.0.1:18789/#token76ad1fb5640e0d990d6c5defa27cc60ff49225fb36f7d209记住这个地址token 部分就是你在openclaw.json里写的那个。接着确认网关状态和端口监听openclaw status ss -tlnp | grep 18789openclaw status应该显示 gateway 处于 runningss的输出应该能看到127.0.0.1:18789处于 LISTEN。如果ss没有输出说明进程没起来去看日志tail -n 50 ~/openclaw.log日志里如果出现EADDRINUSE说明 18789 被别的进程占了用lsof -i :18789找到 PID 后 kill 掉或者改gateway.port换一个端口。如果出现Cannot find module多半是 npm 全局包没装好重新跑一遍安装脚本。本机验证通过后如果你是在虚拟机或远程主机上部署需要做端口转发才能在自己电脑的浏览器里打开。最省事的方式是 SSH 本地转发在你自己的电脑上执行ssh -N -L 18789:127.0.0.1:18789 test192.168.0.153把test和 IP 换成你 Ubuntu 机器的用户名和地址。这条命令保持不关然后在浏览器里打开http://127.0.0.1:18789/#token你的token就能看到 openclaw 的控制面板。如果你希望 Ubuntu 防火墙层面也放行比如做其他转发执行sudo ufw allow 18789/tcp sudo ufw reload sudo ufw statusufw status里应该能看到18789/tcp ALLOW Anywhere。注意即使 ufw 放行了因为bind是 loopback外部依然连不上必须配合 SSH 转发或改 bind。这是很多人卡住的地方以为放行端口就能访问结果一直连不上其实是绑定地址的问题。验证模型通道是否真的通了可以在控制面板里发一条测试消息或者用 CLIopenclaw models list openclaw message send --target test --message pingmodels list应该能列出taotoken/claude-sonnet-4-5。如果发消息返回 401说明 apiKey 不对返回model not found说明模型 id 和 TaoToken 侧不一致。5. 常见报错排查401、local proxy failed 与端口占用部署过程中最容易撞上的几类错误我按实际遇到的顺序列一下每条都给出定位方法和修复动作。第一类是 401 Unauthorized。表现是控制面板里发消息后返回401或者invalid api key。原因通常是openclaw.json里models.providers.taotoken.apiKey填错或者 Key 前后带了空格。修复方式是重新复制 Key确认以sk-开头然后openclaw validate再重启网关。还有一种情况是auth.profiles里的 provider 名字和models.providers的键不一致比如 provider 写taotoken但 profile 写kimi:default这会导致认证找不到对应 provider也会报 401。第二类是local proxy failed或connect ECONNREFUSED。这通常出现在网关启动阶段说明 openclaw 尝试连接某个本地代理或上游地址失败。先检查baseUrl是否写成了https://taotoken.net/api/带尾斜杠某些版本对尾斜杠敏感去掉即可。再检查机器能否正常解析和访问外网curl -I https://taotoken.net/api如果这条命令超时说明是网络层问题不是配置问题。另外如果你之前配过系统级代理环境变量HTTP_PROXY之类会干扰 openclaw 的出站请求用env | grep -i proxy检查并 unset 掉。第三类是reading choices或Cannot read properties of undefined (reading choices)。这个报错说明 openclaw 按 OpenAI 格式解析响应但上游返回的是 Anthropic 格式或者反过来。根因是api字段和实际模型协议不匹配。如果你接的是 Anthropic 系模型api必须是anthropic-messages如果接的是 OpenAI 兼容模型改成openai-chat。改完重启网关再试。第四类是端口占用报EADDRINUSE: address already in use :::18789。先用lsof -i :18789或ss -tlnp | grep 18789找到占用进程kill 掉后重启。如果这个端口被系统服务长期占用直接改配置换端口openclaw config set gateway.port 18790然后重启网关访问地址里的端口也要同步改成 18790。第五类是 OAuth 相关报错比如OAuth token expired或refresh failed。openclaw 某些 provider 支持 OAuth 模式如果你在auth.profiles里写了mode: oauth但没走完授权流程就会报这个。最简处理是把 mode 改成api_key用 Key 认证避免 OAuth 刷新逻辑。改完记得openclaw validate。排查时善用日志openclaw logs -f可以实时看输出openclaw logs --error只看错误。openclaw doctor会自动检查端口、依赖、权限和网络openclaw doctor --fix能自动修一部分问题并备份配置。遇到搞不定的先跑一遍 doctor多数环境问题它能直接指出来。6. 把模型请求统一到 TaoToken 的后续用法网关跑起来之后日常使用其实就几件事改模型、看日志、重启。切换模型不用改代码只改openclaw.json里agents.defaults.model.primary的值比如从taotoken/claude-sonnet-4-5换成taotoken/gpt-4o然后在models.providers.taotoken.models数组里补上对应条目重启网关即可。TaoToken 的统一 Key 在这里的好处是你不需要为每个模型单独申请 Key一个 Key 走所有模型换模型只动 model id。如果你要长期挂机跑编码任务或 Agent建议把网关做成 systemd 服务避免 SSH 断开后进程被杀。简单做法是写一个 unit 文件sudo nano /etc/systemd/system/openclaw.service内容如下[Unit] Descriptionopenclaw gateway Afternetwork.target [Service] Typesimple Userroot ExecStart/usr/bin/openclaw gateway run Restarton-failure RestartSec5 [Install] WantedBymulti-user.target然后sudo systemctl daemon-reload sudo systemctl enable --now openclaw。这样开机自启崩溃自动拉起。日志用journalctl -u openclaw -f看。控制面板里的 TUI 聊天支持斜杠命令/elevated full开完整权限执行命令必备/think high深度思考/usage看用量。这些命令在调试 Agent 行为时很有用。如果你只是想让 openclaw 帮你写代码tools.profile保持coding就行要做消息自动化再按需开对应技能。最后提醒一句gateway.auth.token那串字符相当于控制面板的密码别提交到公开仓库。如果你在团队里共享给每个人发不同的 token 并定期轮换。配置改完永远先openclaw validate再重启能省掉一大半排错时间。需要看模型列表和 Key 管理去 TaoToken 控制台接入细节和字段说明翻一下官方文档想先试试模型对话效果可以直接用模型对话页面验证通道是否正常。