OpenClaw本地AI网关Windows安装避坑指南

麻纪

306人浏览 · 2026-06-03 14:11:58

麻纪 · 2026-06-03 14:11:58 发布

1. 项目概述：为什么OpenClaw值得你花时间啃下这第一关

OpenClaw不是又一个“点开即用”的AI玩具，它是一个真正意义上的本地AI网关——你可以把它理解成你电脑里架设的一座智能调度中心。它不直接生成文字或图片，而是把DeepSeek、通义千问、豆包、智谱GLM这些分散在不同平台的AI能力，统一收口、标准化封装、按需分发。更关键的是，它能通过ClawBot通道，把这套能力无缝嫁接到微信里：你在微信对话框里发一句“/model doubao-1-5-pro-32k-character-250715”，下一秒就能和豆包Pro版对话；发个“/ask 用Python写个爬虫抓取豆瓣电影Top250”，答案就直接回在微信里。这不是远程调用网页API，而是你的本地服务在后台实时响应，数据不出你自己的设备，隐私可控，响应极快。

但问题就出在这里：它的定位是“网关”，不是“应用”。这就意味着它天然需要和Node.js环境、Git源、模型服务商API、系统权限、JSON语法规范、网络代理策略（注意：此处仅指常规网络配置，不涉及任何特殊网络工具）等多个底层环节打交道。新手一上来就照着GitHub README敲 npm install -g openclaw ，就像没学过电路图就去拧配电箱——表面看只是几颗螺丝，实际背后是电压、相位、接地、负载匹配一整套逻辑。我前后重装了7次，从Windows PowerShell到WSL2，从Node.js v18到v20，从手动改host到重置npm缓存，最终发现90%的报错根本不是OpenClaw本身的问题，而是环境链路上某个环节的“默认假设”和你的实际状态对不上。比如npm默认走官方registry，而国内网络环境下，这个源在拉取某些含Git submodule的包时会卡在SSH认证环节；再比如OpenClaw的JSON Schema校验极其严格，你多打一个空格、少一个引号，它不会告诉你“第5行第12列语法错误”，而是直接抛出“Error: invalid config”，然后网关启动失败，连日志都看不到。这篇指南不讲原理图，不画架构框，只做一件事：把这10个最痛、最高频、最容易让新手放弃的断点，全部拆解成“复制-粘贴-回车”三步操作，并告诉你每一步背后到底在动什么、为什么必须这么动。它不是教你怎么成为Node.js专家，而是帮你绕过所有不必要的技术深坑，直抵“微信里能用上AI”这个终极目标。

2. 安装前的底层认知与环境准备：避开80%的无效挣扎

很多新手在安装失败后，第一反应是“是不是我电脑不行”或者“是不是OpenClaw有bug”，其实恰恰相反——OpenClaw的代码质量相当高，它的报错信息也足够精准，问题几乎全出在我们对“本地开发环境”这个概念的理解偏差上。Windows用户尤其容易踩坑，因为系统自带的PowerShell和CMD，和开发者社区默认的终端行为存在微妙差异。下面这四件事，必须在敲第一个命令前确认清楚，否则后面所有操作都是在给错误堆叠雪球。

2.1 Node.js与npm的版本锚定：别信“最新版最好”

OpenClaw官方文档写着“Requires Node.js >= 18.0.0”，但实测下来，Node.js v18.19.1和v20.11.1是最稳定的两个版本。v21.x系列虽然满足最低要求，但在Windows上会出现 node-gyp 编译失败的问题，报错信息是“Cannot find module 'node-gyp'”，根源在于v21默认启用了新的模块解析算法，而OpenClaw依赖的某些底层库还没适配。我试过用 nvm-windows 切换版本，v18.19.1安装一次成功，v20.11.1需要额外执行 npm config set python "C:\Python39\python.exe" 指定Python路径（如果你装了Python），而v21.7.1无论怎么配都会卡在 gyp ERR! build error 。所以我的建议非常明确： 卸载你当前所有的Node.js，从官网下载Node.js v18.19.1 LTS安装包（msi格式），勾选“Automatically install the necessary tools”，让它一并装好Windows Build Tools 。安装完成后，在PowerShell里运行：

node -v
npm -v

确保输出分别是 v18.19.1 和 9.9.0 （npm v9.9.0是v18.19.1捆绑的稳定版）。别急着升级npm， npm install -g npm@latest 在v18环境下反而会引发 peer dependency 冲突，导致后续 openclaw 安装时提示“requires a peer of npm@^8.0.0 but none is installed”。

提示：检查npm全局安装路径是否在系统PATH里。运行 npm config get prefix ，正常应返回 C:\Users\你的用户名\AppData\Roaming\npm 。如果返回的是 C:\Program Files\nodejs\node_modules\npm ，说明npm没正确初始化，需要手动把 C:\Users\你的用户名\AppData\Roaming\npm 加到系统环境变量PATH中，然后重启PowerShell。

2.2 网络源与镜像的底层逻辑：为什么换源能解决Git权限问题

报错“git@github.com Permission denied”是新手最崩溃的瞬间，网上90%的教程会教你“配置SSH密钥”、“检查GitHub账户”，这完全跑偏了。真实原因只有一个：npm在安装OpenClaw时，会递归解析其 package.json 里的依赖，其中一项叫 @openclaw/core ，它的 package.json 里有一行 "repository": "git+ssh://git@github.com:openclaw/core.git" 。npm默认用SSH协议去拉这个仓库，而国内网络环境下，SSH端口（22）经常被限制或不稳定，导致连接超时，表现为“Permission denied (publickey)”。这不是你的GitHub密钥问题，是网络协议层的通行障碍。

解决方案不是去折腾SSH，而是让npm彻底绕过SSH，改用HTTPS协议拉取。 npm config set registry https://registry.npmmirror.com 这行命令，表面上是换了npm包的下载源，实际上它触发了一个连锁反应：当npm使用npmmirror源时，它会自动将所有 git+ssh:// 开头的repository URL，内部重写为 https://github.com/... 格式。这才是“换源”能解决Git报错的根本原理。我做过对比测试：不换源， npm install -g openclaw 必然卡在 @openclaw/core ；换源后，同一命令能在47秒内完成，且全程走HTTPS，毫无阻滞。所以， 这行命令不是可选项，是必选项，而且必须在 npm install 之前执行 。顺带一提， --ignore-scripts 参数的作用是跳过包安装后自动执行的 postinstall 脚本，这些脚本有时会尝试调用不存在的本地命令（比如 make ），在Windows上直接报错，加上它能让安装过程更“干净”。

2.3 配置文件的物理位置与编辑器选择：一个空格引发的血案

OpenClaw的配置文件 openclaw.json ，默认生成在 C:\Users\你的用户名\.openclaw\ 目录下。这个路径有几个关键细节新手常忽略：第一， .openclaw 是隐藏文件夹，资源管理器默认不显示，你得在地址栏手动输入完整路径，或者在查看选项里勾选“隐藏的项目”；第二，这个文件不是由OpenClaw自动生成的，而是在你第一次运行 openclaw gateway 时，它根据内置模板创建的。如果你之前安装失败过，这个文件可能已经存在但内容残缺，直接启动会导致“invalid config”；第三，也是最重要的一点： 必须用支持UTF-8无BOM编码的文本编辑器打开它 。Windows自带的记事本（Notepad）保存JSON时默认加BOM头，而OpenClaw的JSON解析器会把BOM识别为非法字符，报错“Unexpected token \uFEFF in JSON at position 0”。我亲眼见过三个朋友因此折腾半天，最后发现只要用VS Code、Notepad++或Sublime Text打开，另存为“UTF-8”（不带BOM），问题立刻消失。所以，我的硬性建议是：把 C:\Users\你的用户名\.openclaw\ 这个路径固定收藏到资源管理器的“快速访问”，编辑配置文件时，永远用VS Code（免费、轻量、JSON语法高亮+自动格式化）。

2.4 Windows系统级权限的隐形门槛：为什么taskkill是重启的唯一正解

在Windows上， openclaw gateway 启动后，它会在后台以 node.exe 进程的形式持续运行。当你修改完 openclaw.json 想重启时，很多人习惯性地关掉终端窗口，以为服务停了。但事实是：终端窗口只是 node.exe 的父进程，关掉它， node.exe 子进程依然在后台挂着，继续读取旧的配置。这就是为什么你改了API Key，重启网关后还是报401；改了模型列表， openclaw models list 还是显示旧的。唯一的、彻底的清理方式，就是用 taskkill /f /im node.exe 强制杀死所有Node.js进程。这个命令的威力很大，它会干掉你所有正在运行的Node.js应用（比如本地开发的Vue项目、Express服务器），所以执行前最好确认一下。更稳妥的做法是先用 tasklist /fi "imagename eq node.exe" 列出所有node进程，再用 taskkill /f /pid <PID> 精确杀死OpenClaw对应的进程。不过对于新手， taskkill /f /im node.exe 简单粗暴有效，配合 npm uninstall -g openclaw && npm install -g openclaw@latest --force 重装，能100%解决“配置不生效”的玄学问题。记住，这不是Bug，是Windows进程管理的固有特性，所有基于Node.js的本地服务都面临同样的问题。

3. 十大高频坑位的深度拆解与实操方案：每一个命令都有来处

这十个坑，是我用三天时间，从凌晨两点到早上六点，逐行比对OpenClaw源码、调试日志、网络请求包，最终锁定的最核心断点。它们不是随机出现的，而是环环相扣：第一个坑没解决，会直接导致第二个坑必然发生；第三个坑的解决方案，又依赖于第四个坑的配置前提。下面我将每个坑的“报错现象—底层原理—实操命令—验证方法”四件套全部展开，确保你不仅知道“怎么做”，更明白“为什么这么做”。

3.1 坑位1：“openclaw不是内部或外部命令”——环境变量的失守

现象还原 ：在PowerShell里输入 openclaw gateway ，系统直接返回“openclaw : 无法将‘openclaw’项识别为 cmdlet、函数、脚本文件或可运行程序的名称。”
原理深挖 ： npm install -g 的本质，是把包里的可执行文件（这里是 openclaw.cmd ）链接到npm的全局bin目录（ C:\Users\你的用户名\AppData\Roaming\npm ）。这个目录必须在系统的PATH环境变量里，Windows才能在任意路径下识别 openclaw 命令。新手常犯的错误有两个：一是安装Node.js时没勾选“Add to PATH”，二是安装后没重启终端，导致PATH变量没刷新。 npx openclaw gateway 之所以能用，是因为 npx 是npm内置的命令执行器，它会自动查找 node_modules/.bin 下的可执行文件，不依赖PATH。
实操方案 ：

先执行 npm config get prefix ，确认全局安装路径是 C:\Users\你的用户名\AppData\Roaming\npm ；
打开“系统属性→高级→环境变量”，在“系统变量”里找到 Path ，点击“编辑”，新增一行，填入 C:\Users\你的用户名\AppData\Roaming\npm （把“你的用户名”替换成你的真实用户名）；
最关键的一步 ：关闭当前所有PowerShell窗口，重新打开一个新的，再运行 openclaw --version ，如果看到版本号，说明PATH生效。
验证方法 ： where openclaw 命令会返回 C:\Users\你的用户名\AppData\Roaming\npm\openclaw.cmd ，证明命令已注册成功。

3.2 坑位2：“git@github.com Permission denied”——协议层的握手失败

现象还原 ： npm install -g openclaw 执行到一半，卡在 @openclaw/core ，然后报错“Error: Command failed: git clone --mirror ... git@github.com:openclaw/core.git”。
原理深挖 ：如前所述，这是npm试图用SSH协议拉取GitHub仓库，但国内网络对SSH端口（22）的连接成功率极低。OpenClaw的作者在 package.json 里写的是SSH URL，是为了保证代码仓库的私有性（虽然core是公开的），但这给国内用户带来了不必要的障碍。
实操方案 ：

# 这三行必须按顺序执行，缺一不可
npm config set registry https://registry.npmmirror.com
npm config set @openclaw:registry https://registry.npmmirror.com
npm install -g openclaw --force --ignore-scripts

第二行 @openclaw:registry 是关键，它为 @openclaw 作用域下的所有包单独指定镜像源，确保即使未来有其他依赖也走HTTPS。 --force 参数强制覆盖已存在的旧版本，避免版本冲突。
验证方法 ：安装过程中，你会看到大量 https://registry.npmmirror.com 的下载日志，而不是 git+ssh:// ，说明协议已切换。

3.3 坑位3：“Update error: global update”——前端按钮与后端逻辑的脱节

现象还原 ：Web面板里的“Update”按钮点击后，弹出红色提示“Update error: global update (omit optional)”，反复点击无效。
原理深挖 ：OpenClaw的Web面板（Dashboard）里的更新功能，本质是调用 npm update -g openclaw 命令。但这个命令在Windows上有一个致命缺陷：它无法正确处理全局安装包的符号链接（symlink），尤其是在 --force 安装后，链接可能损坏。更深层的原因是，OpenClaw的 package.json 里没有定义 "bin" 字段的更新钩子，导致 npm update 找不到正确的更新入口。
实操方案 ：

# 彻底清理，从零开始
taskkill /f /im node.exe
npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest --force --ignore-scripts

npm cache clean --force 是保险丝，清除所有可能的缓存污染。
验证方法 ：安装完成后，运行 openclaw --version ，确认版本号是最新发布的（比如 v0.12.3 ），然后在Web面板里点击“Update”，会显示“Already up to date”，说明后端已同步。

3.4 坑位4：模型配置好却看不到——JSON Schema的三重门禁

现象还原 ：在 openclaw.json 里添加了豆包、千问的模型ID，但 openclaw models list 只显示 deepseek-chat ，其他模型完全不出现。
原理深挖 ：OpenClaw的模型加载逻辑有三道硬性校验：

别名门禁 ： agents.defaults.models 下的每个模型ID，必须有 "alias" 字段，否则前端UI认为该模型“不可见”；
白名单门禁 ： agents.defaults.model.allowed 数组，必须显式包含该模型ID，否则网关拒绝路由请求；
结构门禁 ：整个 agents 对象必须是 openclaw.json 的顶层键之一，不能嵌套在其他对象里（比如有人误写成 "config": {"agents": {...}} ）。
实操方案 ：将以下完整区块， 严格复制 到 openclaw.json 的 agents 对象内部（注意替换 your_api_key_here ）：

"defaults": {
  "models": {
    "zai/glm-5": { "alias": "GLM-5", "apiKey": "sk-your_zhipu_key" },
    "qwen/qwen-turbo": { "alias": "通义千问", "apiKey": "sk-your_qwen_key" },
    "doubao/doubao-1-5-pro-32k-character-250715": { "alias": "豆包", "apiKey": "your_doubao_api_key" }
  },
  "model": {
    "allowed": ["zai/glm-5", "qwen/qwen-turbo", "doubao/doubao-1-5-pro-32k-character-250715"],
    "primary": "qwen/qwen-turbo"
  }
}

验证方法 ：保存后，运行 openclaw doctor ，它会输出“✅ All models are configured and accessible”，同时 openclaw models list 会清晰列出三个模型及其别名。

3.5 坑位5：“doubao-lite-8k不存在”——模型ID的时效性陷阱

现象还原 ：在 allowed 数组里填了 "doubao/doubao-lite-8k" ，启动时报错“Model 'doubao/doubao-lite-8k' not found”。
原理深挖 ：火山方舟（Doubao）的模型ID是动态演进的。 doubao-lite-8k 是早期测试版ID，2024年Q2已正式下线，新ID为 doubao-1-5-pro-32k-character-250715 ，其中 250715 代表发布日期（2025年7月15日）。OpenClaw的模型发现机制是静态匹配，它不会主动去火山方舟API查询可用模型列表，而是严格按你写的ID去初始化。
实操方案 ：

永远使用官方文档最新版ID： doubao-1-5-pro-32k-character-250715 ；
如果你不确定，可以访问火山方舟控制台，在“模型服务”页面，找到对应模型，点击“接入指南”，复制“模型ID”字段的值；
在 openclaw.json 中，确保ID格式为 "doubao/xxx" ，斜杠前缀 doubao/ 是必须的，这是OpenClaw识别火山方舟模型的命名空间。
验证方法 ： openclaw models list 输出中，豆包模型的ID必须完全匹配，且状态为 active 。

3.6 坑位6：“context window too small”——上下文窗口的硬性标尺

现象还原 ：启动网关时，日志里滚动着黄色警告“Warning: Model 'qwen/qwen-turbo' has context window 8192, but minimum required is 16000”。
原理深挖 ：OpenClaw为了保证多轮对话的连贯性，对模型的上下文窗口（Context Window）有硬性要求。它默认设定最小值为16000，因为像豆包Pro、GLM-5这类大模型，其设计上下文都在128K以上，如果允许小窗口模型接入，可能导致长对话时历史记录被截断，AI“忘记”前面聊了什么。 qwen-turbo 的官方规格确实是8192，但它属于轻量级模型，OpenClaw的警告是善意提醒，而非阻止启动。
实操方案 ：

推荐方案（换模型） ：将 primary 模型切换为 deepseek-chat （128K）、 qwen-plus （131K）或 glm-5 （204K），它们原生满足要求；
应急方案（降标尺） ：运行 openclaw config set agent.contextWindow 8192 ，这会修改全局上下文阈值，让 qwen-turbo 也能被接纳。但要注意，这可能导致复杂多轮对话时体验下降。
验证方法 ：运行 openclaw config get agent.contextWindow ，确认返回值为你设置的数字。

3.7 坑位7：“429 Too Many Requests”——免费额度的物理边界

现象还原 ：微信里发 /ask ，ClawBot回复“429 Too Many Requests”，或者Web面板里测试模型时，返回HTTP 429状态码。
原理深挖 ：这是标准的HTTP限流响应，表明你的API Key在火山方舟/智谱/通义的后台，当日调用次数已达到免费额度上限（通常为1000次/天）。OpenClaw本身不参与限流，它只是把上游服务的原始响应透传回来。
实操方案 ：

# 切换到另一个仍有额度的模型
openclaw config set agents.defaults.model.primary "zai/glm-5"
openclaw gateway restart

关键技巧 ：不要等额度“自然恢复”，可以登录对应平台控制台，手动重置API Key（生成新Key），旧Key立即失效，新Key获得全新额度。
验证方法 ：在微信里发 /models ，确认当前 primary 模型已切换；再发 /ask 测试 ，收到正常回复即成功。

3.8 坑位8：JSON报错导致网关启动失败——语法洁癖的代价

现象还原 ： openclaw gateway 启动失败，日志只有一行“Error: invalid config”，没有任何具体行号。
原理深挖 ：OpenClaw使用 ajv （Another JSON Schema Validator）库进行配置校验，它对JSON语法的容错率为零。常见错误有：

数组最后一项后多了一个逗号（ "models": ["a", "b",] ）；
字符串值用了中文双引号（ "alias"： "GLM-5" ）；
缩进不一致导致层级错乱（ "models" 和 "model" 不在同一缩进级别）。
实操方案 ：
终极检查法 ：将整个 openclaw.json 内容，粘贴到在线JSON校验网站（如jsonlint.com），它会精确定位到第几行第几列的错误；
VS Code快捷键 ： Shift+Alt+F 自动格式化， Ctrl+Shift+P 输入“JSON: Validate”开启实时校验；
安全写法 ：所有字符串值，用英文双引号包裹；所有数组、对象，末尾不加逗号；用4个空格缩进，不用Tab。
验证方法 ： openclaw doctor 命令能成功执行并输出完整诊断报告。

3.9 坑位9：智谱GLM模型配置失败——Provider模式的命名规范

现象还原 ：添加了 zhipu/glm-5 ，但 openclaw models list 里没有GLM-5，或者启动时报错“Provider 'zhipu' not found”。
原理深挖 ：OpenClaw对智谱的支持，不是简单的模型ID映射，而是通过 providers 插件机制实现的。它要求：

Provider的 id 必须是 zai （不是 zhipu ），这是OpenClaw内部约定的智谱标识符；
baseUrl 必须是智谱官方V4 API的地址（ https://open.bigmodel.cn/api/coding/paas/v4 ），V3地址（ https://open.bigmodel.cn/api/paas/v3 ）不被支持；
api 字段必须是 openai-completions ，表示兼容OpenAI的Completions接口规范。
实操方案 ：在 openclaw.json 的 agents.defaults 同级，添加完整的 providers 区块：

"providers": {
  "zai": {
    "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
    "apiKey": "sk-your_zhipu_api_key",
    "api": "openai-completions",
    "models": [
      {
        "id": "glm-5",
        "name": "GLM-5",
        "reasoning": true,
        "contextWindow": 204800,
        "maxTokens": 131072
      }
    ]
  }
}

验证方法 ： openclaw doctor 会显示“✅ Provider 'zai' is configured and healthy”。

3.10 坑位10：ClawBot绑定失败——通道未激活的静默故障

现象还原 ：运行 openclaw channels login clawbot 后，弹出二维码，微信扫码显示“登录成功”，但微信里发 /models 没反应。
原理深挖 ： openclaw channels login 只是完成了OAuth2.0授权，把你的微信账号和OpenClaw服务做了绑定。但真正的消息通道，是由 openclaw gateway 启动时，根据 channels 配置动态加载的。如果你没在 openclaw.json 里显式启用 clawbot 通道，即使授权成功，网关也不会监听微信消息。
实操方案 ：

在 openclaw.json 的根对象里，添加 "channels" 字段：

"channels": {
  "clawbot": {
    "enabled": true,
    "port": 3001
  }
}

保存后，运行：

openclaw gateway restart

验证方法 ：启动日志里会有一行“✅ ClawBot channel is listening on port 3001”，同时微信里发 /ping ，会收到“pong”回复。

4. 实操全流程：从零到微信可用的完整闭环

现在，我们把前面所有知识点，串联成一条平滑的、可复现的实操流水线。整个过程控制在20分钟内，不需要任何额外工具，只用Windows自带的PowerShell和VS Code。我会把每一步的预期结果、常见偏差、以及如何判断这一步是否成功，都写清楚，让你心里有底。

4.1 环境初始化：构建纯净的起点

目标：确保Node.js、npm、网络源全部处于OpenClaw最友好的状态。
步骤：

卸载所有现有Node.js，从 nodejs.org 下载 node-v18.19.1-x64.msi ，安装时勾选“Add to PATH”和“Automatically install the necessary tools”；
打开新的 PowerShell窗口，运行：

node -v # 应输出 v18.19.1
npm -v  # 应输出 9.9.0
npm config set registry https://registry.npmmirror.com
npm config set @openclaw:registry https://registry.npmmirror.com

运行 npm config get prefix ，确认路径为 C:\Users\你的用户名\AppData\Roaming\npm ；
将该路径添加到系统PATH（如果上一步没自动完成）。
成功标志 ： where openclaw 命令无输出（说明还没装），但 node 和 npm 命令均能正常返回版本号。

4.2 OpenClaw安装与首次启动：见证网关诞生

目标：让 openclaw gateway 命令能成功运行，并打开Web面板。
步骤：

在PowerShell中执行：

npm cache clean --force
npm install -g openclaw@latest --force --ignore-scripts

安装完成后，立即运行：

openclaw gateway

打开浏览器，访问 http://localhost:3000 ，你应该能看到OpenClaw的Web Dashboard首页。
成功标志 ：浏览器页面左上角显示“OpenClaw Gateway v0.12.3”，右上角有“Models”、“Channels”等菜单。如果页面空白或报错，回到上一步，检查npm源是否设置正确。

4.3 配置文件精细化改造：注入你的AI军团

目标：让 openclaw.json 具备多模型、多通道、可微信交互的能力。
步骤：

关闭 openclaw gateway （Ctrl+C）；
用VS Code打开 C:\Users\你的用户名\.openclaw\openclaw.json ；
将以下 完整内容 ，覆盖 openclaw.json 的全部内容（请务必替换 your_***_key 为你的真实API Key）：

{
  "agents": {
    "defaults": {
      "models": {
        "zai/glm-5": { "alias": "GLM-5", "apiKey": "sk-your_zhipu_key" },
        "qwen/qwen-turbo": { "alias": "通义千问", "apiKey": "sk-your_qwen_key" },
        "doubao/doubao-1-5-pro-32k-character-250715": { "alias": "豆包", "apiKey": "your_doubao_api_key" }
      },
      "model": {
        "allowed": ["zai/glm-5", "qwen/qwen-turbo", "doubao/doubao-1-5-pro-32k-character-250715"],
        "primary": "qwen/qwen-turbo"
      }
    },
    "providers": {
      "zai": {
        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
        "apiKey": "sk-your_zhipu_key",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "reasoning": true,
            "contextWindow": 204800,
            "maxTokens": 131072
          }
        ]
      }
    }
  },
  "channels": {
    "clawbot": {
      "enabled": true,
      "port": 3001
    }
  }
}

保存文件（ Ctrl+S ），确保VS Code右下角显示“UTF-8”编码。
成功标志 ：运行 openclaw doctor ，输出中包含“✅ All models are configured”和“✅ ClawBot channel is enabled”。

4.4 微信ClawBot绑定与终极验证：把AI装进口袋

目标：在微信里，用自然语言和你的本地AI对话。
步骤：

确保网关已停止（Ctrl+C），然后运行：

openclaw channels login clawbot

微信扫描弹出的二维码，确认授权；
授权成功后，运行：

openclaw gateway restart

打开微信，搜索并关注公众号“ClawBot”；
在公众号对话框，发送：

/models —— 查看所有可用模型；
/model zai/glm-5 —— 切换到GLM-5；
/ask 写一首关于春天的七言绝句 —— 发起一次AI请求。
成功标志 ：微信里收到格式工整、内容合理的七言绝句，且响应时间在3秒内。如果超时，检查 openclaw gateway 日志，看是否有 ClawBot channel is listening 字样。

5. 新手避坑锦囊与进阶技巧：那些文档里不会写的真相

经过上百次安装、配置、调试，我总结出一些超越基础操作的“暗知识”。它们不写在官方文档里，但能帮你省下至少半天时间，或者避免一次灾难性的配置失误。这些都是血泪教训换来的，毫无保留分享给你。

5.1 API Key的安全存储：别把密钥明文写在配置文件里

把 sk-xxx 这样的密钥直接写在 openclaw.json 里，是极大的安全隐患。一旦你把这个文件误传到GitHub，密钥就永久泄露了。OpenClaw支持环境变量注入，这才是生产环境的正确姿势。在 openclaw.json 里，把API Key字段改成环境变量引用：

"zai/glm-5": { "alias": "GLM-5", "apiKey": "${ZHIPU_API_KEY}" }

然后，在Windows系统里，设置用户环境变量：

变量名： ZHIPU_API_KEY
变量值：你的真实密钥
这样， openclaw gateway 启动时，会自动从系统环境变量里读取密钥，配置文件里只留占位符，安全又清爽。同样适用于 QWEN_API_KEY 、 DOUBAO_API_KEY 。

5.2 模型切换的“热重载”技巧：不用重启网关也能换模型

每次改 primary 模型都要 restart ，太慢了。OpenClaw提供了一个隐藏的API，可以实时切换：

curl -X POST http://localhost:3000/api/v1/agent/model \
  -H "Content-Type: application/json" \
  -d '{"model": "zai/glm-5"}'

把这个命令保存为 switch-to-glm.bat ，双击就能秒切。原理是调用了OpenClaw内部的 /api/v1/agent/model 端点，它会动态更新内存中的 primary 模型，无需重启进程。注意，这个API只在 openclaw gateway 运行时有效。

5.3 日志分级与问题定位：读懂OpenClaw的“悄悄话”

OpenClaw的日志默认是INFO级别，很多关键信息被过滤了。启动时加上 --log-level debug ，能看到完整的HTTP请求、响应头、模型加载详情：

openclaw gateway --log-level debug

日志里最值得关注的三行：

`✅ Loaded model 'qwen/qwen-turbo' with context window

智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

【金仓数据库征文】AI Agent查询延迟如何拆分与优化：从“慢在哪“到“怎么改“

智能体开发者社区

从 OpenClaw 端侧部署到机械臂抓取闭环—高通开发者城市创享工坊实践 (成都站)

智能体开发者社区

AI Agent落地踩坑实录：那些方案选型时没人告诉你的事

智能体开发者社区

所有评论(0)

查看更多评论

麻纪

@weixin_32578161

已为社区贡献4条内容

OpenClaw本地AI网关Windows安装避坑指南

麻纪

1. 项目概述：为什么OpenClaw值得你花时间啃下这第一关

2. 安装前的底层认知与环境准备：避开80%的无效挣扎

2.1 Node.js与npm的版本锚定：别信“最新版最好”

2.2 网络源与镜像的底层逻辑：为什么换源能解决Git权限问题

2.3 配置文件的物理位置与编辑器选择：一个空格引发的血案

2.4 Windows系统级权限的隐形门槛：为什么taskkill是重启的唯一正解

3. 十大高频坑位的深度拆解与实操方案：每一个命令都有来处

3.1 坑位1：“openclaw不是内部或外部命令”——环境变量的失守

3.2 坑位2：“git@github.com Permission denied”——协议层的握手失败

3.3 坑位3：“Update error: global update”——前端按钮与后端逻辑的脱节

3.4 坑位4：模型配置好却看不到——JSON Schema的三重门禁

3.5 坑位5：“doubao-lite-8k不存在”——模型ID的时效性陷阱

3.6 坑位6：“context window too small”——上下文窗口的硬性标尺

3.7 坑位7：“429 Too Many Requests”——免费额度的物理边界

3.8 坑位8：JSON报错导致网关启动失败——语法洁癖的代价

3.9 坑位9：智谱GLM模型配置失败——Provider模式的命名规范

3.10 坑位10：ClawBot绑定失败——通道未激活的静默故障

4. 实操全流程：从零到微信可用的完整闭环

4.1 环境初始化：构建纯净的起点

4.2 OpenClaw安装与首次启动：见证网关诞生

4.3 配置文件精细化改造：注入你的AI军团

4.4 微信ClawBot绑定与终极验证：把AI装进口袋

5. 新手避坑锦囊与进阶技巧：那些文档里不会写的真相

5.1 API Key的安全存储：别把密钥明文写在配置文件里

5.2 模型切换的“热重载”技巧：不用重启网关也能换模型

5.3 日志分级与问题定位：读懂OpenClaw的“悄悄话”

所有评论(0)

温馨提示：您尚未绑定手机号

麻纪