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 node24Linux 用户可以用 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 统一 KeyOpenClaw 初始化时会问你要 LLM API Key。与其填某个厂商的 Key不如用 TaoToken 的统一 Key这样 OpenClaw 只需要认一个 Base URL 和一个 Key背后想换模型只改 Model ID 就行。打开 TaoToken 控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewrite在控制台里新建一个 Key复制出来备用。这个 Key 就是后面 OpenClaw 配置里的apiKey。同时记下两个地址Base URLhttps://taotoken.net/api模型对话入口用来单独验证模型是否通https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewriteTaoToken 的 API 通道兼容 OpenAI 的接口格式所以 OpenClaw 里凡是要求填 OpenAI 兼容 Base URL 的地方都填https://taotoken.net/api。Model ID 填你在 TaoToken 控制台里看到的模型名比如claude-sonnet-4-20250514或gpt-4o这类具体以控制台展示为准。注意Base URL 末尾不要加/v1TaoToken 的通道已经处理了路径加了反而会 404。这一点在第 5 节排障里会再强调。2.3 安装 OpenClaw环境就绪后用 npm 全局安装npm install -g openclawlatest如果你在 macOS 上遇到 sharp 模块编译失败先设置环境变量再装SHARP_IGNORE_GLOBAL_LIBVIPS1 npm install -g openclawlatest装完验证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 nowSkills 插件选no或skip先把核心跑通再说。向导结束后OpenClaw 会在用户目录下生成配置。不同系统路径不同WindowsC:\Users\你的用户名\.openclaw\settings.jsonmacOS / Linux~/.openclaw/settings.json3.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 } }几个关键字段说明字段值作用provideropenai-compatible告诉 OpenClaw 用 OpenAI 兼容协议发请求baseUrlhttps://taotoken.net/apiTaoToken 统一通道地址apiKeysk-开头控制台创建的 Keymodel模型 ID以 TaoToken 控制台展示为准autoApprovefalse执行命令前需确认安全起见先关如果你更习惯用 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_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewrite在页面里选一个模型发一句话能正常回复就把那个模型名抄到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设的是 falseOpenClaw 会先展示它打算执行的操作等你点确认。确认后它会在 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_keyJSON 格式下用驼峰。改完openclaw restart。5.2 local proxy failed / connection refusedError: 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 openclawlatest让 npm 按新版本重新链接。6. 接下来怎么用从跑通到真正干活服务跑起来只是起点。你现在有一个本地执行助理它能通过 TaoToken 通道调用模型也能操作你机器上的文件。接下来可以做的几件事第一把autoApprove保持 false 用一段时间观察 OpenClaw 每次打算执行什么操作建立信任后再考虑放开。第二在 TaoToken 控制台里换不同的 Model ID比如从 Claude 换到 GPT 系列只改settings.json里一个字段openclaw restart就生效不用动其他配置。第三如果你要长期跑编码类任务或 Agent 工作流可以了解一下 Coding Plan它更适合高频调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewrite第四OpenClaw 的 Skills 插件可以在你熟悉基础流程后逐步开启文件管理、浏览器操作、代码执行这些能力都是通过 Skills 挂上去的。开启前建议先看清楚每个 Skill 的权限范围。如果你在配置过程中想再确认一遍 Key 和模型列表回到控制台和模型对话页面核对https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewrite https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewrite接入文档里有更细的字段说明和示例遇到本文没覆盖的报错可以去查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_local_setuputm_campaignrewrite最后提醒一个实操细节settings.json改完后一定要openclaw restart只start不会重新读配置。这个坑我在调试时踩过一次改了 Base URL 但服务没重启一直报 401排查了十分钟才发现是配置没生效。