一文搞定 OpenClaw 部署：Windows / Ubuntu / macOS 全平台超详细教程（TaoToken 统一 Key 接入版）

1. 为什么三端部署 OpenClaw 最容易卡在 Key 上OpenClaw 是一个把多渠道 AI 助手会话统一管起来的开源平台你可以把它理解成一个「本地网关」WebChat、Telegram、Discord 这些入口都接到同一个 Gateway 上再由 Gateway 去调用背后的模型 API。它适合想在自己机器、NAS 或云主机上跑助手、又希望数据可控的开发者和折腾党。真正上手时Windows、Ubuntu、macOS 三端的安装命令其实都不复杂npm install -g openclaw加openclaw init基本就起来了。麻烦的地方在于「接模型」这一步。OpenClaw 的 workspace 里会散落多个配置文件不同版本可能读config.toml也可能读settings.json再加上环境变量、Gateway 参数很多人装完了却卡在「Gateway 起来了但一发消息就报鉴权失败」。我试过在三个系统上各部署一遍最后发现统一用一套 Key 管理方式最省心所有平台都指向同一个 API 端点、同一个 Key配置文件骨架保持一致换机器时只改路径不改逻辑。这篇就把三端的完整流程、可复制的配置骨架、以及启动后怎么验证 API 真的通了一次讲清楚。2. 部署前先把 TaoToken 统一 Key 准备好不管你在哪个系统部署模型调用这一层建议先统一。TaoToken 提供的是兼容常见 API 调用方式的统一入口你只需要一个 Key就能在 Windows、Ubuntu、macOS 上填同一份配置不用每个平台各申请一套、各记一个密钥。具体操作打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面找到 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 新建一个 Key 并复制保存。这个 Key 就是后面三端配置里要填的api_key。API 的基础地址统一用 https://taotoken.net/api 注意这个地址后面不加任何查询参数配置里直接写它即可。如果你不确定某个模型名该怎么填可以先用模型对话页面验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 在里面选一个模型发一句话确认 Key 有效、模型可用再回到 OpenClaw 里配置能省掉很多「到底是 Key 错还是配置错」的排查时间。注意Key 属于敏感信息不要提交到公开的 Git 仓库。多机同步 workspace 时把含 Key 的配置文件加进.gitignore或者用环境变量注入。3. 三端通用前置Node.js 与 workspace 约定三端的前置条件基本一致Node.js 20 或官方推荐版本、能访问 npm 源、一个专门放 OpenClaw 工作目录的路径。我建议三端都用同一个目录名约定比如openclaw-workspace这样配置骨架可以直接复制只改盘符或家目录前缀。先确认 Node 环境node -v npm -v版本低于 20 的话Windows 去 nodejs.org 下 LTS 安装包Ubuntu 和 macOS 建议用 nvm 管理。全局安装 OpenClawnpm install -g openclaw openclaw --version如果openclaw --version报「不是内部或外部命令」或command not found八成是 npm 全局 bin 目录没进 PATH这个放到第 6 节统一排查。安装成功后创建工作目录并初始化mkdir -p ~/openclaw-workspace # Windows 用 mkdir D:\openclaw-workspace cd ~/openclaw-workspace openclaw initopenclaw init会生成AGENTS.md、SOUL.md、USER.md、HEARTBEAT.md以及skills/目录不同版本略有差异。这些文件定义助手人格、用户信息和技能逻辑先不用改重点是接下来把模型接入配置补上。4. 可复制的三端配置骨架OpenClaw 读取模型配置的位置因版本而异常见的是 workspace 下的config.toml或settings.json。下面给两份骨架你按自己版本选一份把api_key换成第 2 步拿到的 Key。4.1 config.toml 骨架TOML 版本# ~/openclaw-workspace/config.toml [gateway] host 127.0.0.1 port 7777 [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model 你的模型名 [workspace] path .4.2 settings.json 骨架JSON 版本{ gateway: { host: 127.0.0.1, port: 7777 }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: 你的模型名 } }三端差异只在路径写法Windows 的path写成D:\\openclaw-workspaceUbuntu 和 macOS 写成/home/用户名/openclaw-workspace或/Users/用户名/openclaw-workspace。其余字段完全一致这就是统一 Key 的好处——换平台只改路径。如果你不想把 Key 写死在文件里可以用环境变量覆盖。三端设置方式不同# Ubuntu / macOS export TAOTOKEN_API_KEYsk-你的TaoToken密钥 # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的TaoToken密钥然后在配置里把api_key留空或写成占位符由 OpenClaw 从环境变量读取。这样多机同步 workspace 时不会泄露密钥。5. 启动 Gateway 并验证 API 真的通了配置写好后在 workspace 目录里启动openclaw gateway start openclaw gateway statusstatus显示 running 就说明 Gateway 起来了启动日志里会给出监听地址通常是http://127.0.0.1:7777。但「Gateway 起来」不等于「模型能调通」必须单独验证一次 API 请求。最直接的验证方式是先用 curl 打一次 TaoToken 的接口确认 Key 和端点没问题curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: ping}] }返回里带choices字段就说明 Key 有效、端点可达。这一步过了再回到 OpenClaw 里发一条测试消息。如果 OpenClaw 报鉴权错误但 curl 正常问题就在 OpenClaw 的配置读取上重点检查配置文件路径和字段名是否和版本匹配。Windows 上如果 curl 不方便可以用 PowerShellInvoke-RestMethod -Uri https://taotoken.net/api/chat/completions -Method Post -Headers { Authorization Bearer sk-你的TaoToken密钥; Content-Type application/json } -Body {model:你的模型名,messages:[{role:user,content:ping}]}验证通过后长期跑编码或 Agent 任务的话可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要稳定调用额度的场景。接入细节和字段说明可以对照文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 三端常见报错排查6.1 openclaw 命令找不到先看 npm 全局目录在哪npm root -g对应的 bin 目录就是命令所在位置。Windows 一般是C:\Users\用户名\AppData\Roaming\npm把它加进系统 PATH。Ubuntu / macOS 在~/.bashrc或~/.zshrc里加export PATH$HOME/.npm-global/bin:$PATH改完重开终端再试openclaw --version。6.2 Gateway 启动后立即退出按顺序查三件事Node 版本是否达标node -v、端口是否被占用换port值重试、配置是否损坏。最快的定位方法是新建一个干净目录重新 initmkdir ~/openclaw-test cd ~/openclaw-test openclaw init openclaw gateway start新目录能起来说明原 workspace 配置有问题逐步对比差异即可。6.3 控制 UI 打不开先openclaw gateway status确认在跑再看启动日志里的监听地址。本地访问优先用http://127.0.0.1:端口别用localhost有时会解析异常。云主机部署的话检查安全组是否放行了该端口。6.4 升级后配置失效不同版本可能改了配置字段名。升级前备份 workspace升级后对照文档检查config.toml/settings.json的字段。卸载重装npm uninstall -g openclaw npm cache clean --force npm install -g openclaw6.5 多机同步 Key 泄露风险把 workspace 放 Git 同步时含 Key 的文件必须进.gitignore。更稳的做法是配置文件里只写占位符Key 通过环境变量注入每台机器各自设置。这样即使仓库公开也不会暴露密钥。三端部署的核心其实就一句话安装流程各平台照做模型接入统一指向 https://taotoken.net/api 和同一个 Key配置文件骨架保持一致。把第 5 节的 curl 验证当成固定动作每次换机器或升级后先跑一遍能挡掉绝大多数「看起来起来了其实没通」的假成功。