OpenClaw 完整安装教程（2026 全平台通用版）：从 Node.js 到 Docker 的 TaoToken 接入配置

1. OpenClaw 是什么为什么 2026 年值得本地部署OpenClaw 是一款可以跑在自己电脑上的 AI 助手工具支持接入 GLM-4.6、Claude 等主流大模型用来做代码辅助、自动化工作流、文档处理这类事情。它和网页版 AI 最大的区别在于模型跑在你自己的机器上数据不出本地模型可以随时切换API Key 也由你自己管理。适合谁三类人最合适一是对数据隐私敏感的开发者二是想统一管理多个模型 Key 的团队三是喜欢折腾本地工具、想把 AI 嵌进自己工作流的技术爱好者。我第一次接触 OpenClaw 是因为手头同时用着好几个模型的 Key切换起来特别烦后来发现它可以用一个统一的 Key 通道把 GLM-4.6 这类模型接进来配置一次就能在 Web 控制台和 VS Code 里共用省了不少事。这篇教程会把 Windows、macOS、Linux 三个平台的完整安装流程走一遍覆盖 Node.js 环境准备、npm 全局安装、Docker 容器化部署三条路径最后用 TaoToken 的统一 Key 通道把 GLM-4.6 接进去跑通第一个实例。整个过程按步骤走30 分钟内能完成。在开始之前先确认你的机器满足基本条件。OpenClaw 对系统版本有要求macOS 12 及以上、Linux 建议 Ubuntu 20.04 / Debian 11 / Fedora 38、Windows 10 或 11 都可以。硬性依赖是 Node.js v20 以上推荐用 v22 LTS因为部分依赖包在 v20 早期版本上会有兼容问题。如果你打算用 Docker 方式部署那本机需要先装好 Docker Desktop 或 Docker Engine版本 20.10 以上即可。这里有个容易忽略的点OpenClaw 本身不绑定任何模型厂商它只是一个调度层。你给它一个 Base URL、一个 API Key、一个模型 ID它就能把请求转发出去。所以模型接入这块完全取决于你用什么通道。后面我会用 TaoToken 的统一 Key 通道来演示因为它把多个模型的接入方式统一了配置片段写一次就能复用。另外提醒一句安装前先确认你的终端能正常访问外网npm 源和 Docker 镜像拉取都需要网络。如果你在公司内网可能需要提前配置好 npm 镜像源和 Docker registry mirror这部分不在本篇展开遇到问题可以看第五章的排查部分。2. Node.js 环境准备与 npm 全局安装 OpenClaw 踩坑记录这一章把 Node.js 装好然后用 npm 全局安装 OpenClaw。先装 Node.js分平台操作。macOS 用户用 Homebrew 最省事brew install node22装完后把 node22 加入 PATH如果你用的是 zshecho export PATH/opt/homebrew/opt/node22/bin:$PATH ~/.zshrc source ~/.zshrcLinuxUbuntu / Debian用 NodeSource 的源curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejsFedora 用户可以直接sudo dnf install nodejs但要注意版本如果源里低于 v20还是走 NodeSource 更稳。Windows 用户到 Node.js 官网下载 v22 LTS 的安装包一路下一步即可。装完后打开 PowerShell 验证node -v npm -v两个命令都能输出版本号说明环境就绪。如果node -v报「不是内部或外部命令」说明 PATH 没生效重启终端或者手动把 Node.js 安装目录加进系统环境变量。Node.js 装好后用 npm 全局安装 OpenClaw。macOS / Linux 上如果遇到权限报错加 sudosudo npm install -g openclawlatestWindows 直接用npm install -g openclawlatestmacOS 上有个高频坑安装过程中 sharp 这个图像处理依赖会尝试编译全局 libvips如果本机没装 libvips就会报一堆node-gyp相关的错。绕过方式是加一个环境变量让它忽略全局 libvipsSHARP_IGNORE_GLOBAL_LIBVIPS1 npm install -g openclawlatest如果还是失败就先装系统级 vips 再重装brew install vips npm install -g openclawlatest安装完成后验证openclaw --version能输出版本号就说明 npm 安装路径通了。如果提示command not found检查 npm 的全局 bin 目录是否在 PATH 里用npm config get prefix看一下路径然后把它加进 PATH。这里补充一个细节npm 全局安装的包默认放在用户目录下macOS 是/usr/local/lib/node_modules或 Homebrew 的/opt/homebrew/lib/node_modulesLinux 是/usr/lib/node_modules。如果你之前用 nvm 管理 Node 版本全局包会跟着 Node 版本走切换版本后需要重新安装。这也是为什么后面 Docker 方式在团队协作里更受欢迎——环境隔离干净不依赖宿主机的 Node 版本。3. Docker 容器化部署 OpenClaw 与 TaoToken 统一 Key 配置片段如果你不想在宿主机上装一堆依赖Docker 是最干净的方式。先确认 Docker 可用docker --version然后拉取并启动 OpenClaw 容器docker run -d \ --name openclaw \ -p 3000:3000 \ -v ~/.openclaw:/root/.openclaw \ openclaw/openclaw:latest这条命令做了三件事容器命名为 openclaw把宿主机 3000 端口映射到容器把本地~/.openclaw目录挂载进容器做数据持久化。这样即使容器被删配置和会话记录还在。容器起来后进入容器执行初始化向导docker exec -it openclaw openclaw onboard向导会依次问你几个问题风险告知选 Yes配置模式选 QuickStart然后进入模型 API Key 配置环节。这里就是接入 TaoToken 统一 Key 通道的关键步骤。TaoToken 的接入信息如下Base URL 用https://taotoken.net/apiAPI Key 到控制台创建模型 ID 填glm-4.6。如果你用的是配置文件方式OpenClaw 的配置目录在~/.openclaw/config.json对应的 JSON 片段长这样{ models: { default: glm-4.6, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: glm-4.6 } } } }如果你更习惯用 TOML 格式部分版本支持等价写法是[models] default glm-4.6 [models.providers.taotoken] baseUrl https://taotoken.net/api apiKey sk-你的TaoToken密钥 modelId glm-4.6三件套记牢Base URL、API Key、Model ID缺一不可。Base URL 决定请求发到哪API Key 决定身份Model ID 决定调哪个模型。很多人配置失败就是这三者有一个写错了尤其是 Base URL 末尾多写或少写/api。配置写完后重启容器让配置生效docker restart openclaw如果你用的是 npm 安装方式配置文件路径一样改完执行openclaw restart即可。这里有个小技巧配置改完后先用openclaw config validate检查一遍语法避免 JSON 格式错误导致服务起不来。关于 API Key 的获取到 TaoToken 控制台创建一个即可创建后复制保存页面上只显示一次。如果你还没账号先注册再创建 Key。整个流程不复杂重点是别把 Key 泄露到公开仓库里建议用环境变量注入而不是硬编码在配置文件里。4. 启动 gateway 与 dashboard 验证 GLM-4.6 请求是否跑通配置完成后OpenClaw 需要两个进程配合gateway 负责转发请求dashboard 提供 Web 控制台。开两个终端窗口。窗口 A 启动网关openclaw gateway窗口 B 启动控制台openclaw dashboarddashboard 启动后会自动打开浏览器地址是http://localhost:3000。如果没自动打开手动访问即可。Docker 方式的话gateway 和 dashboard 都在容器里跑直接访问宿主机的 3000 端口就行。打开 Web 控制台后先做一次模型连通性验证。在对话框里输入一句简单的话比如「用一句话解释什么是递归」然后发送。如果配置正确几秒内会返回 GLM-4.6 的回复。这一步能跑通说明 Base URL、API Key、Model ID 三件套都对了。如果你想用命令行验证可以用 curl 直接打 TaoToken 的接口curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: glm-4.6, messages: [{role: user, content: 你好}] }返回 JSON 里如果有choices字段且内容正常说明 Key 通道没问题。这一步很关键因为它把 OpenClaw 这一层剥掉了直接验证 TaoToken 通道本身是否可用。如果 curl 通了但 OpenClaw 不通问题就在 OpenClaw 配置如果 curl 也不通问题在 Key 或网络。实测下来最常见的成功结果是curl 返回 200JSON 里有choices[0].message.contentOpenClaw 控制台里能看到模型回复且 dashboard 顶部的模型名显示glm-4.6。两个都满足就算跑通了。如果你在 VS Code 里也想用OpenClaw 支持通过本地 gateway 暴露的接口接入配置里填http://localhost:3000作为 endpoint模型选 glm-4.6 即可。这样 Web 控制台和编辑器共用同一个 Key 通道不用重复配置。5. OpenClaw 安装常见报错排查401、local proxy failed、reading choices这一章把安装和接入过程中最容易撞上的几个报错集中处理。每个报错我都给出真实错误信息和对应解法。报错一401 UnauthorizedError: 401 Unauthorized - invalid api key这个最直接API Key 错了或者没传。检查三处配置文件里的apiKey字段是否填了完整 Key、Key 是否已过期或被删除、请求头里Authorization: Bearer格式是否正确。如果你用的是环境变量注入确认变量名和配置文件里引用的一致。还有一种情况是 Key 复制时带了空格肉眼看不出来建议重新复制一次。报错二local proxy failedError: local proxy failed - connect ECONNREFUSED 127.0.0.1:3000这个通常出现在 gateway 没启动或者端口被占用。先确认窗口 A 的openclaw gateway还在运行如果挂了就重启。然后检查 3000 端口是否被别的程序占用lsof -i :3000有占用就换端口启动时加--port 3001。Docker 方式的话检查容器是否在运行docker ps以及端口映射是否正确。报错三reading choices of undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错说明请求发出去了但返回结构不对代码去读choices时拿到 undefined。原因通常是 Base URL 写错了比如写成了https://taotoken.net而漏了/api或者多写了/v1导致路径重复。正确写法是https://taotoken.net/apiOpenClaw 会自动拼接/v1/chat/completions。另一个可能是 Model ID 写错模型不存在时部分网关会返回错误结构也会触发这个报错。报错四OAuth 相关错误Error: OAuth token expired or invalid如果你在配置里误选了 OAuth 认证方式而不是 API Key会撞上这个。OpenClaw 的模型接入用 API Key 就行不需要 OAuth。回到 onboard 向导重新选或者在配置文件里把认证方式改成apiKey。报错五sharp 安装失败macOS 专属前面提过解法是SHARP_IGNORE_GLOBAL_LIBVIPS1或先brew install vips。如果还不行检查 Xcode Command Line Tools 是否装了xcode-select --install。排查顺序建议先 curl 验证 TaoToken 通道再验证 OpenClaw 配置最后看 gateway 和 dashboard 进程。这样能快速定位问题在哪一层。大部分报错集中在 Key 配置和 Base URL 上把这两处核对清楚八成问题就解决了。6. 从安装到跑通把 OpenClaw 接进你的日常工作流到这里一个可用的 OpenClaw 就装好了。完整链路是装 Node.js → 选 npm 或 Docker 方式装 OpenClaw → 执行 onboard 配置 → 填入 TaoToken 的 Base URL、API Key、Model ID 三件套 → 启动 gateway 和 dashboard → 在 Web 控制台验证 GLM-4.6 请求。如果你打算长期用建议把配置固化成脚本。比如写一个启动脚本把 gateway 和 dashboard 一起拉起来省得每次开两个终端。Docker 方式的话用docker compose管理更优雅把端口、挂载、环境变量都写进 compose 文件一条命令启动。模型接入这块TaoToken 的统一 Key 通道好处是你不用为每个模型单独配一套认证。今天用 glm-4.6明天想换别的模型改一下 Model ID 就行Base URL 和 Key 都不用动。对于需要频繁切换模型的场景这个省事程度很明显。最后给个实用建议把 API Key 用环境变量管理别硬编码在配置文件里。OpenClaw 支持从环境变量读取配置里写${TAOTOKEN_API_KEY}这种占位符实际值放在 shell 的 profile 里。这样配置文件可以安全地同步到多台机器不怕泄露。跑通之后你可以试试在 VS Code 里接入本地 gateway把 AI 辅助嵌进编码流程。也可以配几个常用的自动化工作流比如批量处理文档、定时生成报告。OpenClaw 的扩展性不错值得花点时间摸索。遇到问题先按第五章的排查顺序走一遍大多数坑都是配置层面的耐心核对就能解决。