1. 为什么要在本地跑 OpenClaw以及它到底能做什么OpenClaw 是一个开源的个人 AI 助手项目你可以把它理解成「装在自己电脑上的工程型智能体」——它不只是聊天还能读写文件、执行命令、访问网页、跑定时任务。适合谁适合那些不满足于网页对话框、想让 AI 直接操作本地环境干活的开发者。它的网关服务默认监听 18789 端口通过 Web UI 或聊天通道跟你交互模型侧则通过配置文件里的 API 端点来对接。问题在于OpenClaw 默认的模型供应商配置对国内开发者不太顺手要么需要海外账号要么端点地址填起来别扭。我这次的做法是把它接到 TaoToken 的 API 端点上用一套兼容的鉴权方式跑通。整条链路是Node.js 环境 → 安装 OpenClaw → 装 ClawHub 技能管理 → 配置网关服务 → 把模型端点改到 TaoToken → 发一条测试请求验证连通性。这篇教程按「能跟着做」的标准写每一步都给完整命令和配置片段。你需要准备的东西不多一台 2GB 内存以上的机器macOS / Windows / Linux 都行、Node.js 22 以上、一个 TaoToken 的 API Key。下面从环境检查开始一路走到验证请求成功。先说清楚 OpenClaw 和普通聊天工具的区别免得你装完发现预期不对。普通聊天工具是「你问它答」OpenClaw 是「你给它任务它自己拆步骤执行」。比如你说「把 workspace 里所有 .log 文件按日期归档」它会真的去列目录、建文件夹、移动文件。这种能力来自它的技能系统和网关服务而技能通过 ClawHub 分发。所以安装流程里ClawHub 不是可选项是让 OpenClaw 真正好用的关键一环。另外提醒一点OpenClaw 的配置文件集中在~/.openclaw/目录下主配置是openclaw.json模型密钥存在agents/agent/agent/auth-profiles.json。后面改端点就是改这两个地方记住路径能省很多排查时间。2. Node.js 环境准备与 OpenClaw 安装含 ClawHub 技能管理2.1 检查并安装 Node.js 22OpenClaw 要求 Node.js ≥ 22低于这个版本会在启动时报引擎不兼容。先查版本node -v npm -v如果版本低于 22用 nvm 升级最省事# 安装 nvmmacOS / Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并使用 Node.js 22 nvm install 22 nvm use 22 node -v # 应输出 v22.x.xWindows 用户直接去 Node.js 官网下 22 的 LTS 安装包装完重开终端验证即可。这一步别跳过我见过太多「装完启动就崩」的案例根因都是 Node 版本太低。2.2 安装 OpenClaw一键脚本适合快速体验# macOS / Linux curl -fsSL https://openclaw.ai/install.sh | bash但更推荐 npm 全局安装版本可控、卸载干净npm i -g openclaw --registryhttps://registry.npmmirror.com openclaw --version如果你要改源码或跟进最新特性用源码模式git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build pnpm build pnpm openclaw onboard --install-daemon2.3 安装 ClawHub 技能管理工具ClawHub 是 OpenClaw 的技能市场技能就是给助手加功能的模块。装好管理工具后搜索、安装、更新技能都靠它npm install -g clawhub clawhub login clawhub search file clawhub install 技能名 clawhub update --all装完技能后用openclaw skills list确认本地已加载。这里有个坑技能装完不会自动生效需要重启网关服务后面会讲。2.4 初始化配置执行交互式向导openclaw onboard --install-daemon向导里几个关键选择启动模式选 QuickStart模型配置这一步先随便选一个供应商占位因为后面我们要手动改成 TaoToken端口保持默认 18789技能选择可以直接跳过后续用 ClawHub 补装最后选 Open the Web UI 打开界面。配置完成后访问http://127.0.0.1:18789/chat能看到聊天界面说明基础环境通了。接下来才是重点——把模型端点接到 TaoToken。3. 网关服务配置把 API 端点改到 TaoToken3.1 先拿到 TaoToken 的 API Key去 TaoToken 控制台创建一个 API Key路径是 API Keys 页面。创建后复制那串以sk-开头的密钥只显示一次存好。同时确认你要用的模型 ID比如claude-sonnet-4-5这类具体以控制台模型列表为准。控制台 / API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite3.2 修改主配置文件OpenClaw 的主配置在~/.openclaw/openclaw.json。先备份再改cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak openclaw config file # 确认路径用编辑器打开找到模型供应商相关段落改成下面这样。注意 Base URL 用https://taotoken.net/api不要带任何多余路径{ models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5 } ] } }, default: taotoken/claude-sonnet-4-5 } }如果你更习惯用 TOML 风格的配置片段部分版本支持等价写法是[models.providers.taotoken] type openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoToken密钥 [[models.providers.taotoken.models]] id claude-sonnet-4-5 name Claude Sonnet 4.5 [models] default taotoken/claude-sonnet-4-53.3 写入鉴权文件除了主配置模型密钥还会落在~/.openclaw/agents/agent/agent/auth-profiles.json。确保这里也有对应条目{ profiles: { taotoken: { provider: taotoken, apiKey: sk-你的TaoToken密钥, baseUrl: https://taotoken.net/api } } }三件套对齐检查Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 是控制台里确认过的模型名。三者任何一个写错后面请求都会失败。3.4 校验并重启网关改完配置必须校验再重启否则改动不生效openclaw config validate openclaw gateway restart openclaw gateway statusgateway status显示 running 就说明网关起来了。如果显示 stopped用openclaw gateway run --port 18789 --verbose前台跑一次看具体报错。4. 验证请求发一条测试消息确认连通性4.1 用命令行发测试请求网关起来后最直接的验证方式是发一条消息openclaw chat send 你好请回复连通成功如果配置正确你会看到模型返回的内容里包含「连通成功」。这一步成功说明 Base URL、Key、Model ID 三件套都对上了。4.2 用 curl 直接验证端点想更底层地确认 TaoToken 端点可达可以绕过 OpenClaw 直接打 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回 JSON 里带choices数组就说明端点通。这一步能帮你区分「是 OpenClaw 配置问题」还是「是端点/密钥问题」。4.3 在 Web UI 里验证打开http://127.0.0.1:18789/chat在输入框发一条消息。如果界面一直转圈或报错按 F12 看 Network 面板里请求的 URL 和状态码。常见的是 401Key 错或 404Base URL 多写了路径。4.4 验证技能是否生效发一条需要调用技能的消息比如「列出当前 workspace 的文件」。如果助手能返回文件列表说明 ClawHub 技能和网关服务都正常联动。到这一步整条链路就算跑通了。5. 常见启动报错排查清单5.1 401 Unauthorized报错长这样Error: 401 Unauthorized - invalid api key原因基本是 Key 写错、Key 过期或者auth-profiles.json和openclaw.json里的 Key 不一致。排查顺序先确认sk-开头那串没复制漏字符再检查两个文件里的 Key 是否相同最后去 TaoToken 控制台确认 Key 还有效。改完记得openclaw gateway restart。5.2 local proxy failed / connection refusedError: local proxy failed: connect ECONNREFUSED 127.0.0.1:18789这是网关服务没起来。先openclaw gateway status看状态stopped 就openclaw gateway start。如果启动就崩用openclaw gateway run --port 18789 --verbose前台跑看具体堆栈。常见根因是端口被占用换个端口或杀掉占用进程。5.3 reading choices of undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错说明请求发出去了但返回结构不对——通常是 Base URL 写成了https://taotoken.net/api/v1这种多带路径的形式导致实际请求打到了错误端点。把 Base URL 改回https://taotoken.net/api重启网关。5.4 OAuth / token 相关报错Error: OAuth token expired, please re-authenticate如果你之前配过别的供应商残留的 OAuth 配置会干扰。执行openclaw models auth setup-token重新配置鉴权或者直接清掉auth-profiles.json里旧供应商的条目只留 TaoToken。5.5 配置改了不生效这是最高频的「假故障」。OpenClaw 的配置是启动时加载的改完openclaw.json不重启网关改动不会生效。养成习惯改配置 →openclaw config validate→openclaw gateway restart。三步走完再验证。5.6 技能装了但助手不用openclaw skills list能看到技能但助手不调用。检查两点技能是否 enable网关是否重启过。技能安装后需要openclaw gateway restart才会被加载。另外部分技能有依赖装的时候看下 ClawHub 的说明。6. 把 OpenClaw 接到 TaoToken 后的日常使用建议跑通之后日常使用有几个点值得注意。模型切换用/model 模型名斜杠命令不用改配置文件会话上下文乱了用/new重置任务跑太久用/stop中止。这些命令在 Web UI 输入框直接敲就行。长期编码或跑 Agent 任务的话建议用 Coding Plan 这类套餐比按次调用划算适合高频使用场景。如果你只是想先验证模型效果可以直接在模型对话页面试几条确认输出质量再决定要不要本地部署。模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后说个实际经验OpenClaw 的日志在/tmp/openclaw/*.log出问题先openclaw logs --follow看实时日志比猜快得多。配置改动前备份openclaw.json改崩了直接还原。这套流程跑顺之后你就有了一台完全跑在自己环境里的 AI 助手模型端点指向 TaoToken数据和控制权都在自己手里。
1. 为什么要在本地跑 OpenClaw以及它到底能做什么OpenClaw 是一个开源的个人 AI 助手项目你可以把它理解成「装在自己电脑上的工程型智能体」——它不只是聊天还能读写文件、执行命令、访问网页、跑定时任务。适合谁适合那些不满足于网页对话框、想让 AI 直接操作本地环境干活的开发者。它的网关服务默认监听 18789 端口通过 Web UI 或聊天通道跟你交互模型侧则通过配置文件里的 API 端点来对接。问题在于OpenClaw 默认的模型供应商配置对国内开发者不太顺手要么需要海外账号要么端点地址填起来别扭。我这次的做法是把它接到 TaoToken 的 API 端点上用一套兼容的鉴权方式跑通。整条链路是Node.js 环境 → 安装 OpenClaw → 装 ClawHub 技能管理 → 配置网关服务 → 把模型端点改到 TaoToken → 发一条测试请求验证连通性。这篇教程按「能跟着做」的标准写每一步都给完整命令和配置片段。你需要准备的东西不多一台 2GB 内存以上的机器macOS / Windows / Linux 都行、Node.js 22 以上、一个 TaoToken 的 API Key。下面从环境检查开始一路走到验证请求成功。先说清楚 OpenClaw 和普通聊天工具的区别免得你装完发现预期不对。普通聊天工具是「你问它答」OpenClaw 是「你给它任务它自己拆步骤执行」。比如你说「把 workspace 里所有 .log 文件按日期归档」它会真的去列目录、建文件夹、移动文件。这种能力来自它的技能系统和网关服务而技能通过 ClawHub 分发。所以安装流程里ClawHub 不是可选项是让 OpenClaw 真正好用的关键一环。另外提醒一点OpenClaw 的配置文件集中在~/.openclaw/目录下主配置是openclaw.json模型密钥存在agents/agent/agent/auth-profiles.json。后面改端点就是改这两个地方记住路径能省很多排查时间。2. Node.js 环境准备与 OpenClaw 安装含 ClawHub 技能管理2.1 检查并安装 Node.js 22OpenClaw 要求 Node.js ≥ 22低于这个版本会在启动时报引擎不兼容。先查版本node -v npm -v如果版本低于 22用 nvm 升级最省事# 安装 nvmmacOS / Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并使用 Node.js 22 nvm install 22 nvm use 22 node -v # 应输出 v22.x.xWindows 用户直接去 Node.js 官网下 22 的 LTS 安装包装完重开终端验证即可。这一步别跳过我见过太多「装完启动就崩」的案例根因都是 Node 版本太低。2.2 安装 OpenClaw一键脚本适合快速体验# macOS / Linux curl -fsSL https://openclaw.ai/install.sh | bash但更推荐 npm 全局安装版本可控、卸载干净npm i -g openclaw --registryhttps://registry.npmmirror.com openclaw --version如果你要改源码或跟进最新特性用源码模式git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build pnpm build pnpm openclaw onboard --install-daemon2.3 安装 ClawHub 技能管理工具ClawHub 是 OpenClaw 的技能市场技能就是给助手加功能的模块。装好管理工具后搜索、安装、更新技能都靠它npm install -g clawhub clawhub login clawhub search file clawhub install 技能名 clawhub update --all装完技能后用openclaw skills list确认本地已加载。这里有个坑技能装完不会自动生效需要重启网关服务后面会讲。2.4 初始化配置执行交互式向导openclaw onboard --install-daemon向导里几个关键选择启动模式选 QuickStart模型配置这一步先随便选一个供应商占位因为后面我们要手动改成 TaoToken端口保持默认 18789技能选择可以直接跳过后续用 ClawHub 补装最后选 Open the Web UI 打开界面。配置完成后访问http://127.0.0.1:18789/chat能看到聊天界面说明基础环境通了。接下来才是重点——把模型端点接到 TaoToken。3. 网关服务配置把 API 端点改到 TaoToken3.1 先拿到 TaoToken 的 API Key去 TaoToken 控制台创建一个 API Key路径是 API Keys 页面。创建后复制那串以sk-开头的密钥只显示一次存好。同时确认你要用的模型 ID比如claude-sonnet-4-5这类具体以控制台模型列表为准。控制台 / API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite3.2 修改主配置文件OpenClaw 的主配置在~/.openclaw/openclaw.json。先备份再改cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak openclaw config file # 确认路径用编辑器打开找到模型供应商相关段落改成下面这样。注意 Base URL 用https://taotoken.net/api不要带任何多余路径{ models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5 } ] } }, default: taotoken/claude-sonnet-4-5 } }如果你更习惯用 TOML 风格的配置片段部分版本支持等价写法是[models.providers.taotoken] type openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoToken密钥 [[models.providers.taotoken.models]] id claude-sonnet-4-5 name Claude Sonnet 4.5 [models] default taotoken/claude-sonnet-4-53.3 写入鉴权文件除了主配置模型密钥还会落在~/.openclaw/agents/agent/agent/auth-profiles.json。确保这里也有对应条目{ profiles: { taotoken: { provider: taotoken, apiKey: sk-你的TaoToken密钥, baseUrl: https://taotoken.net/api } } }三件套对齐检查Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 是控制台里确认过的模型名。三者任何一个写错后面请求都会失败。3.4 校验并重启网关改完配置必须校验再重启否则改动不生效openclaw config validate openclaw gateway restart openclaw gateway statusgateway status显示 running 就说明网关起来了。如果显示 stopped用openclaw gateway run --port 18789 --verbose前台跑一次看具体报错。4. 验证请求发一条测试消息确认连通性4.1 用命令行发测试请求网关起来后最直接的验证方式是发一条消息openclaw chat send 你好请回复连通成功如果配置正确你会看到模型返回的内容里包含「连通成功」。这一步成功说明 Base URL、Key、Model ID 三件套都对上了。4.2 用 curl 直接验证端点想更底层地确认 TaoToken 端点可达可以绕过 OpenClaw 直接打 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回 JSON 里带choices数组就说明端点通。这一步能帮你区分「是 OpenClaw 配置问题」还是「是端点/密钥问题」。4.3 在 Web UI 里验证打开http://127.0.0.1:18789/chat在输入框发一条消息。如果界面一直转圈或报错按 F12 看 Network 面板里请求的 URL 和状态码。常见的是 401Key 错或 404Base URL 多写了路径。4.4 验证技能是否生效发一条需要调用技能的消息比如「列出当前 workspace 的文件」。如果助手能返回文件列表说明 ClawHub 技能和网关服务都正常联动。到这一步整条链路就算跑通了。5. 常见启动报错排查清单5.1 401 Unauthorized报错长这样Error: 401 Unauthorized - invalid api key原因基本是 Key 写错、Key 过期或者auth-profiles.json和openclaw.json里的 Key 不一致。排查顺序先确认sk-开头那串没复制漏字符再检查两个文件里的 Key 是否相同最后去 TaoToken 控制台确认 Key 还有效。改完记得openclaw gateway restart。5.2 local proxy failed / connection refusedError: local proxy failed: connect ECONNREFUSED 127.0.0.1:18789这是网关服务没起来。先openclaw gateway status看状态stopped 就openclaw gateway start。如果启动就崩用openclaw gateway run --port 18789 --verbose前台跑看具体堆栈。常见根因是端口被占用换个端口或杀掉占用进程。5.3 reading choices of undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错说明请求发出去了但返回结构不对——通常是 Base URL 写成了https://taotoken.net/api/v1这种多带路径的形式导致实际请求打到了错误端点。把 Base URL 改回https://taotoken.net/api重启网关。5.4 OAuth / token 相关报错Error: OAuth token expired, please re-authenticate如果你之前配过别的供应商残留的 OAuth 配置会干扰。执行openclaw models auth setup-token重新配置鉴权或者直接清掉auth-profiles.json里旧供应商的条目只留 TaoToken。5.5 配置改了不生效这是最高频的「假故障」。OpenClaw 的配置是启动时加载的改完openclaw.json不重启网关改动不会生效。养成习惯改配置 →openclaw config validate→openclaw gateway restart。三步走完再验证。5.6 技能装了但助手不用openclaw skills list能看到技能但助手不调用。检查两点技能是否 enable网关是否重启过。技能安装后需要openclaw gateway restart才会被加载。另外部分技能有依赖装的时候看下 ClawHub 的说明。6. 把 OpenClaw 接到 TaoToken 后的日常使用建议跑通之后日常使用有几个点值得注意。模型切换用/model 模型名斜杠命令不用改配置文件会话上下文乱了用/new重置任务跑太久用/stop中止。这些命令在 Web UI 输入框直接敲就行。长期编码或跑 Agent 任务的话建议用 Coding Plan 这类套餐比按次调用划算适合高频使用场景。如果你只是想先验证模型效果可以直接在模型对话页面试几条确认输出质量再决定要不要本地部署。模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后说个实际经验OpenClaw 的日志在/tmp/openclaw/*.log出问题先openclaw logs --follow看实时日志比猜快得多。配置改动前备份openclaw.json改崩了直接还原。这套流程跑顺之后你就有了一台完全跑在自己环境里的 AI 助手模型端点指向 TaoToken数据和控制权都在自己手里。
