1. 为什么在 Ubuntu 上部署 OpenClaw 值得折腾OpenClaw 是一个开源的个人 AI 助手框架和普通聊天机器人的区别在于它能真正操作你的电脑、定时主动执行任务还能挂到 Telegram、Discord、飞书这类平台上。如果你想在 Ubuntu 上从零把它跑起来核心要解决三件事Node.js 环境、WebUI 启动、以及模型 API 通道的接入。我这次用的是 TaoToken 作为统一 Key/API 通道好处是一个 Key 就能覆盖 Claude、GPT、Gemini 等多家模型不用在 OpenClaw 里来回切换供应商配置。下面这套流程在 Ubuntu 22.04 Node.js 22 上实测跑通包含可复制的config.toml、settings.json骨架以及启动后 WebUI 连通性验证和常见报错排查。适合人群手里有一台 Ubuntu 机器本地或云主机都行、想自建 AI 助手、对命令行不陌生但不想被各家 API 配置绕晕的开发者。整个过程大概 20 分钟前提是网络能正常访问 npm 源。2. 前置准备Node.js 环境与 TaoToken Key2.1 系统与 Node.js 版本要求OpenClaw 对运行环境的要求不算高但 Node.js 版本必须达标否则安装阶段就会报错。项目最低要求推荐操作系统Ubuntu 20.04Ubuntu 22.04Node.jsv18v22 LTS内存4GB8GB磁盘2GB5GB用 nvm 装 Node.js 是最省心的方式避免系统自带版本过旧curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22 node --version看到v22.x.x就说明环境就绪。如果nvm命令找不到先执行source ~/.bashrc再试。2.2 获取 TaoToken API KeyTaoToken 在这里扮演的是「统一模型网关」的角色。OpenClaw 本身支持 Custom provider兼容 OpenAI/Anthropic 协议的端点所以只要把 TaoToken 的 API 地址和 Key 填进去就能通过一个通道调用多家模型。操作路径访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。建议直接进 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成复制出来的 Key 形如sk-xxxx只显示一次先存到安全的地方。注意Key 不要提交到 Git 仓库也不要在截图里暴露。后面我们会用环境变量方式注入避免硬编码。3. 安装 OpenClaw 并接入 TaoToken3.1 全局安装与版本验证npm install -g openclaw openclaw --version输出类似OpenClaw 2026.3.x即安装成功。如果提示权限错误不要用sudo npm install -g正确做法是配置 npm 全局目录或直接用 nvm 管理的 Nodenvm 环境下默认不需要 sudo。3.2 用环境变量注入 TaoToken 配置OpenClaw 的配置分两层config.toml管网关和 providersettings.json管模型选择和运行参数。先设置环境变量让 Key 不落盘到明文配置里export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api想持久化就写进~/.bashrc但更推荐用.env文件配合启动脚本。下面是config.toml骨架放在~/.openclaw/config.toml[gateway] host 127.0.0.1 port 18789 [[providers]] name taotoken type openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY这里type用openai-compatible因为 TaoToken 的/api端点兼容 OpenAI 协议格式。api_key_env指向环境变量名OpenClaw 启动时会自动读取不用把 Key 写死在文件里。3.3 settings.json 模型骨架~/.openclaw/settings.json决定默认用哪个模型、走哪个 provider{ defaultProvider: taotoken, defaultModel: claude-sonnet-4-20250514, fallbackModels: [ gpt-4o, gemini-2.0-flash ], temperature: 0.7, maxTokens: 4096 }defaultModel按你实际需要的模型填TaoToken 支持的模型列表可以在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 里确认。fallbackModels是主模型不可用时的备选建议至少配一个不同厂商的避免单点故障。4. 启动 WebUI 并验证连通性4.1 启动网关服务openclaw gateway start openclaw gateway statusstatus会输出 Dashboard 地址和访问 TokenDashboard: http://127.0.0.1:18789 Token: xxxxxxxxxxxxxxxxxxxxxxx浏览器打开这个地址粘贴 Token 登录。如果服务没起来先看日志openclaw gateway logs --tail 504.2 用 curl 验证 TaoToken 通道在 WebUI 里发消息之前先用命令行确认 API 通道是通的这样能把「网络问题」和「OpenClaw 配置问题」分开排查curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 20 }返回 JSON 里带choices字段就说明 Key 和端点都正常。如果返回 401检查 Key 是否复制完整返回 404检查base_url是不是写成了https://taotoken.net/api不要多加/v1OpenClaw 会自己拼。4.3 WebUI 内实测对话登录 WebUI 后在对话框发一句「你好报一下当前使用的模型」。正常返回说明整条链路打通WebUI → OpenClaw Gateway → TaoToken → 模型。这一步成功后再去配 Telegram、Discord 之类的渠道否则问题会混在一起。5. 本篇常见报错排查5.1 openclaw 命令找不到source ~/.bashrc which node which openclaw如果which openclaw为空说明 npm 全局 bin 目录不在 PATH 里。用npm config get prefix看路径把它加到 PATH。5.2 端口 18789 被占用lsof -i :18789找到占用进程后 kill或者换端口启动openclaw gateway --port 18790换端口后记得同步改config.toml里的port否则下次重启又回到默认值。5.3 API Key 报 401 / 403最常见的原因是环境变量没生效。检查echo $TAOTOKEN_API_KEY如果为空说明当前 shell 没加载。注意export只在当前会话有效写进.bashrc后要source一次。另一个坑是 Key 前后带了空格或换行复制时容易带上用echo -n验证长度。5.4 模型返回超时先确认base_url没写错再检查maxTokens是否设得过大。如果用的是长上下文模型首次请求可能较慢把openclaw gateway logs打开看具体卡在哪一步。TaoToken 的接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有各端点的超时建议对照排查。5.5 WebUI 登录后白屏多半是浏览器缓存了旧版本前端资源。强制刷新CtrlShiftR或换无痕窗口。如果还不行看浏览器控制台有没有 404通常是 Gateway 版本和 WebUI 资源不匹配执行openclaw update升级到最新版。6. 后续配置与长期使用建议跑通之后如果你打算把 OpenClaw 当日常编码助手或挂 Agent 长期跑建议把模型通道固定下来避免每次手动改配置。TaoToken 的 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合这种长期高频调用的场景配合 OpenClaw 的 daemon 模式可以做到开机自启、断线重连。日常维护记住三条命令就够openclaw gateway status看状态、openclaw doctor做诊断、openclaw update升级。配置改完统一用openclaw gateway restart生效不要直接 kill 进程。最后提醒一句config.toml和settings.json建议纳入版本管理但 Key 一定走环境变量。这样换机器时只要重新 export 一次 Key配置可以原样复用。