1. 为什么要在本地跑一个 OpenClaw 执行助理
OpenClaw 是一个可以跑在自己电脑上的 AI 执行助理，它能读写文件、执行命令、调用工具，把「只会聊天」的模型变成「能动手干活」的助手。它适合两类人：一类是希望数据不出本机、对隐私比较在意的开发者；另一类是手里已经有模型 API Key，想把它接进一个能操作本地环境的 Agent 框架里做自动化的人。本地安装 OpenClaw 的核心价值在于，所有文件操作和命令执行都发生在你自己的机器上，模型只负责决策，执行权始终握在你手里。
不过从零部署 OpenClaw 有几个绕不开的坎。第一是 Node.js 版本，OpenClaw 要求 Node.js ≥ v22.14，很多人系统里还是 v18 甚至 v16，直接 npm 安装会报引擎不匹配。第二是模型接入，OpenClaw 初始化向导会让你填 LLM API Key，如果你手上有多个厂商的 Key，逐个配置很麻烦，而且不同厂商的 Base URL 格式还不一样。第三是网络问题，npm 拉包和模型请求都可能超时。
这篇教程的思路是：用 TaoToken 的统一 Key 和 API 通道来解决第二个问题，让 OpenClaw 只认一个 Base URL 和一个 Key，就能调用背后多个模型。这样你不需要在 OpenClaw 里为每个厂商单独写配置，也不用担心某个厂商的接口格式对不上。下面从环境准备开始，一步步走到启动验证和报错排查，每一步都给可复制的命令和配置片段。
我试过在一台 8GB 内存的笔记本上完整走一遍流程，从装 Node 到 OpenClaw 跑起来大概二十分钟，中间卡了一次 npm 镜像和一次端口占用，都在后面的排障章节里写了。你跟着做，遇到报错直接跳到第 5 节对照。
2. 环境准备与 TaoToken 统一 Key 的前置配置
2.1 Node.js 与 npm 环境
OpenClaw 的硬性要求是 Node.js ≥ v22.14.0，推荐 v24。先确认你当前的版本：
node --version npm --version如果 node 版本低于 v22.14，需要升级。Windows 用户去 Node.js 官网下载 LTS 安装包覆盖安装即可；macOS 用户如果用 Homebrew，执行brew install node@24；Linux 用户可以用 nvm 管理版本：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.bashrc nvm install 24 nvm use 24装完再跑一次node --version，确认输出 v24.x 或 v22.14 以上。npm 会随 Node 一起装上，不用单独装。
国内网络建议先切 npm 镜像，否则后面全局安装 OpenClaw 可能卡在下载阶段：
npm config set registry https://registry.npmmirror.com这条命令只影响 npm 的包下载源，不影响模型请求，可以放心执行。
2.2 获取 TaoToken 统一 Key
OpenClaw 初始化时会问你要 LLM API Key。与其填某个厂商的 Key，不如用 TaoToken 的统一 Key，这样 OpenClaw 只需要认一个 Base URL 和一个 Key，背后想换模型只改 Model ID 就行。
打开 TaoToken 控制台创建 API Key：
https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite在控制台里新建一个 Key，复制出来备用。这个 Key 就是后面 OpenClaw 配置里的apiKey。同时记下两个地址：
- Base URL：
https://taotoken.net/api - 模型对话入口（用来单独验证模型是否通）：
https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite
TaoToken 的 API 通道兼容 OpenAI 的接口格式，所以 OpenClaw 里凡是要求填 OpenAI 兼容 Base URL 的地方，都填https://taotoken.net/api。Model ID 填你在 TaoToken 控制台里看到的模型名，比如claude-sonnet-4-20250514或gpt-4o这类，具体以控制台展示为准。
注意：Base URL 末尾不要加
/v1，TaoToken 的通道已经处理了路径，加了反而会 404。这一点在第 5 节排障里会再强调。
2.3 安装 OpenClaw
环境就绪后，用 npm 全局安装：
npm install -g openclaw@latest如果你在 macOS 上遇到 sharp 模块编译失败，先设置环境变量再装：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest装完验证：
openclaw --version输出类似v2026.3.8的版本号就说明安装成功。如果提示command not found，检查 npm 全局 bin 目录是否在 PATH 里，执行npm config get prefix看路径，然后把它加到 PATH。
3. 可复制的 OpenClaw 配置文件与 Base URL 设置
3.1 初始化向导与跳过通讯平台
安装完成后运行初始化：
openclaw onboard向导会依次问几个问题。模式选择选quick start；到了填 LLM API Key 的步骤，先别急着填厂商 Key，我们后面直接改配置文件更可控。通讯平台（Slack、Discord 等）选skip for now，Skills 插件选no或skip，先把核心跑通再说。
向导结束后，OpenClaw 会在用户目录下生成配置。不同系统路径不同：
- Windows：
C:\Users\你的用户名\.openclaw\settings.json - macOS / Linux：
~/.openclaw/settings.json
3.2 settings.json 完整配置片段
用编辑器打开settings.json，把模型部分改成下面这样。这是一个可直接复制的 JSON 片段，路径和字段名与 OpenClaw 实际读取的一致：
{ "gateway": { "port": 18789 }, "llm": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoTokenKey", "model": "claude-sonnet-4-20250514", "maxTokens": 4096, "temperature": 0.7 }, "agent": { "workspace": "./workspace", "autoApprove": false } }几个关键字段说明：
| 字段 | 值 | 作用 |
|---|---|---|
| provider | openai-compatible | 告诉 OpenClaw 用 OpenAI 兼容协议发请求 |
| baseUrl | https://taotoken.net/api | TaoToken 统一通道地址 |
| apiKey | sk-开头 | 控制台创建的 Key |
| model | 模型 ID | 以 TaoToken 控制台展示为准 |
| autoApprove | false | 执行命令前需确认，安全起见先关 |
如果你更习惯用 TOML 格式（部分版本支持settings.toml），等价写法是：
[gateway] port = 18789 [llm] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" model = "claude-sonnet-4-20250514" max_tokens = 4096 temperature = 0.7 [agent] workspace = "./workspace" auto_approve = false两种格式选一种即可，OpenClaw 会优先读settings.json。改完保存，配置文件这一步就完成了。
3.3 关于 Model ID 的填写
Model ID 必须和 TaoToken 控制台里列出的名称完全一致，大小写敏感。如果你填了一个控制台里不存在的模型名，请求会返回模型不存在的错误。建议先在模型对话页面确认一下可用模型列表：
https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite在页面里选一个模型发一句话，能正常回复，就把那个模型名抄到settings.json的model字段里。这样能避免配置写对了但模型名写错的情况。
4. 启动服务与一次真实对话验证
4.1 启动 OpenClaw
配置改好后启动服务：
openclaw start如果之前向导已经自动启动过，先停再起：
openclaw stop openclaw start启动成功的标志是终端输出类似Gateway listening on http://localhost:18789的日志。如果没看到，用openclaw status查状态。
浏览器打开：
http://localhost:18789进入 OpenClaw 控制台，能看到对话输入框和工具面板。
4.2 用 curl 先验证 TaoToken 通道
在让 OpenClaw 发请求之前，先用 curl 单独验证 TaoToken 的 API 通道是通的，这样能把「通道问题」和「OpenClaw 配置问题」分开：
curl https://taotoken.net/api/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复两个字：通了"}] }'如果返回 JSON 里choices[0].message.content是「通了」，说明 Key、Base URL、模型名三者都对。这一步过了，OpenClaw 里再报错就基本是配置文件格式或字段名的问题。
4.3 在 OpenClaw 里发一次对话
回到http://localhost:18789，在输入框里发一句：
帮我在 workspace 目录下创建一个 hello.txt，内容写 OpenClaw 已就绪因为autoApprove设的是 false，OpenClaw 会先展示它打算执行的操作，等你点确认。确认后它会在 workspace 目录下生成文件。你去文件系统里看一眼，hello.txt存在且内容正确，就说明整条链路——OpenClaw 决策、TaoToken 通道转发、模型返回、本地执行——全部打通了。
这一步是整个教程的验收点。如果对话有回复但文件没生成，看第 5 节的工具权限排查；如果对话直接报错，看下面的报错对照。
5. 常见报错排查对照
5.1 401 Unauthorized
报错长这样：
Error: 401 Unauthorized - invalid api key原因通常是 Key 复制时带了空格，或者settings.json里apiKey字段名写错。检查两点：Key 是否以sk-开头且没有换行；字段名是否是apiKey而不是api_key（JSON 格式下用驼峰）。改完openclaw restart。
5.2 local proxy failed / connection refused
Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:xxxx这个报错说明 OpenClaw 尝试走本地代理但没连上。检查你的系统环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个没启动的本地端口。如果有，临时清掉再启动：
unset HTTP_PROXY HTTPS_PROXY openclaw restart5.3 reading choices 报错
TypeError: Cannot read properties of undefined (reading 'choices')这个报错几乎都是 Base URL 写错导致的。常见错误是写成了https://taotoken.net/api/v1，多加了/v1，请求打到了不存在的路径，返回体里没有choices字段。把baseUrl改回https://taotoken.net/api即可。另一个可能是 Model ID 填错，返回体是错误信息而不是标准补全结构，同样会触发这个报错。
5.4 OAuth 相关报错
Error: OAuth token expired or invalid如果你在初始化时选了某个需要 OAuth 的厂商登录方式，而不是填 API Key，就会走到这条路。解决办法是回到settings.json，把provider改成openai-compatible，用 TaoToken 的 Key 走 API 通道，绕开 OAuth 流程。
5.5 端口 18789 被占用
Error: listen EADDRINUSE: address already in use :::18789改端口：
openclaw config set gateway.port 18790 openclaw restart然后访问http://localhost:18790。改完记得在settings.json里确认gateway.port也同步了。
5.6 Node 版本不匹配
Error: The engine "node" is incompatible. Expected version ">=22.14.0"回到第 2.1 节升级 Node.js。升级后如果openclaw命令还在但报错，重新执行一次npm install -g openclaw@latest，让 npm 按新版本重新链接。
6. 接下来怎么用：从跑通到真正干活
服务跑起来只是起点。你现在有一个本地执行助理，它能通过 TaoToken 通道调用模型，也能操作你机器上的文件。接下来可以做的几件事：
第一，把autoApprove保持 false 用一段时间，观察 OpenClaw 每次打算执行什么操作，建立信任后再考虑放开。第二，在 TaoToken 控制台里换不同的 Model ID，比如从 Claude 换到 GPT 系列，只改settings.json里一个字段，openclaw restart就生效，不用动其他配置。第三，如果你要长期跑编码类任务或 Agent 工作流，可以了解一下 Coding Plan，它更适合高频调用场景：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite第四，OpenClaw 的 Skills 插件可以在你熟悉基础流程后逐步开启，文件管理、浏览器操作、代码执行这些能力都是通过 Skills 挂上去的。开启前建议先看清楚每个 Skill 的权限范围。
如果你在配置过程中想再确认一遍 Key 和模型列表，回到控制台和模型对话页面核对：
https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite接入文档里有更细的字段说明和示例，遇到本文没覆盖的报错可以去查：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=openclaw_local_setup&utm_campaign=rewrite最后提醒一个实操细节：settings.json改完后一定要openclaw restart，只start不会重新读配置。这个坑我在调试时踩过一次，改了 Base URL 但服务没重启，一直报 401，排查了十分钟才发现是配置没生效。
