1. 为什么要在三端折腾 OpenClaw以及它到底能干什么OpenClaw 是一个本地优先的开源 AI 代理框架简单说就是能在你自己电脑上跑起来的“超级助手”。它和网页版聊天工具最大的区别在于它能读写你本机的文件、执行系统命令、调用第三方 API还能把飞书、钉钉这类聊天工具接进来当入口。所有数据留在本机隐私可控这一点对经常处理内部文档和代码的人来说很关键。我这次要交付的是 Windows、macOS、Linux 三端的完整部署流程从 Node.js 环境准备到 config.toml / settings.json 落地再到用 TaoToken 统一 Key 接入模型最后给出各平台的启动验证和报错排查动作。目标很明确你照着做一次跑通全平台。适合谁看如果你是第一次接触 OpenClaw或者之前在某一端装成功了但换平台就卡住这篇就是为你写的。难度不高但细节多尤其是配置文件的路径和字段名写错一个字符就会报错。我会把每一步的命令、参数、预期输出都列清楚遇到问题直接对照第五节排查。先明确一个核心检索词OpenClaw 全平台部署教程重点在“全平台”和“可复制配置”。下面所有操作都围绕这两个点展开。环境要求先对齐一下避免后面白忙要求项最低版本推荐版本Node.jsv22.16v24 LTS操作系统Windows 10 / macOS 12 / LinuxWindows 11 / macOS 14 / Ubuntu 22.04内存4GB8GB网络可访问 npm / GitHub稳定访问Windows 用户特别注意官方建议在 WSL2 下运行体验最顺。如果你坚持原生 Windows请用管理员身份打开 PowerShell后面涉及执行策略的地方我会单独说明。2. TaoToken 前置准备统一 Key 与 Base URL 怎么拿在配置模型之前先把 TaoToken 的接入信息准备好。TaoToken 提供统一的 API 入口你只需要一个 Key 就能调用多种模型省去在多个平台之间切换的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。操作步骤很直接第一步打开官网注册并登录账号。登录后进入控制台地址是 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 就是后面配置文件里要填的 apiKey 字段。第三步确认你要用的模型 ID。TaoToken 支持多种模型你可以在模型对话页面先试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。选一个模型发条消息确认能正常返回再把这个模型 ID 记下来。如果你打算长期做编码或 Agent 类任务可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到字段不确定的时候翻一下。这里要强调三件套的概念Base URL、Key、Model ID。无论你后面用哪种配置方式这三个值必须同时正确。Base URL 统一填 https://taotoken.net/api Key 用你刚创建的Model ID 用你在模型对话里验证过的那个。三者缺一请求就会失败。注意不要把 Key 直接提交到公开仓库。后面我会讲怎么用环境变量隔离。3. 可复制配置config.toml 与 settings.json 骨架OpenClaw 的配置分两层主配置文件 config.toml 和模型相关的 settings.json。不同平台路径不一样先对号入座。Windows 原生路径C:\Users\你的用户名.openclaw\config.toml macOS 路径/Users/你的用户名/.openclaw/config.toml Linux 路径/home/你的用户名/.openclaw/config.toml如果你用 WSL2路径按 Linux 的来在 /home/你的用户名/.openclaw/ 下。先给 config.toml 的骨架直接复制改 Key 和 Model ID 即可# OpenClaw 主配置 [gateway] port 18789 host 127.0.0.1 [model] provider openai baseURL https://taotoken.net/api apiKey 你的TaoToken Key model 你的Model ID timeout 60 [logging] level info再给 settings.json 的骨架放在同一目录下{ provider: openai, baseURL: https://taotoken.net/api, apiKey: 你的TaoToken Key, model: 你的Model ID, temperature: 0.7, maxTokens: 4096 }字段说明provider 填 openai 是因为 TaoToken 兼容 OpenAI 接口格式baseURL 必须带 /api 后缀apiKey 和 model 用你第二步准备的值。temperature 和 maxTokens 按需调整不确定就保持默认。如果你用 Docker 部署配置文件挂载路径是 ~/.openclaw:/root/.openclaw所以宿主机上的 ~/.openclaw/config.toml 会映射进容器。Docker Compose 写法version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 18789:18789 volumes: - ~/.openclaw:/root/.openclaw environment: - OPENCLAW_CONFIG_PATH/root/.openclaw/config.toml启动命令docker compose up -d 。这样配置就落地了容器重启也不会丢。提示如果你用 Cline MCP 或 Codex 的 auth.json同样把 Base URL 填 https://taotoken.net/api Key 和 Model ID 保持一致。三件套对齐任何客户端都能通。4. 启动验证三端分别怎么确认跑通了配置写完后先别急着开 Dashboard用命令行验证最直接。通用第一步检查配置是否被正确读取openclaw config --show预期输出里应该能看到 baseURL 是 https://taotoken.net/api model 是你填的 ID。如果这里显示的还是默认值说明配置文件路径不对回到第三节核对路径。第二步启动网关openclaw gateway start想后台运行加 --daemon openclaw gateway start --daemon第三步发一个测试请求。OpenClaw 自带诊断命令openclaw doctor这个命令会检查 Node 版本、配置文件、网络连通性、模型接口可达性。如果模型那一项显示 OK说明 TaoToken 接入成功。第四步打开 Dashboard 做可视化确认openclaw dashboard浏览器会自动打开 http://127.0.0.1:18789 。如果没自动打开手动输入这个地址。在 Dashboard 左侧菜单点“模型配置”应该能看到你填的 Base URL 和 Model ID。随便发一条消息能收到回复就说明全链路通了。三端差异点Windows 原生环境下如果 openclaw 命令找不到先执行 npm prefix -g 查看全局路径把其中的 bin 目录加到 PATH。PowerShell 里执行策略报错的话运行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass 再重试。macOS 和 Linux 下如果 gateway start 后 Dashboard 打不开先确认端口没被占用lsof -i :18789 。有占用就换端口改 config.toml 里的 port 字段。WSL2 下注意一点Dashboard 的 127.0.0.1 在 Windows 浏览器里可能访问不到需要用 WSL2 的 IP。执行 hostname -I 拿到 IP然后访问 http://那个IP:18789 。验证成功的标志就三个doctor 全绿、Dashboard 能打开、发消息有回复。三个都满足部署就算完成了。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来遇到哪个查哪个。401 Unauthorized这是最常见的。原因通常是 Key 填错、Key 过期、或者 baseURL 少了 /api 后缀。排查动作打开 config.toml确认 apiKey 字段没有多余空格baseURL 是 https://taotoken.net/api 而不是 https://taotoken.net 。改完重启网关openclaw gateway restart 。local proxy failed这个报错说明 OpenClaw 尝试走本地代理但失败了。检查两点一是你的网络环境是否能直连 TaoToken 的 API 端点二是 config.toml 里有没有误配 proxy 字段。如果有 proxy 相关配置先注释掉再试。另外确认防火墙没有拦截 18789 端口。reading choices 报错这个通常出现在模型返回格式不符合预期的时候。原因可能是 Model ID 填错了或者 provider 字段和实际接口不匹配。排查确认 provider 是 openaiModel ID 是你在 TaoToken 模型对话页面验证过的那个。如果还不行把 timeout 从 60 调到 120排除网络慢导致的截断。OAuth 相关报错如果你在配置过程中看到 OAuth 字样说明某个环节触发了授权流程。OpenClaw 本身用 API Key 接入不需要 OAuth。检查是不是在 onboard 向导里选错了选项。重新运行 openclaw onboard 在模型配置那一步选择手动输入 API Key不要选 OAuth 登录。onboard 卡住初始化向导卡住通常是网络问题。先清除配置重来rm -rf ~/.openclaw openclaw onboard --install-daemonWindows 下删除 C:\Users\你的用户名.openclaw 文件夹再重新运行 onboard。命令找不到npm 全局路径没进 PATH。Linux/macOS 下执行echo export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc source ~/.bashrcWindows 下在系统环境变量里把 npm prefix -g 输出的路径加进去。排查顺序建议先看 doctor 输出再查 config.toml 三件套最后看日志 openclaw logs --follow 。日志里会明确告诉你哪一步失败了。6. 长期使用建议与接入入口汇总部署跑通只是开始长期用起来还有几个点值得注意。第一Key 管理。不要把 Key 硬编码在 config.toml 里提交到 Git。可以用环境变量在 config.toml 里写 apiKey ${TAOTOKEN_KEY} 然后在系统环境变量里设置 TAOTOKEN_KEY。OpenClaw 支持这种引用方式。第二版本更新。OpenClaw 迭代快定期执行 npm update -g openclaw 拿最新版。更新后跑一次 openclaw doctor 确认配置没被破坏。第三安全隔离。OpenClaw 能执行系统命令不建议在主力生产机上直接跑。用虚拟机或云服务器更稳妥。Dashboard 端口不要暴露到公网防火墙限制来源 IP。第四模型切换。TaoToken 的好处是统一入口你想换模型只需要改 config.toml 里的 model 字段Base URL 和 Key 不用动。换完重启网关即可。如果你在编码场景用得多Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档随时可查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要新建或管理 Key 就去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。想先试试模型效果模型对话页面在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。最后说一个我踩过的坑WSL2 下 Dashboard 的 127.0.0.1 和 Windows 宿主机的 127.0.0.1 不是同一个必须用 WSL2 的 IP 才能从 Windows 浏览器访问。这个点卡了我半小时希望你别再卡。配置改完记得重启网关很多“改了没生效”的问题都是忘了重启。