OpenClaw 安装部署与接入微信、QQ 指南

本文记录一次在 Windows 上安装 OpenClaw、配置 OpenRouter 模型、接入微信和 QQ Bot 的完整过程。目标是让读者可以按步骤复现，同时理解每一步背后的原理。

适用场景：

想在自己的电脑上运行 OpenClaw Gateway
想通过浏览器控制台和 OpenClaw 聊天
想把 OpenClaw 接入微信
想把 OpenClaw 接入 QQ Bot
使用 Windows / PowerShell 环境

一、核心原理

1. OpenClaw 由哪些部分组成

OpenClaw 本地部署后主要包含四层：

用户聊天入口
  - Web 控制台
  - 微信
  - QQ Bot

OpenClaw Gateway
  - 本机常驻服务
  - 默认监听 http://127.0.0.1:18789
  - 负责接收消息、路由消息、调用模型、返回回复

模型提供商
  - OpenRouter / OpenAI / DeepSeek / Qwen 等
  - OpenClaw 本身不内置大模型，需要 API Key

本地配置与状态
  - ~/.openclaw/openclaw.json
  - ~/.openclaw/agents
  - ~/.openclaw/openclaw-weixin

简单理解：

微信 / QQ / 浏览器
        ↓
OpenClaw Gateway
        ↓
模型 API，例如 OpenRouter
        ↓
OpenClaw Gateway
        ↓
回到微信 / QQ / 浏览器

2. Gateway 是什么

Gateway 是 OpenClaw 的本地网关。它负责：

启动浏览器控制台
管理 WebSocket 连接
管理设备配对和访问 token
接收微信、QQ 等渠道消息
把消息交给 agent
调用模型 API
把回复发送回原渠道

默认地址：

http://127.0.0.1:18789/
ws://127.0.0.1:18789

127.0.0.1 表示本机，默认只有你自己的电脑可以访问。

3. 模型配置的原理

OpenClaw 不是大模型本身，它需要连接模型提供商。本文使用 OpenRouter：

API Base URL: https://openrouter.ai/api/v1
模型: openrouter/free
兼容协议: OpenAI-compatible

OpenRouter 的免费模型会变化。教程里常见的 qwen/qwen3.6-plus:free 可能已经废弃，因此建议使用：

openrouter/free

它会由 OpenRouter 路由到当前可用的免费模型。

4. 微信和 QQ 的差异

微信接入使用的是 openclaw-weixin 插件，可以通过二维码授权绑定。

QQ 接入使用的是官方 QQ Bot API，不是直接扫码绑定个人 QQ。你需要先去 QQ 开放平台创建机器人，拿到：

AppID
AppSecret

然后配置到 OpenClaw。

二、安装前准备

1. 基础环境

Windows 建议使用 PowerShell。需要：

Node.js
npm
OpenClaw CLI

检查命令：

node --version
npm --version
openclaw --version

正常情况下可以看到类似：

v24.12.0
11.6.2
OpenClaw 2026.5.18

2. 准备模型 API Key

推荐使用 OpenRouter。准备一个 API Key，形如：

sk-or-v1-xxxxxxxx

注意：API Key 不要公开发布。如果曾经发到聊天、截图或文档中，建议去 OpenRouter 后台重新生成并废弃旧 key。

3. 准备 QQ Bot 凭证

如果要接入 QQ，需要：

打开 QQ 开放平台：https://q.qq.com/
登录
创建 Bot
在机器人设置页找到 AppID 和 AppSecret

配置时使用格式：

AppID:AppSecret

三、安装 OpenClaw

1. Windows 安装

用管理员模式打开 PowerShell：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr -useb https://openclaw.ai/install.ps1 | iex

安装完成后验证：

openclaw --version

2. 检查状态

openclaw status

重点看：

Gateway: reachable
Dashboard: http://127.0.0.1:18789/

如果 Gateway 没有运行，可以启动：

openclaw gateway run --force

四、配置 OpenRouter 模型

1. 运行 onboard

如果你想走交互式向导：

openclaw onboard --install-daemon

选择：

QuickStart
Custom Provider
OpenAI-compatible

填写：

API Base URL: https://openrouter.ai/api/v1
API Key: sk-or-v1-你的密钥
Model ID: openrouter/free

2. 非交互式配置思路

如果向导卡住，也可以直接写入配置。关键配置位于：

~/.openclaw/openclaw.json

核心字段包括：

{
  "models": {
    "mode": "merge",
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "api": "openai-completions",
        "apiKey": "sk-or-v1-你的密钥",
        "models": [
          {
            "id": "openrouter/free",
            "name": "OpenRouter Free Models Router",
            "input": ["text"]
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/openrouter/free"
      }
    }
  }
}

实际推荐还是优先使用 OpenClaw CLI，因为它会做 schema 校验。

3. 验证模型

openclaw config validate
openclaw agents list

确认看到：

Model: openrouter/free

测试一次模型调用：

openclaw agent --agent main --model openrouter/free --session-id openrouter-test --message "你好，请只回复：OpenClaw 已配置成功。"

正常输出：

OpenClaw 已配置成功。

五、打开 Web 控制台

启动 Gateway 后打开：

openclaw dashboard

或者只复制带 token 的 URL：

openclaw dashboard --no-open

如果页面提示需要 token，可以从配置中读取：

(Get-Content $HOME\.openclaw\openclaw.json -Raw | ConvertFrom-Json).gateway.auth.token

填入页面的 Gateway token 后点击连接。

首次连接可能提示设备配对，按页面提示执行：

openclaw devices approve <request-id>

如果还提示 scope upgrade，再执行：

openclaw devices list
openclaw devices approve <scope-upgrade-request-id>

六、接入微信

1. 安装并启用微信插件

如果已经安装，可以跳过。

检查：

openclaw plugins list

确认有：

openclaw-weixin

如果没有，安装：

openclaw plugins install @tencent-weixin/openclaw-weixin

启用：

openclaw config set plugins.entries.openclaw-weixin.enabled true

2. 微信扫码登录

运行：

openclaw channels login --channel openclaw-weixin

终端会显示二维码或链接。用手机微信扫码并确认授权。

扫码成功后，凭证会写入：

~/.openclaw/openclaw-weixin/accounts/

3. 检查微信状态

openclaw channels status --probe

成功时类似：

openclaw-weixin <account-id>: enabled, configured, running

此时可以在微信里给绑定的 OpenClaw 发消息测试。

七、接入 QQ Bot

1. 安装 QQBot 插件

openclaw plugins install @openclaw/qqbot

安装成功后会提示：

Installed plugin: qqbot
Restart the gateway to load plugins.

2. 配置 QQBot 凭证

准备 QQ 开放平台里的：

AppID
AppSecret

用下面格式配置：

openclaw channels add --channel qqbot --token "AppID:AppSecret"

示例：

openclaw channels add --channel qqbot --token "1234567890:你的AppSecret"

3. 检查 QQBot 状态

openclaw channels status --probe

成功时类似：

QQ Bot default: enabled, configured, running, connected, token:config

4. QQ 侧测试

私聊：给机器人发消息
群聊：把机器人加入群，通常需要 @ 它才会回复

如果群聊不回复，先确认：

QQ 开放平台中机器人已启用
机器人已加入群
群消息权限已打开
发送时有 @ 机器人

八、常见报错与解决

1. PowerShell 提示 openclaw 命令找不到

原因：

npm 全局目录没有加入 PATH
PowerShell 执行策略限制
安装未完成

处理：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

重新打开 PowerShell，再检查：

openclaw --version

2. Web 控制台提示需要认证

现象：

Gateway 可以访问，但此浏览器连接前需要匹配的令牌或密码。

解决：

openclaw dashboard --no-open

复制带 token 的 URL，或手动填入：

(Get-Content $HOME\.openclaw\openclaw.json -Raw | ConvertFrom-Json).gateway.auth.token

3. Web 控制台提示需要设备配对

现象：

需要设备配对
openclaw devices approve <request-id>

解决：

openclaw devices approve <request-id>

如果还有 scope upgrade：

openclaw devices list
openclaw devices approve <新的 request-id>

4. OpenRouter 模型报 404 deprecated

现象：

404 The free model has been deprecated.
Transition to qwen/qwen3.6-plus for continued paid access.

原因：

某个免费模型 ID 被 OpenRouter 下线。

解决：

把模型改成：

openrouter/free

然后验证：

openclaw agents list

5. OpenAI 401 Incorrect API key

现象：

401 Incorrect API key provided

原因：

OpenClaw 仍在使用旧的 OpenAI 模型或旧 API Key。

解决：

检查默认模型：

openclaw config get agents.defaults.model.primary
openclaw agents list

确认不是：

openai/gpt-5.5

应切到：

openrouter/free

6. 微信登录 Config write rejected

现象：

Config write rejected: ~/.openclaw/openclaw.json (size-drop:14829->5065)
Rejected payload saved to ~/.openclaw/openclaw.json.rejected...

原因：

OpenClaw 的配置保护机制认为新配置体积大幅下降，有误删风险，因此拒绝写入。

解决思路：

找到 rejected 配置：

Get-ChildItem $HOME\.openclaw -Filter "openclaw.json.rejected.*"

校验 rejected 配置：

$rej = Get-ChildItem $HOME\.openclaw -Filter "openclaw.json.rejected.*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
$env:OPENCLAW_CONFIG_PATH=$rej.FullName
openclaw config validate

如果校验通过，备份当前配置，再替换：

Copy-Item $HOME\.openclaw\openclaw.json "$HOME\.openclaw\openclaw.json.bak"
Copy-Item $rej.FullName $HOME\.openclaw\openclaw.json -Force
Copy-Item $rej.FullName $HOME\.openclaw\openclaw.json.last-good -Force

然后重新运行：

openclaw channels login --channel openclaw-weixin

原因可能是：

腾讯微信登录服务瞬时网络失败
本机 HTTPS 请求被代理或安全软件影响
插件请求超时

排查：

Test-NetConnection ilinkai.weixin.qq.com -Port 443
node -e "fetch('https://ilinkai.weixin.qq.com').then(r=>console.log(r.status)).catch(console.error)"

如果 Node 访问正常，可以稍后重试：

openclaw channels login --channel openclaw-weixin

8. Gateway service missing

现象：

Gateway service missing.
Scheduled Task missing.

原因：

Windows 计划任务服务没有安装或不可用。

临时启动：

openclaw gateway run --force

如果希望开机常驻，可尝试：

openclaw gateway install

9. config-health.json EPERM

现象：

Config health-state write failed:
~/.openclaw/logs/config-health.json: EPERM

影响：

通常不影响聊天、微信、QQBot，只是健康状态文件写入失败。

处理：

以管理员 PowerShell 运行 OpenClaw 命令
检查安全软件是否锁定该文件
删除或修复该文件权限后重试

示例：

$p = "$HOME\.openclaw\logs\config-health.json"
attrib -R $p

如果仍然失败，可以先忽略。

九、最终验收清单

1. OpenClaw CLI

openclaw --version

2. 配置合法

openclaw config validate

3. Gateway 可访问

openclaw gateway status

应看到：

Listening: 127.0.0.1:18789

4. 模型可用

openclaw agent --agent main --model openrouter/free --session-id test --message "你好，请只回复：成功。"

应返回：

成功。

5. 微信在线

openclaw channels status --probe

应看到：

openclaw-weixin ... running

6. QQBot 在线

openclaw channels status --probe

应看到：

QQ Bot default: enabled, configured, running, connected

十、安全建议

不要把 OpenRouter API Key、QQ AppSecret 写进公开文档
如果密钥曾经发到聊天或截图里，建议立刻轮换
Web 控制台只在本机使用时保持 127.0.0.1
不要随意把 Gateway 暴露到公网
设备配对的 operator/admin 权限只批准自己信任的浏览器

十一、常用命令速查

# 查看版本
openclaw --version

# 查看整体状态
openclaw status

# 启动 Gateway
openclaw gateway run --force

# 打开 Dashboard
openclaw dashboard

# 只复制带 token 的 Dashboard URL
openclaw dashboard --no-open

# 校验配置
openclaw config validate

# 查看 agent 模型
openclaw agents list

# 测试模型
openclaw agent --agent main --model openrouter/free --session-id test --message "你好"

# 微信登录
openclaw channels login --channel openclaw-weixin

# 安装 QQBot
openclaw plugins install @openclaw/qqbot

# 配置 QQBot
openclaw channels add --channel qqbot --token "AppID:AppSecret"

# 检查渠道
openclaw channels status --probe

PREVIOUSUni-app 项目如何用 GitHub CI/CD 自动部署到 GitHub Pages：完整 SOP、底层原理与避坑总结

一、核心原理

1. OpenClaw 由哪些部分组成

2. Gateway 是什么

3. 模型配置的原理

4. 微信和 QQ 的差异

二、安装前准备

1. 基础环境

2. 准备模型 API Key

3. 准备 QQ Bot 凭证

三、安装 OpenClaw

1. Windows 安装

2. 检查状态

四、配置 OpenRouter 模型

1. 运行 onboard

2. 非交互式配置思路

3. 验证模型

五、打开 Web 控制台

六、接入微信

1. 安装并启用微信插件

2. 微信扫码登录

3. 检查微信状态

七、接入 QQ Bot

1. 安装 QQBot 插件

2. 配置 QQBot 凭证

3. 检查 QQBot 状态

4. QQ 侧测试

八、常见报错与解决

1. PowerShell 提示 openclaw 命令找不到

2. Web 控制台提示需要认证

3. Web 控制台提示需要设备配对

4. OpenRouter 模型报 404 deprecated

5. OpenAI 401 Incorrect API key

6. 微信登录 Config write rejected

7. 微信登录 Failed to start login: TypeError: fetch failed

8. Gateway service missing

9. config-health.json EPERM

九、最终验收清单

1. OpenClaw CLI

2. 配置合法

3. Gateway 可访问

4. 模型可用

5. 微信在线

6. QQBot 在线

十、安全建议

十一、常用命令速查