OpenClaw 使用指南

步骤 1：安装 OpenClaw

前置要求 需要 Node.js 22 或更高版本。验证方式：node --version

🍎 macOS / 🐧 Linux

方法一：官方安装脚本（推荐） 自动检测环境并安装所有依赖：

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

方法二：npm

npm install -g openclaw@latest

方法三：pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g

⊞ Windows

方法一：PowerShell 安装脚本（推荐）

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

方法二：npm（CMD / PowerShell 均可）

npm install -g openclaw@latest

方法三：pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g

初始化

安装完成后，运行初始化向导：

openclaw onboard --install-daemon

提示更多安装方式（Docker、从源码构建等）请参考 OpenClaw 官方文档。

步骤 2：获取 API 密钥

访问 智牛API 控制台，创建一个新的令牌：

点击「添加令牌」
名称：随便填写，方便自己区分即可
令牌分组：根据实际需要选择，分组有详细描述（必填项，不能留空）
额度建议：设置为无限额度

创建成功后，复制令牌备用。

步骤 3：配置 OpenClaw

配置文件位置

系统	路径
macOS / Linux	`~/.openclaw/openclaw.json`
Windows	`%USERPROFILE%\.openclaw\openclaw.json`

注意如果文件不存在，可以手动创建。首次运行 openclaw doctor 也会自动生成默认配置。

智牛API 配置示例

在 openclaw.json 中添加或修改以下内容：

{
  "meta": {
    "lastTouchedVersion": "2026.2.3-1",
    "lastTouchedAt": "2026-02-06T10:08:26.053Z"
  },
  "wizard": {
    "lastRunAt": "2026-02-06T10:06:14.214Z",
    "lastRunVersion": "2026.2.3-1",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  },
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "model": {
        "primary": "niuapi-claude/claude-opus-4-6"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "niuapi-claude": {
        "baseUrl": "https://niuapi.vip",
        "apiKey": "你的API密钥",
        "api": "anthropic-messages",
        "headers": {
          "User-Agent": "claude-cli/2.0.76 (external, cli)",
          "Authorization": "Bearer 你的API密钥"
        },
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "claude-opus-4-6"
          }
        ]
      },
      "niuapi-codex": {
        "baseUrl": "https://niuapi.vip/v1",
        "apiKey": "你的API密钥",
        "api": "openai-completions",
        "headers": {
          "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
          "Authorization": "Bearer 你的API密钥"
        },
        "models": [
          {
            "id": "gpt-5.2",
            "name": "gpt-5.2"
          }
        ]
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "保留默认值即可"
    },
    "mode": "local"
  }
}

重要提示

请将 "apiKey" 和 "headers.Authorization" 中的密钥替换为你在 智牛API 控制台 生成的 API 密钥
Authorization 的格式为 Bearer 你的API密钥（注意 Bearer 后有一个空格）
"gateway.auth.token" 保留默认生成的值即可，无需修改
"agents.defaults.model.primary" 用于设置默认使用的 AI 模型
格式为 provider名称/模型ID，例如：
niuapi-claude/claude-opus-4-6 或 niuapi-codex/gpt-5.2-codex

关键配置说明

models.providers.niuapi-claude — Claude 模型配置：

字段	值	说明
`baseUrl`	`https://niuapi.vip`	智牛 API 地址
`apiKey`	你的 API 密钥	从控制台获取
`api`	`anthropic-messages`	Anthropic 协议，用于 Claude 系列模型
`headers`	自定义请求头	详见下方说明
`models`	模型列表	需要使用的模型

models.providers.niuapi-codex — Codex(GPT系列) 模型配置：

字段	值	说明
`baseUrl`	`https://niuapi.vip/v1`	智牛 API 地址
`apiKey`	你的 API 密钥	从控制台获取
`api`	`openai-completions`	OpenAI 协议，用于 GPT/Codex 系列模型
`headers`	自定义请求头	详见下方说明
`models`	模型列表	需要使用的模型

切换默认模型 修改 agents.defaults.model.primary 即可切换默认模型：

使用 Claude："niuapi-claude/claude-opus-4-6"
使用 Codex："niuapi-codex/gpt-5.2"

格式为 provider名称/模型ID。 headers 配置说明 headers 用于自定义 HTTP 请求头：

User-Agent — 客户端标识，Claude 模型使用 claude-cli/...，Codex 模型使用 codex_cli_rs/...
Authorization — 认证头，值为 Bearer 你的API密钥（与 apiKey 填同一个密钥）

可用模型：访问 智牛API 模型广场 查看所有可用模型。如需添加更多模型，在对应 provider 的 models 数组中追加即可。

步骤 4：启动并验证

配置完成后，先运行诊断命令检查配置是否正确：

openclaw doctor

确认无误后，重启 gateway 使配置生效：

openclaw gateway restart

然后启动 TUI 界面验证配置是否正常：

openclaw tui

如果能正常对话，说明配置成功。

步骤 5：对接飞书（可选）

如果你希望通过飞书与 OpenClaw 交互，可以按照以下步骤完成对接。

5.1 登录飞书开放平台

访问 飞书开放平台，使用飞书账号登录
需要企业管理员或具备开发者权限的账号
进入「开发者后台」

5.2 创建企业自建应用

点击「创建企业自建应用」
填写应用信息：
- 应用名称（如 OpenClaw 助手）
- 应用描述（如 基于 OpenClaw 的 AI 智能助手）
- 应用图标（上传一张辨识度高的图标）
确认创建

5.3 获取应用凭证

进入刚创建的应用，点击左侧菜单「凭证与基础信息」
记录以下两个值（后续配置 OpenClaw 时需要）：
- App ID（格式类似 cli_a90f701cf9f99bd8）
- App Secret

安全提示 App Secret 是敏感信息，请妥善保管，不要泄露或提交到代码仓库。

5.4 添加机器人能力

在左侧菜单找到「应用能力」→「机器人」
点击开启机器人能力
可自定义机器人的名称和描述

5.5 配置应用权限

有两种方式，任选其一。

方式一：JSON 批量导入（推荐）

在左侧菜单点击「权限管理」
找到页面右上角的「批量导入」按钮
粘贴以下 JSON 并确认导入：

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

导入后，检查权限列表，如果有「申请」按钮的权限，点击逐一申请
企业自建应用的权限通常会自动通过审批

方式二：手动逐个开通

在「权限管理」中搜索并开通以下权限：

权限标识	说明	必要性
`im:message`	消息基础权限	必须
`im:message.p2p_msg:readonly`	接收用户私聊消息	必须
`im:message.group_at_msg:readonly`	接收群聊中 @机器人的消息	必须
`im:message:send_as_bot`	以机器人身份发送消息	必须
`im:message:readonly`	获取历史消息	必须
`im:resource`	消息中的资源（图片/文件）读取	必须
`im:chat.access_event.bot_p2p_chat:read`	机器人单聊事件访问	必须
`im:chat.members:bot_access`	获取机器人所在群的成员信息	必须
`cardkit:card:write`	发送交互卡片消息	必须
`application:application.app_message_stats.overview:readonly`	应用消息统计	推荐
`application:application:self_manage`	应用自管理	推荐
`application:bot.menu:write`	配置机器人菜单	推荐
`contact:user.employee_id:readonly`	读取用户工号	推荐
`aily:file:read`	AI 文件读取	推荐
`aily:file:write`	AI 文件写入	推荐
`corehr:file:download`	核心人事文件下载	可选
`event:ip_list`	事件 IP 白名单	可选

5.6 配置事件订阅

在左侧菜单找到「事件与回调」→「事件配置」
订阅方式选择「使用长连接接收事件」（推荐）
点击「添加事件」，搜索并添加 im.message.receive_v1（即「接收消息 v2.0」）

为什么推荐长连接模式？

不需要公网 IP、域名或内网穿透工具，本地即可调试
SDK 自动处理加密传输和鉴权，无需手动解密或验签
集成成本低，几分钟就能跑通

长连接限制

仅支持企业自建应用，商店应用不可用
消息必须在 3 秒内处理完成，否则触发超时重推
单应用最多 50 个连接
多客户端部署时为集群模式（非广播），只有一个客户端收到消息

5.7 创建版本并发布

必须先发布才能使用 飞书自建应用的权限和事件订阅配置，必须创建版本并发布后才会生效。未发布的应用在飞书客户端中搜索不到，也无法正常收发消息。长连接配置也需要应用发布后才能保存，否则会报错。

进入飞书开放平台「版本管理与发布」
点击「创建版本」，填写版本说明（如 OpenClaw AI 助手 v1.0）
设置应用的「可用范围」（至少添加自己或一个测试群）
点击「保存」→「申请发布」
等待企业管理员审核通过（企业自建应用通常审核较快）

注意每次权限变更或事件订阅修改后，都需要创建新版本并重新发布，否则变更不会生效。建议在所有配置完成后统一发布，减少反复提审。

5.8 在 OpenClaw 侧完成飞书配置

飞书应用发布成功后，再配置 OpenClaw 侧并启动网关：

# 1. 安装飞书插件
openclaw plugins install feishu-openclaw

# 2. 启用飞书通道并配置凭证
openclaw config set channels.feishu.enabled true --json
openclaw config set channels.feishu.appId "你的AppID"
openclaw config set channels.feishu.appSecret "你的AppSecret"

# 3. 重启网关使配置生效
openclaw gateway restart

# 4. 验证状态
openclaw status
# 预期输出：Feishu | ON | OK | configured

配置顺序很重要 正确顺序：先在飞书开放平台完成所有配置并发布应用 → 再配置 OpenClaw 并启动网关。飞书在建立 WebSocket 长连接时会验证应用凭证和发布状态，如果应用未发布或网关未启动，长连接将无法建立。

5.9 测试验证

发布审核通过且 OpenClaw 网关启动后，即可开始测试：

在飞书客户端搜索你的机器人名称，或将其添加到一个测试群
私聊机器人发送一条消息，确认能正常响应
在群聊中 @机器人发送消息，确认群聊场景也正常
测试图片、文件等富媒体消息的收发（如果需要）

飞书对接常见问题

问题	可能原因	解决方案
机器人无响应	网关未启动或凭证错误	运行 `openclaw status` 检查状态，确认 App ID / Secret 正确
群聊收不到消息	缺少 `im:message.group_at_msg:readonly` 权限	在权限管理中补充开通，重新发布版本
消息超时重复推送	处理时间超过 3 秒	优化处理逻辑，或检查 LLM API 响应速度
权限变更不生效	未重新发布应用版本	创建新版本并申请发布
长连接建立失败	应用未发布或网关未启动	确认飞书应用已发布且审核通过，然后确认 OpenClaw 网关已启动（`openclaw status`）

附录：配置字段说明

字段	说明	是否必填
`agents.defaults.model.primary`	默认使用的模型，格式：`provider/model-id`	是
`agents.defaults.maxConcurrent`	最大并发 agent 数	否（默认 4）
`agents.defaults.subagents.maxConcurrent`	最大并发子 agent 数	否（默认 8）
`agents.defaults.compaction.mode`	上下文压缩模式	否（默认 safeguard）
`models.mode`	模型合并模式	否（默认 merge）
`models.providers.<name>.baseUrl`	API 服务地址	是
`models.providers.<name>.apiKey`	API 密钥	是
`models.providers.<name>.api`	API 协议类型	是
`models.providers.<name>.headers`	自定义请求头	是
`models.providers.<name>.models`	可用模型列表	是
`gateway.mode`	gateway 运行模式	否（默认 local）
`gateway.auth.mode`	gateway 鉴权模式	否
`gateway.auth.token`	gateway 鉴权 token	否

开始使用

模型分组介绍

快速使用

API 参考

OpenClaw 使用指南

步骤 1：安装 OpenClaw

🍎 macOS / 🐧 Linux

⊞ Windows

初始化

步骤 2：获取 API 密钥

步骤 3：配置 OpenClaw

配置文件位置

智牛API 配置示例

关键配置说明

步骤 4：启动并验证

步骤 5：对接飞书（可选）

5.1 登录飞书开放平台

5.2 创建企业自建应用

5.3 获取应用凭证

5.4 添加机器人能力

5.5 配置应用权限

方式一：JSON 批量导入（推荐）

方式二：手动逐个开通

5.6 配置事件订阅

5.7 创建版本并发布

5.8 在 OpenClaw 侧完成飞书配置

5.9 测试验证

飞书对接常见问题

附录：配置字段说明

​步骤 1：安装 OpenClaw

​🍎 macOS / 🐧 Linux

​⊞ Windows

​初始化

​步骤 2：获取 API 密钥

​步骤 3：配置 OpenClaw

​配置文件位置

​智牛API 配置示例

​关键配置说明

​步骤 4：启动并验证

​步骤 5：对接飞书（可选）

​5.1 登录飞书开放平台

​5.2 创建企业自建应用

​5.3 获取应用凭证

​5.4 添加机器人能力

​5.5 配置应用权限

​方式一：JSON 批量导入（推荐）

​方式二：手动逐个开通

​5.6 配置事件订阅

​5.7 创建版本并发布

​5.8 在 OpenClaw 侧完成飞书配置

​5.9 测试验证

​飞书对接常见问题

​附录：配置字段说明

步骤 1：安装 OpenClaw

🍎 macOS / 🐧 Linux

⊞ Windows

初始化

步骤 2：获取 API 密钥

步骤 3：配置 OpenClaw

配置文件位置

智牛API 配置示例

关键配置说明

步骤 4：启动并验证

步骤 5：对接飞书（可选）

5.1 登录飞书开放平台

5.2 创建企业自建应用

5.3 获取应用凭证

5.4 添加机器人能力

5.5 配置应用权限

方式一：JSON 批量导入（推荐）

方式二：手动逐个开通

5.6 配置事件订阅

5.7 创建版本并发布

5.8 在 OpenClaw 侧完成飞书配置

5.9 测试验证

飞书对接常见问题

附录：配置字段说明