1. Windows10 下 OpenClaw-CN 安装踩坑与智谱免费大模型接入全流程OpenClaw-CN 是 OpenClaw 的中国社区维护版简单说就是一个能跑在你自己电脑上的 Agent 网关它把大模型的对话能力、工具调用、聊天通道Telegram、飞书、Discord 等串在一起让你用一个本地服务统一管理。适合谁适合想在 Windows10 上折腾本地 Agent、又不想被网络环境卡住的开发者。我这次的目标很明确在 Windows10 里把 OpenClaw-CN 装起来然后接上智谱的免费大模型让它在本地跑通一次完整对话。整个过程里最容易翻车的不是模型配置而是环境准备和构建脚本的执行环境差异。Node.js 版本、pnpm 镜像、PowerShell 与 Git Bash 的 PATH 继承问题任何一个没处理好都会让你卡在pnpm build那一步。下面我按实际执行顺序拆开讲命令都可以直接复制。先说结论性的路径Node.js ≥ 22pnpm 全局安装并换国内镜像Git 装好并确认 Git Bash 可用克隆仓库后依次pnpm install、pnpm ui:build、pnpm build构建阶段如果 PowerShell 报command not found就切到 Git Bash。初始化向导里选智谱 Z.AI认证方式按你拿到的 Key 类型选最后用pnpm openclaw gateway起网关、pnpm openclaw dashboard开管理页。关于调用凭证的统一管理我后面会讲怎么用 TaoToken 把 Key 和 API 通道收口避免每个模型供应商都散落一份配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 端点是 https://taotoken.net/api 这两个地址先记着配置章节会用到。2. 环境准备Node.js、pnpm 镜像与 Git Bash 的 PATH 陷阱这一章是纯准备工作但恰恰是后面报错的根源。Windows10 上跑 OpenClaw-CN环境没铺好后面每一步都会以奇怪的方式失败。2.1 Node.js 版本必须 ≥ 22去 Node.js 官网下载 LTS 或 Current 都行安装时勾选 “Add to PATH”。装完在 PowerShell 里验证node -v npm -v如果node -v输出的是 v18 或 v20建议升级到 22 以上。OpenClaw-CN 的依赖里有些包用到了较新的语法和 API低版本会在pnpm install阶段就报错。升级最省事的办法是去官网下新的 msi 覆盖安装或者用 nvm-windows 管理多版本。2.2 pnpm 全局安装与国内镜像pnpm 是 OpenClaw-CN 指定的包管理器别用 npm 或 yarn 替代lock 文件格式不一样。安装命令npm install -g pnpm装完验证pnpm -v接下来这一步非常关键不换镜像的话pnpm install会慢到让你怀疑人生pnpm config set registry https://registry.npmmirror.com/设置完可以用pnpm config get registry确认输出是https://registry.npmmirror.com/。这个镜像同步频率很高日常开发够用。2.3 Git 与 Git Bash 的验证Git 官网下载安装安装选项里保持默认即可重点是确保 “Git Bash” 被勾选安装。装完打开 Git Bash执行bash -c node -v这条命令的含义是启动一个 Bash 子进程在子进程里执行node -v。如果它能正常输出 Node 版本号说明 Git Bash 能继承到 Node 的 PATH后面构建脚本就不会因为找不到 node 而失败。如果这里报node: command not found那说明 Git Bash 的环境变量没配好需要手动把 Node 安装目录加到系统 PATH或者重装 Node 时勾选 “Add to PATH”。注意PowerShell 里node -v能跑不代表 Git Bash 里也能跑。这两个是独立的环境PATH 继承规则不同。构建脚本bundle-a2ui.sh是通过 Bash 子进程执行的所以必须单独验证 Git Bash。2.4 关于 pnpm 的构建脚本安全机制pnpm install过程中你会看到一些警告提示某些包的 build scripts 被忽略。这是 pnpm 的默认安全策略防止 npm 包在安装时自动执行任意脚本。像discordjs/opus这种需要原生编译的包会被跳过。目前不影响 OpenClaw-CN 的核心功能可以先不管。如果后续真的用到 Discord 语音再单独用pnpm approve-builds放行。3. 克隆、构建与配置文件定位可复制的 settings 片段环境铺好后进入安装阶段。先切到你想放项目的盘比如 D 盘d: git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git cd openclaw-cn克隆完成后安装依赖pnpm install这一步会拉取大量依赖包括 typescript、vitest、oxlint 等开发工具以及 lit、signal-utils 等前端库。看到前面带号的行就是新增成功的包。等它跑完。接着构建 UI 依赖pnpm ui:build然后是构建项目pnpm build如果你在 PowerShell 里执行pnpm build报错错误信息里出现bash scripts/bundle-a2ui.sh以及command not found不要慌。原因是这个构建脚本启动了一个 Bash 子进程而该子进程没有继承 PowerShell 的 PATH找不到 node。解决办法就是切到 Git Bash 执行同样的命令pnpm build在 Git Bash 里通常能顺利跑完。这就是为什么前面要单独验证bash -c node -v。构建成功后OpenClaw-CN 的配置文件通常位于项目根目录或用户目录下的配置文件夹。初始化向导会引导你生成配置。如果你要手动管理配置核心是找到模型供应商和 API Key 的填写位置。下面是一个模型供应商配置的片段示例路径和字段名以你实际生成的配置为准{ providers: { zai: { baseUrl: https://open.bigmodel.cn/api/paas/v4, apiKey: 你的智谱APIKey, model: glm-4-flash } }, defaultModel: zai/glm-4-flash }如果你希望通过 TaoToken 统一管理调用凭证把 baseUrl 换成 TaoToken 的 API 端点Key 换成 TaoToken 生成的 Key{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoTokenKey, model: glm-4-flash } }, defaultModel: taotoken/glm-4-flash }这样做的价值在于你后续如果还要接别的模型不用在每个工具里重复填不同厂商的 Key统一走一个通道换模型只改 model 字段。TaoToken 的 API Keys 管理页面在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 配置前可以先看一眼字段说明。提示配置文件里的 baseUrl 不要带尾部斜杠否则某些 HTTP 客户端会拼出双斜杠导致 404。model 字段要和你实际开通的模型 ID 一致智谱免费额度通常对应 glm-4-flash 这类轻量模型。4. 初始化向导与连通性验证从 onboard 到 dashboard配置片段准备好后启动初始化向导pnpm openclaw onboard --install-daemon向导会先给一段幽默风格的开场白然后弹出安全警告。这段警告要认真读OpenClaw 处于测试阶段启用工具功能后它能读文件、执行命令恶意提示词可能诱导它做危险操作。推荐的安全基线包括配对/白名单加提及触发、沙箱加最小权限、密钥不要放在它能访问的目录、有工具权限的机器人用最强模型。建议定期跑openclaw security audit --deep openclaw security audit --fix向导会问你 “要继续吗”光标默认停在 No用方向键选 Yes 回车。接下来是快速启动、选择模型供应商。这里选智谱 AI 大模型 Z.AI。智谱开放平台的通用 API 端点是https://open.bigmodel.cn/api/paas/v4。然后选择认证方式可选 Coding-Plan-Global、Coding-Plan-CN、Global、CN 等按你实际拿到的 Key 类型选。再选默认模型建议先用免费额度对应的轻量模型跑通。聊天通道这一步可以跳过或选一个你熟悉的平台。如果选 Telegram去 BotFather 注册机器人拿 token 即可。DM 安全机制默认要求配对码批准命令是openclaw pairing approve telegram 123456技能和钩子按需选择新手可以先跳过。安装 daemon 时如果报权限错误不影响立即使用只是无法自动后台运行。每次手动启动即可pnpm openclaw gateway保持终端窗口开着。然后另开一个终端打开管理页面pnpm openclaw dashboard连通性验证在管理页面的对话窗口发一条消息比如 “你好请用一句话介绍你自己”。如果模型正常返回说明接入成功。如果返回 401检查 API Key 是否正确、是否过期如果返回 404检查 baseUrl 是否多了尾部斜杠或路径拼错如果报reading choices之类的解析错误通常是返回体格式和客户端预期不一致检查 model 字段是否填了不存在的模型 ID。5. 本篇常见报错排查401、local proxy failed 与 OAuth 问题这一章把我在安装和接入过程中遇到以及社区里高频出现的报错集中列一下方便你对照。报错一command not found出现在pnpm build阶段。这是 PowerShell 与 Git Bash 环境隔离导致的。解决方式是切到 Git Bash 执行pnpm build。根因是bundle-a2ui.sh通过 Bash 子进程运行子进程没有继承 PowerShell 的 PATH。验证方法就是前面说的bash -c node -v。报错二401 Unauthorized。说明 Key 无效或没带上。检查三件套Base URL、Key、Model ID 是否匹配。如果你用的是 TaoToken 通道确认 baseUrl 是https://taotoken.net/apiKey 是在 https://taotoken.net/api-keys 生成的Model ID 填的是通道支持的模型名。三者任何一个不对都会 401。报错三local proxy failed或连接超时。这类错误通常是本地网络到 API 端点的连通性问题。先确认你的网络能正常访问目标 API 域名可以用curl或 PowerShell 的Invoke-WebRequest测试。如果公司网络有出口限制需要联系网络管理员放行。不要使用任何非正规的网络加速手段合规访问即可。报错四OAuth 相关错误。如果你在认证方式里选了 OAuth 类选项但本地没有配置好回调地址或浏览器授权流程会报 OAuth 错误。新手建议先用 API Key 方式简单直接。等跑通后再研究 OAuth。报错五reading choices解析失败。这通常出现在客户端期望 OpenAI 格式的返回体但实际返回结构不一致时。检查你的 baseUrl 是否指向了正确的 API 路径以及 model 字段是否是供应商支持的模型。有些供应商的免费模型和付费模型走不同端点填错就会返回非预期结构。报错六daemon 安装失败。提示权限不足。以管理员身份重开终端再执行pnpm openclaw onboard --install-daemon。如果还是失败跳过 daemon每次手动pnpm openclaw gateway启动功能不受影响。排查通用思路先看报错关键词定位是环境问题、认证问题还是网络问题。环境问题看 PATH 和版本认证问题看三件套网络问题看连通性。把这三类分开大部分报错都能快速定位。6. 用 TaoToken 统一管理调用凭证与后续接入建议跑通智谱免费模型后你可能会想接更多模型或者在不同工具之间共享同一套凭证。这时候散落各处的 Key 就会变成负担。我的做法是用 TaoToken 做统一通道所有工具都指向同一个 Base URLKey 也只维护一份。具体操作在 https://taotoken.net/api-keys 生成一个 Key然后在 OpenClaw-CN 的配置里把 provider 的 baseUrl 设为https://taotoken.net/apiapiKey 填这个 Keymodel 填你要用的模型 ID。这样你换模型时只改 model 字段不用动 Key。如果你同时用 Claude Code 或其他编码工具也可以让它们走同一个通道凭证管理集中在一处。对于长期编码和 Agent 场景可以了解 Coding Planhttps://taotoken.net/coding-plan 。如果只是想先验证模型对话效果模型对话入口在 https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc 配置字段有疑问时查这里最快。最后给几个实用建议。第一配置文件改完后重启网关再测试热加载不一定生效。第二管理页面的对话窗口是最快的验证入口不用每次都去聊天平台绕一圈。第三安全审计命令定期跑尤其是你启用了工具功能之后。第四Node.js 和 pnpm 的版本记下来换机器时照着装能省很多排查时间。第五如果构建阶段反复失败先确认 Git Bash 里node -v能跑通这一条能解决大半问题。
深入大模型-19-Windows10中安装OpenClaw-CN配置接入智谱免费大模型
1. Windows10 下 OpenClaw-CN 安装踩坑与智谱免费大模型接入全流程OpenClaw-CN 是 OpenClaw 的中国社区维护版简单说就是一个能跑在你自己电脑上的 Agent 网关它把大模型的对话能力、工具调用、聊天通道Telegram、飞书、Discord 等串在一起让你用一个本地服务统一管理。适合谁适合想在 Windows10 上折腾本地 Agent、又不想被网络环境卡住的开发者。我这次的目标很明确在 Windows10 里把 OpenClaw-CN 装起来然后接上智谱的免费大模型让它在本地跑通一次完整对话。整个过程里最容易翻车的不是模型配置而是环境准备和构建脚本的执行环境差异。Node.js 版本、pnpm 镜像、PowerShell 与 Git Bash 的 PATH 继承问题任何一个没处理好都会让你卡在pnpm build那一步。下面我按实际执行顺序拆开讲命令都可以直接复制。先说结论性的路径Node.js ≥ 22pnpm 全局安装并换国内镜像Git 装好并确认 Git Bash 可用克隆仓库后依次pnpm install、pnpm ui:build、pnpm build构建阶段如果 PowerShell 报command not found就切到 Git Bash。初始化向导里选智谱 Z.AI认证方式按你拿到的 Key 类型选最后用pnpm openclaw gateway起网关、pnpm openclaw dashboard开管理页。关于调用凭证的统一管理我后面会讲怎么用 TaoToken 把 Key 和 API 通道收口避免每个模型供应商都散落一份配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 端点是 https://taotoken.net/api 这两个地址先记着配置章节会用到。2. 环境准备Node.js、pnpm 镜像与 Git Bash 的 PATH 陷阱这一章是纯准备工作但恰恰是后面报错的根源。Windows10 上跑 OpenClaw-CN环境没铺好后面每一步都会以奇怪的方式失败。2.1 Node.js 版本必须 ≥ 22去 Node.js 官网下载 LTS 或 Current 都行安装时勾选 “Add to PATH”。装完在 PowerShell 里验证node -v npm -v如果node -v输出的是 v18 或 v20建议升级到 22 以上。OpenClaw-CN 的依赖里有些包用到了较新的语法和 API低版本会在pnpm install阶段就报错。升级最省事的办法是去官网下新的 msi 覆盖安装或者用 nvm-windows 管理多版本。2.2 pnpm 全局安装与国内镜像pnpm 是 OpenClaw-CN 指定的包管理器别用 npm 或 yarn 替代lock 文件格式不一样。安装命令npm install -g pnpm装完验证pnpm -v接下来这一步非常关键不换镜像的话pnpm install会慢到让你怀疑人生pnpm config set registry https://registry.npmmirror.com/设置完可以用pnpm config get registry确认输出是https://registry.npmmirror.com/。这个镜像同步频率很高日常开发够用。2.3 Git 与 Git Bash 的验证Git 官网下载安装安装选项里保持默认即可重点是确保 “Git Bash” 被勾选安装。装完打开 Git Bash执行bash -c node -v这条命令的含义是启动一个 Bash 子进程在子进程里执行node -v。如果它能正常输出 Node 版本号说明 Git Bash 能继承到 Node 的 PATH后面构建脚本就不会因为找不到 node 而失败。如果这里报node: command not found那说明 Git Bash 的环境变量没配好需要手动把 Node 安装目录加到系统 PATH或者重装 Node 时勾选 “Add to PATH”。注意PowerShell 里node -v能跑不代表 Git Bash 里也能跑。这两个是独立的环境PATH 继承规则不同。构建脚本bundle-a2ui.sh是通过 Bash 子进程执行的所以必须单独验证 Git Bash。2.4 关于 pnpm 的构建脚本安全机制pnpm install过程中你会看到一些警告提示某些包的 build scripts 被忽略。这是 pnpm 的默认安全策略防止 npm 包在安装时自动执行任意脚本。像discordjs/opus这种需要原生编译的包会被跳过。目前不影响 OpenClaw-CN 的核心功能可以先不管。如果后续真的用到 Discord 语音再单独用pnpm approve-builds放行。3. 克隆、构建与配置文件定位可复制的 settings 片段环境铺好后进入安装阶段。先切到你想放项目的盘比如 D 盘d: git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git cd openclaw-cn克隆完成后安装依赖pnpm install这一步会拉取大量依赖包括 typescript、vitest、oxlint 等开发工具以及 lit、signal-utils 等前端库。看到前面带号的行就是新增成功的包。等它跑完。接着构建 UI 依赖pnpm ui:build然后是构建项目pnpm build如果你在 PowerShell 里执行pnpm build报错错误信息里出现bash scripts/bundle-a2ui.sh以及command not found不要慌。原因是这个构建脚本启动了一个 Bash 子进程而该子进程没有继承 PowerShell 的 PATH找不到 node。解决办法就是切到 Git Bash 执行同样的命令pnpm build在 Git Bash 里通常能顺利跑完。这就是为什么前面要单独验证bash -c node -v。构建成功后OpenClaw-CN 的配置文件通常位于项目根目录或用户目录下的配置文件夹。初始化向导会引导你生成配置。如果你要手动管理配置核心是找到模型供应商和 API Key 的填写位置。下面是一个模型供应商配置的片段示例路径和字段名以你实际生成的配置为准{ providers: { zai: { baseUrl: https://open.bigmodel.cn/api/paas/v4, apiKey: 你的智谱APIKey, model: glm-4-flash } }, defaultModel: zai/glm-4-flash }如果你希望通过 TaoToken 统一管理调用凭证把 baseUrl 换成 TaoToken 的 API 端点Key 换成 TaoToken 生成的 Key{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoTokenKey, model: glm-4-flash } }, defaultModel: taotoken/glm-4-flash }这样做的价值在于你后续如果还要接别的模型不用在每个工具里重复填不同厂商的 Key统一走一个通道换模型只改 model 字段。TaoToken 的 API Keys 管理页面在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 配置前可以先看一眼字段说明。提示配置文件里的 baseUrl 不要带尾部斜杠否则某些 HTTP 客户端会拼出双斜杠导致 404。model 字段要和你实际开通的模型 ID 一致智谱免费额度通常对应 glm-4-flash 这类轻量模型。4. 初始化向导与连通性验证从 onboard 到 dashboard配置片段准备好后启动初始化向导pnpm openclaw onboard --install-daemon向导会先给一段幽默风格的开场白然后弹出安全警告。这段警告要认真读OpenClaw 处于测试阶段启用工具功能后它能读文件、执行命令恶意提示词可能诱导它做危险操作。推荐的安全基线包括配对/白名单加提及触发、沙箱加最小权限、密钥不要放在它能访问的目录、有工具权限的机器人用最强模型。建议定期跑openclaw security audit --deep openclaw security audit --fix向导会问你 “要继续吗”光标默认停在 No用方向键选 Yes 回车。接下来是快速启动、选择模型供应商。这里选智谱 AI 大模型 Z.AI。智谱开放平台的通用 API 端点是https://open.bigmodel.cn/api/paas/v4。然后选择认证方式可选 Coding-Plan-Global、Coding-Plan-CN、Global、CN 等按你实际拿到的 Key 类型选。再选默认模型建议先用免费额度对应的轻量模型跑通。聊天通道这一步可以跳过或选一个你熟悉的平台。如果选 Telegram去 BotFather 注册机器人拿 token 即可。DM 安全机制默认要求配对码批准命令是openclaw pairing approve telegram 123456技能和钩子按需选择新手可以先跳过。安装 daemon 时如果报权限错误不影响立即使用只是无法自动后台运行。每次手动启动即可pnpm openclaw gateway保持终端窗口开着。然后另开一个终端打开管理页面pnpm openclaw dashboard连通性验证在管理页面的对话窗口发一条消息比如 “你好请用一句话介绍你自己”。如果模型正常返回说明接入成功。如果返回 401检查 API Key 是否正确、是否过期如果返回 404检查 baseUrl 是否多了尾部斜杠或路径拼错如果报reading choices之类的解析错误通常是返回体格式和客户端预期不一致检查 model 字段是否填了不存在的模型 ID。5. 本篇常见报错排查401、local proxy failed 与 OAuth 问题这一章把我在安装和接入过程中遇到以及社区里高频出现的报错集中列一下方便你对照。报错一command not found出现在pnpm build阶段。这是 PowerShell 与 Git Bash 环境隔离导致的。解决方式是切到 Git Bash 执行pnpm build。根因是bundle-a2ui.sh通过 Bash 子进程运行子进程没有继承 PowerShell 的 PATH。验证方法就是前面说的bash -c node -v。报错二401 Unauthorized。说明 Key 无效或没带上。检查三件套Base URL、Key、Model ID 是否匹配。如果你用的是 TaoToken 通道确认 baseUrl 是https://taotoken.net/apiKey 是在 https://taotoken.net/api-keys 生成的Model ID 填的是通道支持的模型名。三者任何一个不对都会 401。报错三local proxy failed或连接超时。这类错误通常是本地网络到 API 端点的连通性问题。先确认你的网络能正常访问目标 API 域名可以用curl或 PowerShell 的Invoke-WebRequest测试。如果公司网络有出口限制需要联系网络管理员放行。不要使用任何非正规的网络加速手段合规访问即可。报错四OAuth 相关错误。如果你在认证方式里选了 OAuth 类选项但本地没有配置好回调地址或浏览器授权流程会报 OAuth 错误。新手建议先用 API Key 方式简单直接。等跑通后再研究 OAuth。报错五reading choices解析失败。这通常出现在客户端期望 OpenAI 格式的返回体但实际返回结构不一致时。检查你的 baseUrl 是否指向了正确的 API 路径以及 model 字段是否是供应商支持的模型。有些供应商的免费模型和付费模型走不同端点填错就会返回非预期结构。报错六daemon 安装失败。提示权限不足。以管理员身份重开终端再执行pnpm openclaw onboard --install-daemon。如果还是失败跳过 daemon每次手动pnpm openclaw gateway启动功能不受影响。排查通用思路先看报错关键词定位是环境问题、认证问题还是网络问题。环境问题看 PATH 和版本认证问题看三件套网络问题看连通性。把这三类分开大部分报错都能快速定位。6. 用 TaoToken 统一管理调用凭证与后续接入建议跑通智谱免费模型后你可能会想接更多模型或者在不同工具之间共享同一套凭证。这时候散落各处的 Key 就会变成负担。我的做法是用 TaoToken 做统一通道所有工具都指向同一个 Base URLKey 也只维护一份。具体操作在 https://taotoken.net/api-keys 生成一个 Key然后在 OpenClaw-CN 的配置里把 provider 的 baseUrl 设为https://taotoken.net/apiapiKey 填这个 Keymodel 填你要用的模型 ID。这样你换模型时只改 model 字段不用动 Key。如果你同时用 Claude Code 或其他编码工具也可以让它们走同一个通道凭证管理集中在一处。对于长期编码和 Agent 场景可以了解 Coding Planhttps://taotoken.net/coding-plan 。如果只是想先验证模型对话效果模型对话入口在 https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc 配置字段有疑问时查这里最快。最后给几个实用建议。第一配置文件改完后重启网关再测试热加载不一定生效。第二管理页面的对话窗口是最快的验证入口不用每次都去聊天平台绕一圈。第三安全审计命令定期跑尤其是你启用了工具功能之后。第四Node.js 和 pnpm 的版本记下来换机器时照着装能省很多排查时间。第五如果构建阶段反复失败先确认 Git Bash 里node -v能跑通这一条能解决大半问题。