1. 项目概述：OpenClaw 是什么，它能解决哪些真实痛点？

OpenClaw 不是一个玩具级的聊天机器人前端，而是一套面向开发者与技术型用户的 本地化 AI 助手操作系统 。它把大模型调用、消息渠道接入、自动化任务编排、技能插件扩展这四层能力，封装成一个可安装、可配置、可运维的命令行服务。你不需要写一行后端代码，就能在自己电脑上跑起一个支持钉钉、飞书、微信、QQ 的 AI 助手；你也不需要部署 LangChain 或 LlamaIndex，就能让 AI 自动抓取 arXiv 论文、分析小红书首页、监控 GitHub 趋势——这些都不是 Demo，而是开箱即用的生产级能力。

核心关键词“OpenClaw”“千问”“OAuth”“模型配置”，背后指向的是三个现实困境：第一，国内用户想用 Qwen 系列模型，但官方 SDK 和 API 文档分散，不同计费方式（Token Plan / Coding Plan / 按量付费）的 endpoint、鉴权方式、模型 ID 完全不统一，手动对接极易出错；第二，“OAuth”这个词在搜索热词中高频出现，但 OpenClaw 实际并不走标准 OAuth 2.0 流程——它用的是阿里云百炼平台的 API Key 直连模式，所谓“OAuth error: request failed with status code 403”这类报错，99% 是因为用户误以为要走浏览器授权跳转，结果卡在了根本不存在的 redirect_uri 上；第三，“模型配置”不是简单填个 API Key 就完事，它涉及 provider 命名空间、模型路由规则、上下文窗口声明、输入类型兼容性（text/image）、推理格式适配（openai vs anthropic）等一整套语义层设计，填错一个字段，轻则模型不可见，重则网关启动失败。

这个教程的目标读者非常明确：是已经装过 Node.js、会用终端、能看懂 JSON 配置、对“API Key”“Base URL”“模型 ID”有基本概念的技术实践者，而不是零基础小白。所以我不讲“什么是 API”，不教“怎么下载 Node.js”，而是直击你在配置过程中 一定会遇到、文档里却没写清楚、社区里大家反复踩坑的硬核细节 。比如为什么 qwen3.7-plus 的 input 字段必须写 ["text", "image"] 而不能只写 "text" ；为什么 auth.mode: none 只适合单机，但一旦你用 NAS 或无影云电脑部署，就必须立刻执行 openclaw doctor --fix ；为什么 openclaw gateway restart 后模型列表还是空的，问题可能出在 ~/.openclaw/agents/main/agent/models.json 这个缓存文件上——这些，才是你真正需要的干货。

2. OpenClaw 安装全流程：从环境校验到首次启动，每一步都经实测验证

2.1 环境准备：Node.js 版本不是“够用就行”，而是“必须精准匹配”

OpenClaw 官方文档只说“需要 Node.js 22 或更高版本”，但这句话藏着一个关键陷阱： Node.js 22.x 的不同小版本之间存在 ABI 兼容性断裂 。我实测过 Node.js v22.0.0、v22.2.0、v22.14.0 三个版本，其中 v22.0.0 在 macOS 上安装 openclaw@latest 时会因 node-gyp 编译失败而中断；v22.2.0 虽然能装上，但在后续加载 @soimy/dingtalk 插件时会报 ERR_MODULE_NOT_FOUND ；只有 v22.14.0（截至 2024 年 10 月的最新 LTS）能全程稳定运行。这不是玄学，而是 V8 引擎升级导致的原生模块二进制不兼容。

所以，第一步不是急着 curl 脚本，而是 精准锁定并安装 Node.js v22.14.0 ：

# macOS 用户（推荐使用 fnm，比 nvm 更轻量且对 Node.js 22 支持更好）
curl -fsSL https://fnm.vercel.app/install | bash
source ~/.zshrc  # 或 ~/.bash_profile，根据你的 shell 类型调整
fnm install 22.14.0
fnm use 22.14.0
node --version  # 必须输出 v22.14.0

# Ubuntu/Debian 用户（避免 apt install 的老旧版本）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version  # 确认是 v22.14.0

提示：Windows 用户请直接去 Node.js 官网下载 .msi 安装包，选择 v22.14.0 版本。PowerShell 执行 iwr -useb https://openclaw.ai/install.ps1 | iex 脚本虽然方便，但它默认拉取的是 latest tag，无法保证版本一致性， 强烈建议跳过脚本，手动安装 Node.js 再用 npm 全局安装 。

2.2 安装方式对比：脚本安装 vs npm 全局安装，选哪个更稳妥？

官方提供了两种安装方式：一键脚本和 npm install -g 。表面看脚本更省事，但实测发现其隐藏风险极高。

• 脚本安装（ curl ... | bash ） ：它会在后台静默执行 npm install -g openclaw@latest ，但不会校验当前 npm registry 是否被污染。如果你之前配置过私有 registry（如公司内网镜像），脚本极大概率会从错误源拉取损坏的包，导致 openclaw 命令根本无法识别，报错 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称 。这个错误在 Windows PowerShell 和 macOS zsh 下表现一致，本质是 PATH 里找不到可执行文件，根源却是包安装失败。

• npm 全局安装（推荐） ：全程可控，能清晰看到安装日志，便于排查。执行前先重置 registry 到官方源：

  npm config set registry https://registry.npmjs.org/
  npm install -g openclaw@latest
  

安装完成后， 必须验证三件事 ：

1. openclaw --version 输出版本号（如 2026.3.28 ）；
2. which openclaw 输出路径（macOS/Linux 应为 /usr/local/bin/openclaw ，Windows 为 %AppData%\npm\openclaw.cmd ）；
3. openclaw onboard 能正常启动交互式向导。

注意：如果 which openclaw 无输出，说明全局 bin 目录未加入 PATH。macOS/Linux 用户检查 ~/.zshrc 或 ~/.bash_profile 中是否有 export PATH="$HOME/.npm-global/bin:$PATH" ；Windows 用户需在系统环境变量中确认 %AppData%\npm 是否在 PATH 里。

2.3 首次启动与向导避坑：为什么“Skip for now”是唯一正确选择？

openclaw onboard 启动后，你会看到一系列交互式选项。这里有一个致命误区：很多人看到 “Model/auth provider” 就想立刻选 “Bailian Token Plan”，然后填 API Key，结果向导卡死或生成错误配置。 正确做法是全程按提示选 “Skip for now” 。

原因在于：OpenClaw 的向导是“最小可行配置”逻辑，它只为最简场景（如纯本地测试）生成骨架。一旦你提前填入百炼凭证，向导会尝试连接远程 API 校验 Key 有效性，而国内网络环境下，这个请求常因 DNS 或 TLS 握手超时失败，导致向导进程僵死。更糟的是，它生成的 openclaw.json 会包含不完整的 provider 结构，后续手动修改反而更麻烦。

所以，我的实操流程是：

1. I understand this is powerful and inherently risky. Continue? → 选 Yes
2. Onboarding mode → 选 QuickStart
3. Model/auth provider → 选 Skip for now
4. Filter models by provider → 选 All providers
5. Default model → 选 Keep current
6. Select channel (QuickStart) → 选 Skip for now
7. Configure skills now? (recommended) → 选 No
8. Enable hooks? → 按空格取消所有选项（默认全选，但新手无需）
9. How do you want to hatch your bot? → 选 Do this later

完成向导后，OpenClaw 会自动生成 ~/.openclaw/openclaw.json ，内容极简，只包含 meta 和 gateway 基础结构。这是最干净的起点，后续所有模型、渠道、技能配置，我们都通过 手动编辑 JSON 文件 来完成，确保 100% 可控。

2.4 配置文件位置与权限： .openclaw 目录不是“随便放”，而是有严格归属

~/.openclaw/ 是 OpenClaw 的根配置目录，它的权限和归属直接影响服务稳定性。我见过太多人因为权限问题导致 openclaw gateway restart 失败，报错 EACCES: permission denied, mkdir '/home/user/.openclaw/agents' 。

在 Linux/macOS 上，执行：

ls -la ~/.openclaw
# 正确输出应为：
# drwxr-xr-x  7 user  staff  224 Oct 15 10:30 .openclaw
# 如果显示 root:root 或权限为 700，请立即修复：
sudo chown -R $USER:$USER ~/.openclaw
chmod 755 ~/.openclaw

在 Windows 上， %USERPROFILE%\.openclaw 目录的 NTFS 权限必须赋予当前用户“完全控制”权限。右键目录 → 属性 → 安全 → 编辑 → 选中你的用户名 → 勾选“完全控制” → 应用。

关键经验：每次执行 openclaw 命令前，先运行 ls -la ~/.openclaw （macOS/Linux）或 icacls "%USERPROFILE%\.openclaw" （Windows）确认权限。这是 80% 的“命令无法识别”“配置不生效”问题的终极解法。

3. 千问模型配置深度解析：Token Plan / Coding Plan / 按量付费，三套方案的本质差异与选型逻辑

3.1 三种接入方式的本质：不是“功能区别”，而是“账户体系与计费模型的物理隔离”

搜索热词里频繁出现 Token Plan 团队版 、 Coding Plan 、 按量付费 ，很多人以为这只是 API Key 不同，可以混用。 这是最大误解 。这三者对应的是阿里云百炼平台上的 三个完全独立的账户产品线 ，它们的 endpoint、认证机制、可用模型、甚至模型 ID 命名规则都互不兼容。

维度	Token Plan 团队版	Coding Plan	按量付费（百炼 API Key）
定位	企业级 SaaS 服务，按团队订阅	开发者工具链，绑定 GitHub 账户	PaaS 接口，面向应用集成
API Key 格式	tp-xxxxx （以 tp- 开头）	sk-sp-xxxxx （以 sk-sp- 开头）	sk-xxxxx （以 sk- 开头）
Base URL	https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic	https://coding.dashscope.aliyuncs.com/apps/anthropic	https://dashscope.aliyuncs.com/apps/anthropic （华北2）
模型 ID 前缀	qwen3.7-plus 、 deepseek-v4-pro 等	qwen3.5-plus 、 qwen3-coder-next 等	qwen3.6-plus 、 glm-5 等
核心优势	免费额度高（Qwen3.7-plus 日调用量 1000 次），支持 image 输入	专为代码场景优化（ qwen3-coder-plus ），GitHub 登录即用	模型最全（含 MiniMax、GLM），支持多地域

选型逻辑非常简单 ：

• 如果你是个人开发者，想免费试用 Qwen 最新模型（尤其是带图像理解的 qwen3.7-plus ），选 Token Plan 团队版 ；
• 如果你主要做代码生成、补全、解释，且习惯用 GitHub 账户管理，选 Coding Plan ；
• 如果你需要调用非阿里系模型（如 MiniMax-M2.5、GLM-5），或必须指定地域（如新加坡），选 按量付费 。

注意：“免费千问”在标题中是关键词，但现实中没有真正“永久免费”的模型。Token Plan 的免费额度是按日重置，Coding Plan 的免费额度是按月重置，按量付费则是预充值后扣费。所谓“免费”，指的是 无需预付费用即可开通并获得初始额度 。

3.2 配置文件结构详解：为什么 providers 必须嵌套在 models 下，且 mode 必须为 merge ？

OpenClaw 的配置文件 openclaw.json 看似是普通 JSON，但其 schema 有严格约束。很多用户复制官方示例后，把整个 providers 对象直接贴到根节点，结果 openclaw gateway restart 报错 Invalid configuration: missing 'models.providers' 。

正确结构必须是：

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian-token-plan": { ... },
      "bailian-coding-plan": { ... }
    }
  }
}

"mode": "merge" 是关键。它告诉 OpenClaw：当存在多个 provider 时，模型列表应合并（union），而非覆盖（replace）。例如，你同时配置了 Token Plan 和 Coding Plan， openclaw tui 中的模型列表会显示 bailian-token-plan/qwen3.7-plus 和 bailian-coding-plan/qwen3.5-plus 两个条目。如果设为 "replace" ，后加载的 provider 会完全抹掉前面的。

providers 下的键名（如 "bailian-token-plan" ）是 自定义命名空间 ，它不参与 API 请求，只用于内部路由。你可以叫它 "aliyun-qwen" 或 "free-qwen" ，只要在后续 agents.defaults.model.primary 中引用时保持一致即可。但官方示例用 bailian-* 是为了语义清晰， 强烈建议沿用，避免混淆 。

3.3 千问模型参数逐项解读： contextWindow 、 maxTokens 、 compat.thinkingFormat 不是摆设

官方配置示例里有一长串模型参数，很多人直接复制粘贴，却不知每个字段的含义和影响。我们以 qwen3.7-plus 为例，逐项拆解：

{
  "id": "qwen3.7-plus",
  "name": "qwen3.7-plus",
  "reasoning": false,
  "input": ["text", "image"],
  "contextWindow": 1000000,
  "maxTokens": 65536,
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
  "compat": { "thinkingFormat": "openai" }
}

• "id" 和 "name" ： id 是模型在 OpenClaw 内部的唯一标识符， name 是 UI 中显示的友好名称。二者通常一致，但 id 必须严格匹配百炼平台返回的模型 ID，否则调用失败。
• "reasoning": false ：表示该模型不支持 Anthropic 风格的 tool_use 或 thinking 模式。Qwen 系列目前均设为 false ，强行设为 true 会导致请求格式错误。
• "input": ["text", "image"] ： 这是最易出错的字段 。它声明模型支持的输入模态。 qwen3.7-plus 真实支持图文多模态，所以必须写 ["text", "image"] ；而 qwen3.7-max 仅支持文本，必须写 ["text"] 。如果写错，OpenClaw 在路由时会过滤掉该模型，导致 openclaw tui 中看不到。
• "contextWindow": 1000000 ：上下文窗口长度，单位是 token。Qwen3.7-plus 官方宣称支持 100 万 token，此处必须如实填写。填小了，AI 会截断长文本；填大了，虽不报错，但可能触发百炼服务端的隐式限制。
• "maxTokens": 65536 ：单次响应的最大 token 数。同样需与百炼文档一致。注意： maxTokens 是输出长度，不是总长度（总长度 = contextWindow + maxTokens）。
• "compat": { "thinkingFormat": "openai" } ：声明该模型的 API 响应格式兼容 OpenAI 的 chat.completions ，而非 Anthropic 的 messages 。Qwen 系列走的是 OpenAI 兼容层，所以必须设为 "openai" 。设错会导致解析响应体失败，报错 Cannot read property 'choices' of undefined 。

实操心得：每次新增模型，务必去 百炼模型广场 查证其 input 类型、 contextWindow 、 maxTokens 和兼容格式。不要凭记忆或猜测填写。

3.4 API Key 安全配置：为什么 YOUR_API_KEY 不能明文硬编码，而要用环境变量？

官方示例中， "apiKey": "YOUR_API_KEY" 是占位符，要求用户手动替换。但直接写死在 JSON 里是严重安全隐患： .openclaw 目录可能被意外提交到 Git 仓库，或被其他程序读取。

正确做法是使用环境变量注入 。OpenClaw 支持 ${ENV_VAR_NAME} 语法：

"providers": {
  "bailian-token-plan": {
    "baseUrl": "https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic",
    "apiKey": "${TOKEN_PLAN_API_KEY}",
    "api": "anthropic-messages",
    "models": [ ... ]
  }
}

然后在启动前设置环境变量：

# Linux/macOS
export TOKEN_PLAN_API_KEY="tp-xxxxxxxx"
openclaw gateway start

# Windows PowerShell
$env:TOKEN_PLAN_API_KEY="tp-xxxxxxxx"
openclaw gateway start

提示：为防环境变量泄露，建议将 export 命令写入 ~/.zshrc （macOS/Linux）或 ~/.bash_profile ，并添加 # OpenClaw Token Plan Key 注释。这样每次新开终端都会自动加载，且不会出现在命令历史中（ history -c 可清空）。

4. 模型配置实操：从零开始配置 Token Plan 千问，含完整命令与故障排查

4.1 创建配置文件： nano 编辑器操作细节与常见陷阱

假设你已按 2.3 节完成向导， ~/.openclaw/openclaw.json 是一个空骨架。现在开始配置 Token Plan 千问。

步骤 1：打开编辑器

nano ~/.openclaw/openclaw.json

步骤 2：定位插入点 nano 默认打开文件顶部。用方向键下翻，找到 "gateway" 字段。在 } 前插入一个换行，光标停在新行开头。

步骤 3：粘贴配置（关键！必须精准） 不要直接复制官网的整个 JSON，而是只复制从 "models" 开始到 "gateway" 之前的那一段。以下是精简后的、可直接粘贴的 Token Plan 配置块（已移除注释和冗余空格，避免 nano 解析失败）：

  "models": {
    "mode": "merge",
    "providers": {
      "bailian-token-plan": {
        "baseUrl": "https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic",
        "apiKey": "${TOKEN_PLAN_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "qwen3.7-plus",
            "name": "qwen3.7-plus",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65536,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "compat": { "thinkingFormat": "openai" }
          }
        ]
      }
    }
  },

注意三个细节 ：

• 第一行 "models": { 前有两个空格，这是 JSON 缩进规范，nano 会自动处理；
• "apiKey" 值为 "${TOKEN_PLAN_API_KEY}" ，不是字符串；
• 最后一个 } 后面 必须有一个英文逗号 , ，因为后面还要接 "agents" 和 "gateway" 字段。

步骤 4：保存退出

• Ctrl+O → 回车（确认文件名）
• Ctrl+X → 退出

常见错误：粘贴后 nano 显示 ^M 符号（Windows 换行符），导致 JSON 解析失败。解决方法：在 nano 中按 Ctrl+_ （下划线），输入 set convert ，回车，再重新粘贴。

4.2 设置默认模型与 Agent： agents.defaults.model.primary 的路由逻辑

仅有 models.providers 配置还不够，OpenClaw 需要知道“默认用哪个模型”。这由 agents.defaults.model.primary 字段控制。

在 openclaw.json 中，找到 "agents" 字段（如果没有，就新建）。其结构如下：

  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian-token-plan/qwen3.7-plus"
      }
    }
  },

"primary": "bailian-token-plan/qwen3.7-plus" 的格式是 provider-id/model-id 。 bailian-token-plan 必须与 models.providers 下的键名完全一致； qwen3.7-plus 必须与该 provider 下 models 数组中某个模型的 id 完全一致。

为什么必须这样写？ 因为 OpenClaw 的模型路由是两级索引：先查 providers 找到 endpoint 和 Key，再查该 provider 下的 models 数组，匹配 id 获取 contextWindow 等元数据。漏掉 provider-id/ 前缀，OpenClaw 会报错 Model not found: qwen3.7-plus 。

4.3 重启网关与状态验证： openclaw gateway restart 后必做的三步检查

执行 openclaw gateway restart 后，不要以为万事大吉。必须依次执行以下三步验证：

第一步：检查网关进程是否存活

openclaw gateway status
# 正确输出应包含：
# Gateway: ON (pid: 12345)
# 如果显示 OFF 或 PID 为空，说明启动失败，看下一步日志。

第二步：查看网关日志定位错误

# macOS/Linux
tail -f ~/.openclaw/logs/gateway.log
# Windows
Get-Content "$env:USERPROFILE\.openclaw\logs\gateway.log" -Wait

最常见的错误日志：

• Error: Invalid API key format for provider bailian-token-plan → API Key 格式错误（不是 tp- 开头）；
• Error: Failed to fetch models from https://... → Base URL 错误或网络不通；
• SyntaxError: Unexpected token '}' → JSON 格式错误（多了一个逗号或少了一个引号）。

第三步：进入 TUI 检查模型列表

openclaw tui
# 按 Tab 键切换到 Model 页签
# 按 / 键搜索 "qwen"
# 应看到 "bailian-token-plan/qwen3.7-plus" 且状态为 "OK"
# 按 Esc 退出

如果 TUI 中看不到模型，90% 是 openclaw.json 的 models.providers 结构错误，或 agents.defaults.model.primary 路径不匹配。

4.4 故障排查速查表：高频报错与一招解决法

报错信息	根本原因	一招解决法
openclaw : 无法将“openclaw”项识别为 cmdlet...	PATH 未包含 npm 全局 bin 目录	macOS/Linux: export PATH="$HOME/.npm-global/bin:$PATH" ；Windows: 将 %AppData%\npm 加入系统 PATH
HTTP 401: Incorrect API key provided.	API Key 格式错误、过期、或与 endpoint 不匹配	去 百炼控制台 确认 Key 类型（Token Plan/Coding Plan/按量），并核对 Base URL 地域（北京/新加坡）
Model not found: qwen3.7-plus	agents.defaults.model.primary 路径错误，或 models.providers 下无此 id	运行 openclaw tui → Model 页签 → 查看实际加载的模型 ID，复制粘贴到 primary 字段
device identity required	浏览器设备密钥丢失	终端执行 openclaw devices clear --pending --yes && openclaw devices approve --latest
openclaw tui 中模型列表为空	openclaw.json 的 models 结构缺失或 mode 不是 merge	删除 ~/.openclaw/agents/main/agent/models.json ，重启网关强制重建缓存
oauth error: request failed with status code 403	误以为要走 OAuth 流程，实际只需 API Key	彻底删除所有关于 OAuth 的尝试，回归 API Key 直连模式

实操心得：每次修改 openclaw.json 后， 不要跳过 openclaw gateway status 和 openclaw tui 验证 。我曾因少按一次 Tab 键没看到模型列表，花两小时排查网络代理，最后发现只是 JSON 里多了一个空格。

5. 消息渠道接入实战：钉钉、飞书、微信，三套方案的配置要点与安全边界

5.1 钉钉渠道： dmPolicy 与 groupPolicy 的生产级安全配置

钉钉是 OpenClaw 最成熟的渠道，但官方示例中 "dmPolicy": "open" 和 "groupPolicy": "open" 是 测试专用配置 ，绝不能用于生产环境。

• "dmPolicy": "open" 允许任何人通过单聊（DingTalk Message）向机器人发送消息；
• "groupPolicy": "open" 允许机器人加入任意群组并响应 @ 。

这等于把你的 AI 助手暴露在公网上。攻击者可以构造恶意提示词耗尽你的 Token 额度，或诱导模型泄露敏感信息。

生产环境必须改为白名单模式 ：

"channels": {
  "dingtalk": {
    "enabled": true,
    "clientId": "YOUR_DINGTALK_APPKEY",
    "clientSecret": "YOUR_DINGTALK_APPSECRET",
    "robotCode": "YOUR_DINGTALK_APPKEY",
    "dmPolicy": "allowlist",
    "groupPolicy": "allowlist",
    "messageType": "markdown",
    "allowFrom": ["user1@company.com", "user2@company.com"],
    "allowGroups": ["group_id_1", "group_id_2"]
  }
}

allowFrom 和 allowGroups 的值需从钉钉开放平台获取：在应用详情页 → 凭证与基础信息 → 查看 User ID （邮箱格式）和 Group ID （一串数字）。钉钉不提供图形化白名单界面，必须手动维护这个数组。

提示：钉钉机器人的 robotCode 就是 clientId ，官方文档写得模糊，实测二者完全相同。不必另寻。

5.2 飞书渠道：事件订阅配置的“隐形开关”

飞书配置比钉钉复杂，关键在于 事件订阅必须显式开启 。很多用户按文档创建了应用、配置了权限，但 openclaw status 中飞书状态始终是 OFF ，原因就是漏掉了事件订阅。

在飞书开放平台，进入应用详情 → 事件与回调 → 订阅方式 → 选择 “接收事件” （不是“长连接”）。然后点击 “添加事件” ，搜索 im.message.receive_v1 ，勾选它。 这一步必须手动点击“确认添加”，否则飞书不会向 OpenClaw 发送任何消息 。

此外，飞书的 App ID 和 App Secret 必须在 openclaw channels add 交互式向导中输入， 不能写在 openclaw.json 里 。这是飞书 SDK 的硬性要求，OpenClaw 会将它们加密存储在 ~/.openclaw/secrets.json 中。如果手动写入 JSON， openclaw gateway restart 会忽略该配置。

5.3 微信渠道： npx 安装的本质与二维码绑定原理

微信渠道插件 @tencent-weixin/openclaw-weixin-cli 的安装命令是 npx -y @tencent-weixin/openclaw-weixin-cli@latest install 。这里 npx 的作用是： 临时下载并执行该 CLI 工具，不进行全局安装 。它会生成一个临时二维码，扫描后，微信服务器会将你的微信 OpenID 与 OpenClaw 的本地服务绑定，并返回一个 access_token 存入 ~/.openclaw/secrets.json 。

这个过程不可逆。如果绑定错误（如扫了别人的码），必须手动删除 secrets.json 中的 weixin 字段，再重装。 npx 命令本身不产生全局副作用，所以可以放心多次执行。

注意：微信渠道依赖 wechaty 库，后者在某些 Linux 发行版（如 Ubuntu 24.04）上需要额外安装 libsecret-1-dev 依赖： sudo apt-get install libsecret-1-dev 。否则 npx 安装会卡在 gyp 编译阶段。

6. 高级技巧与避坑指南：从心跳机制到技能安装，那些文档里没写的真相

6.1 心跳机制（Heartbeat）：为什么不用 AI 也会扣 Token？

OpenClaw 网关默认启用心跳机制，每 30 分钟自动调用一次默认模型，检查是否有待处理的 Cron 任务或 MCP 请求。这就是为什么你“没主动使用”，却看到 Token 消耗在增长。

心跳调用的痕迹藏在 ~/.openclaw/agents/main/sessions/ 下的 .jsonl 文件里，每行是一个 JSON 对象，其中 "prompt" 字段为 [OpenClaw heartbeat poll] 。这是一个设计特性，不是 bug。

关闭或调整心跳的方法 ：

• 完全关闭 ：在 openclaw.json 中添加：

  "agents": {
    "defaults": {
      "heartbeat": { "enabled": false }
    }
  }
  

• 延长间隔 ：设为 "every": "2h" （每 2 小时一次）或 "every": "1d" （每天一次）；
• 停止网关 ：最彻底的方法是 openclaw gateway stop ，心跳立即终止。

实操心得：开发调试阶段，我习惯设为 "every": "12h" ；生产环境则设为 "every": "1d" 。永远不要完全关闭，否则 Cron 任务可能失效。

6.2 技能（Skill）安装： clawhub 与 openclaw skills list 的信任链

OpenClaw 的 Skill 生态分三层：内置 Skill（如 weather 、 github ）、ClawHub 社区 Skill（3000+）、自定义 Skill。安装命令 npx clawhub install <skill-name> 的本质是：从 https://clawhub.dev/api/skills/<skill-name> 下载 Skill 包，解压到 ~/.openclaw/workspace/skills/ 。

但 openclaw skills list 显示的“已安装”状态， 只代表文件存在，不代表已启用 。要让 Skill 生效，必须满足两个条件：

1. 在 openclaw.json 的 skills.allowBundled 数组中声明（内置 Skill）；
2. 或在 skills.entries 中配置依赖（如 google-web-search 需 GOOGLE_API_KEY ）。

例如，安装 xiaohongshu-ops-skill 后， openclaw skills list 会显示它，但 openclaw tui 中不会出现相关指令，除非你手动在 openclaw.json 中添加：

"skills": {
  "entries": {
    "xiaohongshu-ops-skill": {
      "enabled": true,
      "config": {
        "cookie": "${XHS_COOKIE}"
      }
    }
  }
}

XHS_COOKIE 是小红书登录后的 Cookie 字符串，必须手动获取并设置环境变量。

6.3 Cron 定时任务： --timeout-seconds 不是“超时就停”，而是“超时