# OpenClaw 接入指南

OpenClaw 是一款开源的个人 AI 助手框架，可以把同一个 AI 后端接到钉钉、飞书、微信、QQ 等多个聊天入口。本文介绍如何让 OpenClaw 使用 UModelverse 平台提供的模型。

## **系统要求**

| 平台 | 要求 |
| --- | --- |
| Windows | Windows 10 或 Windows 11 |
| macOS | macOS 10.15 (Catalina) 或更高版本 |
| Linux | Ubuntu 18.04+、CentOS 7+、Debian 9+ |

所有平台均需要：

-   Node.js 22+（OpenClaw 对 Node 版本要求较高，请勿低于 22）
    
-   网络连接
    

## **1. 安装 OpenClaw**

先确认本机 Node.js 版本符合要求：

```
node --version
```

若输出低于 22 或提示命令不存在，请前往 [Node.js 官网](https://nodejs.org/) 安装或升级后再继续。

### macOS / Linux

可使用官方脚本一键安装：

```
curl -fsSL https://openclaw.ai/install.sh | bash
```

也可以走 npm：

```
npm install -g openclaw@latest
```

### Windows

在 PowerShell 中运行官方脚本：

```
iwr -useb https://openclaw.ai/install.ps1 | iex
```

或同样使用 npm：

```
npm install -g openclaw@latest
```

### 初始化向导

安装结束后向导会自动弹出（也可随时执行 `openclaw onboard` 重新进入）。由于模型和渠道我们会在后续手动配置，这里按下表选择即可，先把向导走完：

| **配置项** | **建议选择** |
| --- | --- |
| I understand this is powerful and inherently risky. Continue? | **Yes** |
| Onboarding mode | **QuickStart** |
| Model/auth provider | **Skip for now** |
| Filter models by provider | **All providers** |
| Default model | **Keep current** |
| Select channel (QuickStart) | **Skip for now** |
| Configure skills now? (recommended) | **No** |
| Enable hooks? | 按空格选中后回车 |
| How do you want to hatch your bot? | **Do this later** |

## **2. 配置 UModelverse API**

OpenClaw 的全部配置都集中在 `~/.openclaw/openclaw.json` 这一个文件里，启动时自动读取。下面先准备好接入信息，再选择终端或 Web UI 任一方式写入。

### 2.1 准备接入信息

前往 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 获取 API Key，并记下以下信息：

| 项目 | 值 |
| --- | --- |
| API Key | 在 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 获取 |
| Base URL | `https://api.modelverse.cn` |
| 接口类型 | `anthropic-messages` |
| 可用模型 | UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models) |

> **关于网关鉴权：** 下文示例使用 `auth.mode: none`，即不对本地网关做鉴权，仅适合单机自用。若计划共享或远程访问，请执行 `openclaw doctor --fix` 开启 token 鉴权。

### 2.2 方式一：编辑配置文件（推荐）

1.  打开配置文件：
    
    ```
    nano ~/.openclaw/openclaw.json
    ```
    
2.  写入下列内容，把 `YOUR_API_KEY` 换成自己的 UModelverse API Key。若文件中已有其他配置，只新增/调整 `providers`、`agents` 相关字段，**不要整份覆盖**。
    
    ```
    {
      "models": {
        "mode": "merge",
        "providers": {
          "umodelverse": {
            "baseUrl": "https://api.modelverse.cn",
            "apiKey": "YOUR_API_KEY",
            "api": "anthropic-messages",
            "models": [
              {
                "id": "claude-sonnet-4-6",
                "name": "claude-sonnet-4-6",
                "reasoning": true,
                "input": ["text", "image"],
                "contextWindow": 200000,
                "maxTokens": 65536,
                "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
              },
              {
                "id": "claude-opus-4-8",
                "name": "claude-opus-4-8",
                "reasoning": true,
                "input": ["text", "image"],
                "contextWindow": 200000,
                "maxTokens": 65536,
                "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
              }
            ]
          }
        }
      },
      "agents": {
        "defaults": {
          "model": {
            "primary": "umodelverse/claude-sonnet-4-6"
          },
          "models": {
            "umodelverse/claude-sonnet-4-6": {},
            "umodelverse/claude-opus-4-8": {}
          }
        }
      },
      "gateway": {
        "mode": "local",
        "auth": { "mode": "none" }
      }
    }
    ```
    
    > 上面的 `models` 只是两个示例条目。你可以对照 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models) 增删，注意 `agents.defaults.models` 里的列表要和 `providers` 中声明的模型对应一致。
    
3.  保存退出：依次按 `Ctrl+X`、`Y`、`Enter`。
    
4.  重启网关让配置生效：
    
    ```
    openclaw gateway restart
    ```
    

### 2.3 方式二：通过 Web UI 编辑

> Web UI 仅在 OpenClaw **2026.3.28 及更早版本**提供，更新版本请使用方式一。

1.  启动控制台：
    
    ```
    openclaw dashboard
    ```
    
    在浏览器页面中进入左侧 **设置**，把编辑器从 **Form** 切到 **Raw** 模式。
    
2.  把方式一里的同一份 JSON 粘进编辑框，记得替换 `YOUR_API_KEY`。
    
3.  先点 **Save** 写入磁盘，再点 **Apply** 重启网关生效。

## **3. 接入消息渠道**

配置好模型后，就可以把 OpenClaw 挂到常用的聊天软件上。以下按渠道分别说明，按需选择即可，互不影响。

### 钉钉

**① 创建应用并拿到凭证**

1.  登录[钉钉开放平台](https://open-dev.dingtalk.com/)，选择一个有开发者权限的组织（没有就新建一个组织）。
    
2.  顶部菜单进入**应用** → **创建应用**，填写名称（如"AI 助手"）和描述后保存。
    
3.  在**添加应用能力**中加入**机器人**，开启机器人开关、填好必填项，**消息接收模式**保持默认的 **Stream 模式**，点击**发布**。
    
4.  打开**凭证与基础信息**，记下 Client ID 与 Client Secret。
    
5.  进入**版本管理与发布**，新建版本、设定可见范围，保存并发布。
    

**② 安装钉钉插件**

```
openclaw plugins install @soimy/dingtalk
```

装好后用 `openclaw plugins list` 确认 `dingtalk` 处于 `loaded` 状态。

**③ 写入渠道配置**

在 `~/.openclaw/openclaw.json` 中补充 `channels` 与 `plugins.allow`，把 `YOUR_DINGTALK_APPKEY`、`YOUR_DINGTALK_APPSECRET` 换成上一步的凭证。这部分是追加到现有配置里，别动已有的 `models`、`agents`：

```
{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_DINGTALK_APPKEY",
      "clientSecret": "YOUR_DINGTALK_APPSECRET",
      "robotCode": "YOUR_DINGTALK_APPKEY",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown"
    }
  },
  "plugins": {
    "allow": ["dingtalk"],
    "entries": {
      "dingtalk": {
        "enabled": true
      }
    }
  }
}
```

> 示例把 `dmPolicy`、`groupPolicy` 都设成了 `open`，方便自测；正式使用建议改为 `allowlist`，用白名单限定可访问的人和群。

**④ 重启并验证**

```
openclaw gateway restart
```

执行 `openclaw status`，Channels 一栏的 DingTalk 显示 `ON` 且 `OK - configured` 即表示就绪，随后在钉钉群里 @机器人发条消息试试。

### 飞书

**① 创建飞书应用**

1.  打开[飞书开放平台](https://open.feishu.cn/app)，**创建企业自建应用**，填写名称与描述后创建。
    
2.  在**凭证与基础信息**里复制 **App ID**（形如 `cli_xxx`）和 **App Secret**。
    
3.  进入**权限管理** → **批量导入/导出权限**，粘贴下面的权限清单，确认新增后申请开通：
    

```
{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}
```

4.  在应用能力里找到**机器人**卡片并**配置**。
    
5.  设置事件订阅：**事件与回调** → **订阅方式**选**使用长连接接收事件**并保存，再**添加事件**搜索 `im.message.receive_v1` 确认加入。
    
6.  在**版本管理与发布**创建版本，填好版本号与说明，提交审核并发布。
    

**② 配置飞书机器人**

执行交互式命令并按提示填写：

```
openclaw channels add
```

依次选择 **Feishu**、输入 **App ID**、输入 **App Secret**。完成后重启网关。私聊机器人时它会回一条带**配对码**的消息，把最后一行复制到 OpenClaw 对话中发送即可完成配对。

**③ 重启并验证**

```
openclaw gateway restart
```

执行 `openclaw status`，Channels 中 Feishu 显示 `ON` 且 `OK` 即可，在飞书里发消息测试。

### 微信

> 请确保微信客户端版本不低于 8.0.70。

**① 安装微信插件**

```
npx -y @tencent-weixin/openclaw-weixin-cli@latest install
```

命令执行后终端会打印二维码，用微信扫码完成绑定；绑定成功后会自动弹出 ClawBot 聊天窗口。随后用 `openclaw plugins list` 确认 `openclaw-weixin` 为 `loaded`。

**② 重启并验证**

```
openclaw gateway restart
```

在微信里找到 ClawBot 发消息测试即可。

### QQ

**① 安装 QQ 插件**

```
openclaw plugins install @sliverp/qqbot
```

用 `openclaw plugins list` 确认 `qqbot` 为 `loaded`。

**② 创建 QQ 机器人**

1.  在 [QQ 开放平台](https://q.qq.com/#/) 注册并登录开发者账号。
    
2.  通过 [OpenClaw 专属页面](https://q.qq.com/qqbot/openclaw/index.html) 创建机器人，获取 AppID 和 AppSecret。
    
    > AppSecret 不支持明文回看，再次查看会强制重置，请创建时妥善保存。
    

**③ 写入渠道配置**

在 `~/.openclaw/openclaw.json` 中追加以下内容，替换 `YOUR_APP_ID`、`YOUR_APP_SECRET`，同样注意不要覆盖已有的 `models`、`agents`：

```
{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "clientSecret": "YOUR_APP_SECRET",
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  },
  "plugins": {
    "allow": ["qqbot"],
    "entries": {
      "qqbot": {
        "enabled": true,
        "config": {}
      }
    }
  }
}
```

`dmPolicy: open` 表示放开私聊、`allowFrom: ["*"]` 表示放开所有用户，适合自测；正式使用请按需收窄范围。改完重启网关，再到 QQ 里给机器人发消息测试：

```
openclaw gateway restart
```

## **4. 常用命令**

进入对话后可随时使用以下指令：

| 命令 | 作用 | 示例 |
| --- | --- | --- |
| /help | 查看命令速览 | /help |
| /status | 查看模型、会话、网关等状态 | /status |
| /model <模型名> | 切换当前会话的模型 | /model claude-opus-4-8 |
| /new | 开启新会话 | /new |
| /compact | 压缩历史、释放上下文空间 | /compact |
| /think <级别> | 调整推理深度（off / low / medium / high） | /think high |
| /skills | 列出可用 Skill | /skills |

## **常见问题**

### 怎么查看当前配置了哪些模型？

执行 `openclaw tui` 进入终端界面后输入 `/model`，即可浏览模型列表；回车选中、Esc 退出。

### 报错 "HTTP 401: Incorrect API key provided." 或 "No API key found for provider xxx"

多半是 Key 或缓存的问题：

1.  确认 API Key 来自 UModelverse 平台、复制完整无空格、且订阅有效，没有写错或过期。
    
2.  若是历史缓存导致，删除 `~/.openclaw/agents/main/agent/models.json` 里的 `providers` 字段后重启 OpenClaw。
    

### 已经接了渠道，怎么安全地新增模型而不弄丢原配置？

关键是**别整份替换**，只做局部修改：

-   OpenClaw 还能正常对话时，直接在对话里让它帮你合并配置。
    
-   无法对话时，手动编辑 `~/.openclaw/openclaw.json`，只改要变的字段，其余原样保留。
    

改完重启网关；如果旧会话变得无法对话，新开一个会话即可。

### 报错 device identity required

完整报错形如：

```
... code=1008 reason=device identity required
```

**成因：** 连接网关时缺少设备身份，常见于首次访问尚未配对、浏览器缓存被清、或重装升级后 `~/.openclaw/identity/` 下密钥丢失。

**处理：** 先放行当前设备并重新生成访问地址：

```
openclaw devices approve --latest
openclaw dashboard --no-open
```

仍不行就清掉异常设备记录再试：

```
openclaw devices clear --pending --yes
openclaw dashboard --no-open
```

最后用 `openclaw devices list` 确认设备进入 Paired 列表即为正常。