1. Ubuntu 上 OpenClaw 到底解决什么问题OpenClaw 是一个跑在本地、通过浏览器访问的 AI 助手网关。你在 Ubuntu 上把它装好之后它会监听本机的一个端口你打开浏览器就能像用网页版聊天工具一样跟模型对话同时它还能挂载技能、记忆、命令执行等能力。适合谁适合手里有一台 Ubuntu 机器物理机、虚拟机、Jetson、树莓派都行、想让模型调用能力留在自己环境里、又不想每换一个模型就改一遍代码的人。真正让人头疼的不是安装本身而是配置。OpenClaw 支持多家模型供应商火山、OpenAI 兼容接口、Anthropic 风格接口各有各的 Key 和 Base URL。你要是每个供应商都单独填一遍settings.json 很快就会变成一团乱麻这个 Key 放哪、那个模型走哪个通道、换机器怎么迁移全是坑。这篇的做法是用 TaoToken 的统一 Key 作为唯一出口把多模型调用收敛到一个 Base URL 上settings.json 只维护一份骨架。装完之后你只需要改模型名就能切换后端不用再动 Key。下面按「环境准备 → 装 OpenClaw → 写 settings.json → curl 验证 → 排错」的顺序走一遍命令都可以直接复制。目标是一次配置完成模型调用准备后面加模型只是改一行。2. 前置准备Node 环境与 TaoToken 统一 Key2.1 用 nvm 装 Node别用系统自带Ubuntu 自带的 Node 版本经常偏旧OpenClaw 对 Node 版本有要求所以先用 nvm 管起来。这套操作在虚拟机、Jetson、树莓派上通用。bash -c $(curl -fsSL https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh) source ~/.nvm/nvm.sh nvm --version nvm install stable nvm use stable node --versionnvm --version能打印版本号说明 nvm 加载成功。node --version建议在 v20 以上。如果你用的是 zsh把source ~/.nvm/nvm.sh这行加到~/.zshrc里否则新开终端 nvm 会失效这是新手最常踩的坑之一。2.2 拿到 TaoToken 统一 KeyTaoToken 在这里的角色是「统一入口」你只申请一个 Key就能通过同一个 Base URL 调用不同模型。对 OpenClaw 来说配置里只需要写一个baseUrl和一个apiKey模型名按需替换即可。操作路径很直接打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 创建一个 Key。创建后立刻复制保存页面刷新后通常不再完整显示。注意Key 只存在你本地配置文件里不要提交到 Git也不要贴到公开聊天记录。settings.json 建议加进.gitignore。接口地址统一用https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。3. 安装 OpenClaw 并写入 settings.json 骨架3.1 全局安装 OpenClawnpm install -g openclaw2026.3.23-2 openclaw --version能打印版本号就说明装好了。如果提示权限错误不要用sudo npm install -g硬来那会把文件属主搞乱正确做法是回到 nvm 环境重装nvm 装的 Node 天然不需要 sudo。3.2 跑一次 onboard 生成基础目录openclaw onboard引导过程里会问你要不要配置平台飞书、微信等、要不要 Web 检索这些先选 Skip技能按需勾选。走完之后 OpenClaw 会在用户目录下生成配置目录通常是~/.openclaw/。确认一下ls -la ~/.openclaw/你应该能看到settings.json或类似命名的配置文件。如果没生成手动创建即可。3.3 settings.json 骨架统一 Key 接入下面这份骨架是核心。它把模型调用统一指向 TaoToken 的 Base URLKey 只写一处。字段名以你本地 OpenClaw 版本为准结构逻辑是通用的一个 provider 块 一个 models 列表。{ gateway: { host: 127.0.0.1, port: 18789 }, providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken统一Key, models: [ claude-sonnet-4-5, gpt-4o-mini, deepseek-chat ] } }, defaultModel: claude-sonnet-4-5, skills: { enabled: [clawhub, summarize] } }几个关键点解释一下。type用openai-compatible因为 TaoToken 的接口兼容 OpenAI 调用格式这样 OpenClaw 内部走标准请求路径不用为每家供应商写适配。baseUrl固定为https://taotoken.net/api不要在后面加/v1之类的后缀具体路径由 OpenClaw 拼接。models数组里放你想用的模型名切换模型时改defaultModel就行Key 和地址完全不用动——这就是「统一 Key」省事的地方。提示如果你之前已经在 onboard 里填过火山或其他供应商的 Key建议把那些 provider 块删掉或注释避免 OpenClaw 在多个 provider 之间选错通道。3.4 重启 Gateway 让配置生效openclaw gateway restart或者直接openclaw restart取决于你的版本。重启后配置才会重新加载。然后打开浏览器访问 onboard 结束时给出的地址形如http://127.0.0.1:18789/#token你的本地访问token这个 token 是 OpenClaw 自己生成的本地访问凭证跟 TaoToken 的 Key 是两回事别搞混。4. 验证通道一条 curl 确认连通配置写完别急着在界面里点先用 curl 直接打 TaoToken 的接口确认 Key 和地址是通的。这一步能把「配置问题」和「OpenClaw 问题」分开。curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的TaoToken统一Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}], max_tokens: 16 }返回里如果出现choices字段和一段模型回复内容说明通道连通、Key 有效、模型名正确。如果返回 401是 Key 问题返回 404多半是路径或模型名写错返回超时检查本机网络出口。curl 通了之后回到 OpenClaw 的 Web UI在模型选择里选claude-sonnet-4-5发一句「你好」能正常回复就说明整条链路打通了。想单独验证模型对话效果也可以直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat 对比一下返回是否一致。如果你打算长期用 OpenClaw 跑编码任务或挂 Agent建议顺手了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 它针对高频编码场景做了额度安排比按次调用更划算。5. 本篇常见错误排查5.1 nvm 命令找不到新开终端后nvm报 command not found是因为没把加载语句写进 shell 配置。解决办法echo source ~/.nvm/nvm.sh ~/.bashrc source ~/.bashrczsh 用户把~/.bashrc换成~/.zshrc。5.2 settings.json 改了不生效OpenClaw 只在启动时读配置改完必须重启 Gateway。另外 JSON 对格式极其严格多一个逗号、少一个引号都会导致整个文件解析失败而报错信息往往不指向具体行。建议用python3 -m json.tool ~/.openclaw/settings.json校验一遍能打印出格式化结果就说明语法没问题。5.3 401 / 403 鉴权失败先确认 Key 前后没有多余空格Bearer和 Key 之间是一个空格。再确认 Key 没有过期或被删除。如果 curl 能通但 OpenClaw 里报 401检查 settings.json 里apiKey字段是不是被 onboard 生成的旧值覆盖了。5.4 模型名报 not found模型名必须和 TaoToken 侧支持的名称完全一致大小写、连字符都不能差。不确定的话先用 curl 拿一个确定可用的模型名测通再写进 settings.json。切换模型只改defaultModel不要动 provider 块。5.5 端口被占用18789被别的进程占了Gateway 起不来。查一下ss -tlnp | grep 18789要么杀掉占用进程要么在 settings.json 的gateway.port里换一个端口重启后访问地址的端口号也要同步改。6. 后续怎么扩展骨架搭好之后加模型就是往providers.taotoken.models数组里加一个名字再把defaultModel指过去重启即可。想接 Anthropic 风格的调用参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 里的说明调整type字段。整套配置的核心思路就一句话Key 和地址只维护一份变化的部分收敛到模型名。这样无论你后面换多少模型、迁多少台机器settings.json 的骨架都不用重写。
1. Ubuntu 上 OpenClaw 到底解决什么问题OpenClaw 是一个跑在本地、通过浏览器访问的 AI 助手网关。你在 Ubuntu 上把它装好之后它会监听本机的一个端口你打开浏览器就能像用网页版聊天工具一样跟模型对话同时它还能挂载技能、记忆、命令执行等能力。适合谁适合手里有一台 Ubuntu 机器物理机、虚拟机、Jetson、树莓派都行、想让模型调用能力留在自己环境里、又不想每换一个模型就改一遍代码的人。真正让人头疼的不是安装本身而是配置。OpenClaw 支持多家模型供应商火山、OpenAI 兼容接口、Anthropic 风格接口各有各的 Key 和 Base URL。你要是每个供应商都单独填一遍settings.json 很快就会变成一团乱麻这个 Key 放哪、那个模型走哪个通道、换机器怎么迁移全是坑。这篇的做法是用 TaoToken 的统一 Key 作为唯一出口把多模型调用收敛到一个 Base URL 上settings.json 只维护一份骨架。装完之后你只需要改模型名就能切换后端不用再动 Key。下面按「环境准备 → 装 OpenClaw → 写 settings.json → curl 验证 → 排错」的顺序走一遍命令都可以直接复制。目标是一次配置完成模型调用准备后面加模型只是改一行。2. 前置准备Node 环境与 TaoToken 统一 Key2.1 用 nvm 装 Node别用系统自带Ubuntu 自带的 Node 版本经常偏旧OpenClaw 对 Node 版本有要求所以先用 nvm 管起来。这套操作在虚拟机、Jetson、树莓派上通用。bash -c $(curl -fsSL https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh) source ~/.nvm/nvm.sh nvm --version nvm install stable nvm use stable node --versionnvm --version能打印版本号说明 nvm 加载成功。node --version建议在 v20 以上。如果你用的是 zsh把source ~/.nvm/nvm.sh这行加到~/.zshrc里否则新开终端 nvm 会失效这是新手最常踩的坑之一。2.2 拿到 TaoToken 统一 KeyTaoToken 在这里的角色是「统一入口」你只申请一个 Key就能通过同一个 Base URL 调用不同模型。对 OpenClaw 来说配置里只需要写一个baseUrl和一个apiKey模型名按需替换即可。操作路径很直接打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 创建一个 Key。创建后立刻复制保存页面刷新后通常不再完整显示。注意Key 只存在你本地配置文件里不要提交到 Git也不要贴到公开聊天记录。settings.json 建议加进.gitignore。接口地址统一用https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。3. 安装 OpenClaw 并写入 settings.json 骨架3.1 全局安装 OpenClawnpm install -g openclaw2026.3.23-2 openclaw --version能打印版本号就说明装好了。如果提示权限错误不要用sudo npm install -g硬来那会把文件属主搞乱正确做法是回到 nvm 环境重装nvm 装的 Node 天然不需要 sudo。3.2 跑一次 onboard 生成基础目录openclaw onboard引导过程里会问你要不要配置平台飞书、微信等、要不要 Web 检索这些先选 Skip技能按需勾选。走完之后 OpenClaw 会在用户目录下生成配置目录通常是~/.openclaw/。确认一下ls -la ~/.openclaw/你应该能看到settings.json或类似命名的配置文件。如果没生成手动创建即可。3.3 settings.json 骨架统一 Key 接入下面这份骨架是核心。它把模型调用统一指向 TaoToken 的 Base URLKey 只写一处。字段名以你本地 OpenClaw 版本为准结构逻辑是通用的一个 provider 块 一个 models 列表。{ gateway: { host: 127.0.0.1, port: 18789 }, providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken统一Key, models: [ claude-sonnet-4-5, gpt-4o-mini, deepseek-chat ] } }, defaultModel: claude-sonnet-4-5, skills: { enabled: [clawhub, summarize] } }几个关键点解释一下。type用openai-compatible因为 TaoToken 的接口兼容 OpenAI 调用格式这样 OpenClaw 内部走标准请求路径不用为每家供应商写适配。baseUrl固定为https://taotoken.net/api不要在后面加/v1之类的后缀具体路径由 OpenClaw 拼接。models数组里放你想用的模型名切换模型时改defaultModel就行Key 和地址完全不用动——这就是「统一 Key」省事的地方。提示如果你之前已经在 onboard 里填过火山或其他供应商的 Key建议把那些 provider 块删掉或注释避免 OpenClaw 在多个 provider 之间选错通道。3.4 重启 Gateway 让配置生效openclaw gateway restart或者直接openclaw restart取决于你的版本。重启后配置才会重新加载。然后打开浏览器访问 onboard 结束时给出的地址形如http://127.0.0.1:18789/#token你的本地访问token这个 token 是 OpenClaw 自己生成的本地访问凭证跟 TaoToken 的 Key 是两回事别搞混。4. 验证通道一条 curl 确认连通配置写完别急着在界面里点先用 curl 直接打 TaoToken 的接口确认 Key 和地址是通的。这一步能把「配置问题」和「OpenClaw 问题」分开。curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的TaoToken统一Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}], max_tokens: 16 }返回里如果出现choices字段和一段模型回复内容说明通道连通、Key 有效、模型名正确。如果返回 401是 Key 问题返回 404多半是路径或模型名写错返回超时检查本机网络出口。curl 通了之后回到 OpenClaw 的 Web UI在模型选择里选claude-sonnet-4-5发一句「你好」能正常回复就说明整条链路打通了。想单独验证模型对话效果也可以直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat 对比一下返回是否一致。如果你打算长期用 OpenClaw 跑编码任务或挂 Agent建议顺手了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 它针对高频编码场景做了额度安排比按次调用更划算。5. 本篇常见错误排查5.1 nvm 命令找不到新开终端后nvm报 command not found是因为没把加载语句写进 shell 配置。解决办法echo source ~/.nvm/nvm.sh ~/.bashrc source ~/.bashrczsh 用户把~/.bashrc换成~/.zshrc。5.2 settings.json 改了不生效OpenClaw 只在启动时读配置改完必须重启 Gateway。另外 JSON 对格式极其严格多一个逗号、少一个引号都会导致整个文件解析失败而报错信息往往不指向具体行。建议用python3 -m json.tool ~/.openclaw/settings.json校验一遍能打印出格式化结果就说明语法没问题。5.3 401 / 403 鉴权失败先确认 Key 前后没有多余空格Bearer和 Key 之间是一个空格。再确认 Key 没有过期或被删除。如果 curl 能通但 OpenClaw 里报 401检查 settings.json 里apiKey字段是不是被 onboard 生成的旧值覆盖了。5.4 模型名报 not found模型名必须和 TaoToken 侧支持的名称完全一致大小写、连字符都不能差。不确定的话先用 curl 拿一个确定可用的模型名测通再写进 settings.json。切换模型只改defaultModel不要动 provider 块。5.5 端口被占用18789被别的进程占了Gateway 起不来。查一下ss -tlnp | grep 18789要么杀掉占用进程要么在 settings.json 的gateway.port里换一个端口重启后访问地址的端口号也要同步改。6. 后续怎么扩展骨架搭好之后加模型就是往providers.taotoken.models数组里加一个名字再把defaultModel指过去重启即可。想接 Anthropic 风格的调用参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 里的说明调整type字段。整套配置的核心思路就一句话Key 和地址只维护一份变化的部分收敛到模型名。这样无论你后面换多少模型、迁多少台机器settings.json 的骨架都不用重写。
