> ## Documentation Index > Fetch the complete documentation index at: https://docs.niuapi.vip/llms.txt > Use this file to discover all available pages before exploring further. # OpenClaw 使用指南 > OpenClaw 是一个开源（MIT 许可）的自托管网关，可将 WhatsApp、Telegram、Discord、iMessage 等聊天应用连接到 AI 编码代理，支持多代理路由、工具使用和会话记忆。更多信息请参考 OpenClaw 官网。本教程将指导你如何在 OpenClaw 中安装并配置 智牛 API。 ## **步骤 1：安装 OpenClaw** **前置要求** 需要 Node.js 22 或更高版本。验证方式：`node --version` ### **🍎 macOS / 🐧 Linux** **方法一：官方安装脚本（推荐）** 自动检测环境并安装所有依赖： ```text theme={null} curl -fsSL https://openclaw.ai/install.sh | bash ``` **方法二：npm** ```text theme={null} npm install -g openclaw@latest ``` **方法三：pnpm** ```text theme={null} pnpm add -g openclaw@latest pnpm approve-builds -g ``` ### **⊞ Windows** **方法一：PowerShell 安装脚本（推荐）** ```text theme={null} iwr -useb https://openclaw.ai/install.ps1 | iex ``` **方法二：npm（CMD / PowerShell 均可）** ```text theme={null} npm install -g openclaw@latest ``` **方法三：pnpm** ```text theme={null} pnpm add -g openclaw@latest pnpm approve-builds -g ``` ### **初始化** 安装完成后，运行初始化向导： ```text theme={null} openclaw onboard --install-daemon ``` **提示** 更多安装方式（Docker、从源码构建等）请参考 [**OpenClaw 官方文档**](https://docs.openclaw.ai/install)。 *** ## **步骤 2：获取 API 密钥** 访问 [**智牛API 控制台**](https://niuapi.vip/console/token)，创建一个新的令牌： * 点击「添加令牌」 * 名称：随便填写，方便自己区分即可 * **令牌分组：根据实际需要选择，分组有详细描述（必填项，不能留空）** * 额度建议：设置为无限额度 创建成功后，复制令牌备用。 *** ## **步骤 3：配置 OpenClaw** ### **配置文件位置** | **系统** | **路径** | | :------------ | :-------------------------------------- | | macOS / Linux | `~/.openclaw/openclaw.json` | | Windows | `%USERPROFILE%\.openclaw\openclaw.json` | **注意** 如果文件不存在，可以手动创建。首次运行 `openclaw doctor` 也会自动生成默认配置。 ### **智牛API 配置示例** 在 `openclaw.json` 中添加或修改以下内容： ```text theme={null} { "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 控制台**](https://niuapi.vip/console/token) 生成的 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 模型广场**](https://niuapi.vip/pricing) 查看所有可用模型。如需添加更多模型，在对应 provider 的 `models` 数组中追加即可。 *** ## **步骤 4：启动并验证** 配置完成后，先运行诊断命令检查配置是否正确： ```text theme={null} openclaw doctor ``` 确认无误后，重启 gateway 使配置生效： ```text theme={null} openclaw gateway restart ``` 然后启动 TUI 界面验证配置是否正常： ```text theme={null} openclaw tui ``` 如果能正常对话，说明配置成功。 *** ## **步骤 5：对接飞书（可选）** 如果你希望通过飞书与 OpenClaw 交互，可以按照以下步骤完成对接。 ### **5.1 登录飞书开放平台** 1. 访问 [**飞书开放平台**](https://open.feishu.cn/)，使用飞书账号登录 2. 需要企业管理员或具备开发者权限的账号 3. 进入「开发者后台」 ### **5.2 创建企业自建应用** 1. 点击「创建企业自建应用」 2. 填写应用信息： * 应用名称（如 `OpenClaw 助手`） * 应用描述（如 `基于 OpenClaw 的 AI 智能助手`） * 应用图标（上传一张辨识度高的图标） 3. 确认创建 ### **5.3 获取应用凭证** 1. 进入刚创建的应用，点击左侧菜单「凭证与基础信息」 2. 记录以下两个值（后续配置 OpenClaw 时需要）： * **App ID**（格式类似 `cli_a90f701cf9f99bd8`） * **App Secret** **安全提示** App Secret 是敏感信息，请妥善保管，不要泄露或提交到代码仓库。 ### **5.4 添加机器人能力** 1. 在左侧菜单找到「应用能力」→「机器人」 2. 点击开启机器人能力 3. 可自定义机器人的名称和描述 ### **5.5 配置应用权限** 有两种方式，任选其一。 #### **方式一：JSON 批量导入（推荐）** 1. 在左侧菜单点击「权限管理」 2. 找到页面右上角的「批量导入」按钮 3. 粘贴以下 JSON 并确认导入： ```text theme={null} { "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" ] } } ``` 4. 导入后，检查权限列表，如果有「申请」按钮的权限，点击逐一申请 5. 企业自建应用的权限通常会自动通过审批 #### **方式二：手动逐个开通** 在「权限管理」中搜索并开通以下权限： | **权限标识** | **说明** | **必要性** | | :------------------------------------------------------------ | :-------------- | :------ | | `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 配置事件订阅** 1. 在左侧菜单找到「事件与回调」→「事件配置」 2. 订阅方式选择「使用长连接接收事件」（推荐） 3. 点击「添加事件」，搜索并添加 `im.message.receive_v1`（即「接收消息 v2.0」） **为什么推荐长连接模式？** * 不需要公网 IP、域名或内网穿透工具，本地即可调试 * SDK 自动处理加密传输和鉴权，无需手动解密或验签 * 集成成本低，几分钟就能跑通 **长连接限制** * 仅支持企业自建应用，商店应用不可用 * 消息必须在 3 秒内处理完成，否则触发超时重推 * 单应用最多 50 个连接 * 多客户端部署时为集群模式（非广播），只有一个客户端收到消息 ### **5.7 创建版本并发布** **必须先发布才能使用** 飞书自建应用的权限和事件订阅配置，必须创建版本并发布后才会生效。未发布的应用在飞书客户端中搜索不到，也无法正常收发消息。长连接配置也需要应用发布后才能保存，否则会报错。 1. 进入飞书开放平台「版本管理与发布」 2. 点击「创建版本」，填写版本说明（如 `OpenClaw AI 助手 v1.0`） 3. 设置应用的「可用范围」（至少添加自己或一个测试群） 4. 点击「保存」→「申请发布」 5. 等待企业管理员审核通过（企业自建应用通常审核较快） **注意** 每次权限变更或事件订阅修改后，都需要创建新版本并重新发布，否则变更不会生效。建议在所有配置完成后统一发布，减少反复提审。 ### **5.8 在 OpenClaw 侧完成飞书配置** 飞书应用发布成功后，再配置 OpenClaw 侧并启动网关： ```text theme={null} # 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 网关启动后，即可开始测试： 1. 在飞书客户端搜索你的机器人名称，或将其添加到一个测试群 2. 私聊机器人发送一条消息，确认能正常响应 3. 在群聊中 @机器人 发送消息，确认群聊场景也正常 4. 测试图片、文件等富媒体消息的收发（如果需要） ### **飞书对接常见问题** | **问题** | **可能原因** | **解决方案** | | :------- | :--------------------------------------- | :---------------------------------------------------- | | 机器人无响应 | 网关未启动或凭证错误 | 运行 `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..baseUrl` | API 服务地址 | 是 | | `models.providers..apiKey` | API 密钥 | 是 | | `models.providers..api` | API 协议类型 | 是 | | `models.providers..headers` | 自定义请求头 | 是 | | `models.providers..models` | 可用模型列表 | 是 | | `gateway.mode` | gateway 运行模式 | 否（默认 local） | | `gateway.auth.mode` | gateway 鉴权模式 | 否 | | `gateway.auth.token` | gateway 鉴权 token | 否 |