首页 产品 为什么选 OCTO 解决方案 文档 关于
文档中心 / 用户手册 / Bot 开发者入门
← 返回文档中心

Bot 开发者入门

OCTO 文档中心 · 用户手册
  • 06-api-integration/OCTO-Bot-API接入快速上手指南-v0.1.md（v0.1，鉴权/端点/三种接入路径）
  • 06-api-integration/Bot-API概览.md v0.1（端点分组骨架）
  • 02-architecture/OpenClaw-Agent-Bot-OCTO关系说明.md v1.0（Agent→插件→Bot→OCTO 链路与角色对照）
  • 02-architecture/OCTO总体架构.md v1.0（请求5步、WuKongIM 边界）
  • 03-deployment-ops/OCTO部署形态总览.md v1.0（端口/反代/必选可选依赖）
  • source-repos/openclaw-channel-octo/src/api-fetch.ts（botToken Bearer、register/heartbeat/sendMessage/events 调用）
  • source-repos/octo-server/modules/bot_api/bot_api.go（路由注册行）
  • 00-inbox/product-bot-answers/2026-09-19-第一批核心问题回答.md（Q5 Bot/Agent/插件关系）

Bot 开发者接入前准备 v0.1

状态：`draft` / v0.1。confidence:medium。

面向第一次在 OCTO 上开发 Bot/Agent 的开发者，讲"动手前要知道什么"，不讲具体代码实现（代码层见 `06-api-integration/OCTO-Bot-API接入快速上手指南-v0.1.md`）。

本文所有"待确认"项已用引用块标注；这些信息等 061 三批 P0 提问稿（API与鉴权/版本与命名/部署架构）被产品管家回答后回填。本文不替代官方 API 文档，不作为客户交付手册。

一、前置条件：动手前你需要准备什么

1.1 部署与网络

  • 可用的 OCTO 部署：你需要能访问到一套 OCTO 服务。私有化默认入口：HTTP http://:28080、HTTPS https://:28443；K8s/反代环境下以实际 ingress 地址为准。（来源：049 部署形态总览；octo-deployment docker README）
  • 网络可达性：你的 Bot 程序所在机器必须能访问 OCTO 的 HTTP 入口；如果走 WebSocket 长连接或接收 webhook 回调，还要考虑反向的网络可达性（OCTO 能否回调到你的 Bot，取决于你选长轮询还是 webhook 模式）。
  • 客户端测试环境：建议你自己有一个 Web 端账号能登录 OCTO，用来验证 Bot 发出的消息/卡片在真实客户端上的呈现。

1.2 账号与权限

  • OCTO 账号：你自己需要一个能登录 OCTO 客户端（Web/PC）的普通用户账号，用来加 Bot 为好友、把 Bot 拉进群、测试消息收发。
  • 管理员配合：创建 Bot 身份、颁发 bot_token 需要管理员权限。

⚠️ 待确认：

- Bot 创建/管理的具体入口是在 octo-admin 管理后台还是普通客户端的"Bot 管理/BotFather"页面？octo-server 源码存在 `modules/botfather`，推断类似 Telegram BotFather 的开发者入口，但具体 UI 路径和角色要求（是否必须 superAdmin，还是普通开发者也可自助创建）需产品管家确认。

- 是否需要额外签署什么审批/备案流程（企业私有化场景常见要求），本文不假设。

1.3 技术栈选择

路径 适用场景 技术要求
① 通过 openclaw-channel-octo 插件接入 OpenClaw Agent（推荐） 要做 AI Agent（带 SOUL/MEMORY/工具/技能的智能助手，如知识库 Bot、客服 Bot） Node.js + OpenClaw 运行时；插件自动处理鉴权/心跳/事件轮询/卡片协商
② 直接调 REST API（/v1/bot/\*） 要做轻量 Bot（通知推送、简单命令响应），不跑 Agent 任意 HTTP 客户端（curl/Python/Node/Go 均可）；自己处理 token 保活和事件轮询
③ incoming webhook 入站 只需要把第三方系统的通知单向推到 OCTO 群，不需要收消息 任意 HTTP 客户端；不需要长连接；webhook URL 由管理员/群配置生成

⚠️ 待确认：路径③ incoming webhook 的具体配置入口、URL 格式、鉴权方式、支持的消息类型——源码 `modules/webhook/incomingwebhook/` 存在，但具体使用文档未在当前阅读范围。

1.4 能力边界预期（先想清楚再动手）

  1. 只发消息（通知类）：只需要调 `sendMessage`，不用处理事件轮询，最简单。
  2. 收消息 + 回消息（命令响应类）：需要 `/v1/bot/events` 长轮询拉取消息事件，加 ACK 去重。
  3. 发交互卡片（带按钮/表单）：需要先调 `/v1/bot/card/profile` 查询服务端 manifest，理解卡片三模式（raw/card/template）、template_ref XOR、render_profile 服务端覆盖等规则（详见 `售前交付/openclaw-channel-octo卡片能力正式口径-v1.0.md`）。
  4. 带 AI 能力的 Agent：建议走路径①，不要自己在 REST 层重造 Agent 运行时。

二、核心概念速览：3 分钟搞懂几个词

概念 一句话解释 类比
OCTO 平台 企业 IM+AI 协作平台本体（octo-server + WuKongIM + MySQL/Redis/MinIO 等） 写字楼
Bot OCTO 里的一个"机器人工号"（uid 唯一标识），是程序在平台里收发消息的身份 员工工牌
Agent 跑在 OpenClaw 运行时里的智能体（有 SOUL/MEMORY/工具/技能），通过插件映射为一个 Bot 员工本人
openclaw-channel-octo OpenClaw 的一个 channel 插件，负责把 Agent 对接到 OCTO Bot API 办公室到写字楼的专线
App（Bot App） Bot 承载的应用/能力集合（源码存在 modules/app_bot）；一个 Bot 可挂一个或多个 App 能力 员工的岗位/职责
Group（群） OCTO 里多人会话的基本单位，有唯一 group_no 会议室
Thread（子区/话题） 群下的子讨论区，用 group_no____short_id（四下划线）标识，避免在主群刷屏 会议室里的分会场
bot_token Bot 的主鉴权凭证，调 /v1/bot/* 时放 Authorization: Bearer 工牌密码
IM token 插件通过 /v1/bot/register 刷出来的 IM 层短 token，由插件自动维护，开发者无需手动管 临时门禁卡

核心来源：02-architecture/OpenClaw-Agent-Bot-OCTO关系说明.md 角色对照表；modules/bot_api 路由；api-fetch.ts register/heartbeat 实现。

⚠️ 待确认：

- "App"概念是否对 Bot 开发者开放、App 与 Bot 的绑定流程、是否需要上架/审核——源码 `modules/app_bot` 存在但未精读。

- Bot 是否同时支持多 App、App 的权限隔离模型，需产品管家确认。

三、鉴权机制：你会拿到哪些 token、怎么用

3.1 bot_token（主凭证）

  • 用途：调用几乎所有 /v1/bot/* REST 端点的鉴权凭证。
  • 形式：放在 HTTP Header：Authorization: Bearer 。（源码直接证据：openclaw-channel-octo api-fetch.ts:254）
  • 生命周期：

⚠️ 待确认：bot_token 的具体形态（长度/前缀/JWT or opaque）、有效期（长期有效还是会过期）、吊销/重置流程、是否支持一次颁发多个 token（读写分离/环境分离）——待 061-P0-API与鉴权 Q2 产品管家回答。

3.2 IM token（插件自动维护）

  • 是什么：插件启动时调 POST /v1/bot/register 会返回一个 IM 层 token，用于和 WuKongIM 长连接鉴权。
  • 你需要管吗：走路径①（插件）时完全不用关心，插件自动 register、自动刷新、自动 heartbeat；走路径②（直接 REST）时主要操作 REST 端点，一般也不直接接触 IM token，除非你要自己实现长连接。
  • heartbeat 机制：插件会周期性调 ANY /v1/bot/heartbeat（限流豁免，2026-08-05 事故驱动设计）保活。

3.3 OBO（On-Behalf-Of）用户授权

  • 是什么：一种"Bot 代表某个用户行事"的授权机制，端点 /v1/bot/obo/grant。
  • 典型场景：用户点了 Bot 发的卡片按钮，Bot 以该用户身份完成某个操作（比如"以我的名义在群里发一条消息"）。

⚠️ 待确认：OBO 的完整授权流程、token 形态、有效期、权限边界——待 Q2 回答后补。

3.4 权限模型：Bot 在群里能干什么

  • Bot 加入群后身份是群成员（不是超管），发消息/收消息需要在群里；
  • Bot 能否跨群发消息、拉所有群列表、踢人、改群公告：源码 bot_api.go 已见 GET /v1/bot/groups 和 GET /v1/bot/groups/:group_no/members 等只读端点，写操作端点（POST/PUT/DELETE 创建群/踢人/改公告）是否开放，待 061-P0-API与鉴权 Q4 确认。
  • 硬边界（源码已验证）：
  • 只有持 bot_token 的 Bot 身份能发卡片；普通用户 API 绝对拒卡（046 nonBot 入站验证）。
  • legacy incoming webhook 有独立鉴权路径，和 bot_token 不同。

四、接入最小路径：从 0 到发第一条消息

以下路径为基于源码骨架和产品管家口径的合理推断；具体管理后台 UI 路径和 API URL 前缀待确认，本文给出"步骤"而非"可复制命令"。可运行的 curl 示例见 `06-api-integration/OCTO-Bot-API接入快速上手指南-v0.1.md`（用 `{{apiBase}}` 占位符）。

Step 1：申请并创建 Bot

  1. 联系 OCTO 管理员，在管理后台 / BotFather 入口创建一个新 Bot；
  2. 拿到 `botToken`（字符串，具体展示格式待确认）；
  3. 把 Bot 加为你测试群的成员，或者先和 Bot 开一对一私聊。

⚠️ 待确认：自助申请入口、是否需要审核、Bot 名字/头像/简介配置规则。

Step 2：建立连接（路径二选一）

  • 走路径②直接 REST：不用建长连接，所有收发都走 HTTPS，每次请求带 Authorization: Bearer 。
  • 走路径①插件：在 OpenClaw 配置里填 botToken 和 apiBase，插件启动后会自动调 /v1/bot/register + /v1/bot/heartbeat 完成接入。
  • 走路径③ webhook：在群/Bot 配置里生成 incoming webhook URL，直接 POST 到该 URL。

Step 3：发第一条消息

  • 端点（源码已见）：POST /v1/bot/sendMessage
  • 最小请求体骨架（字段级硬校验事实来自 044A/044C schema 验证）：必须包含 channel 目标、消息类型、内容；发卡片有 card/template 专属字段，raw 与 template 互斥（XOR）。

⚠️ 待确认：

- `channel_type` 常量字符串（群/私聊/Thread 分别是什么值，例如 `"group"`/`"direct"`/`"thread"`）；

- 响应字段（message_id/时间戳等）；

- 完整 URL 前缀是否是 `/v1/bot/sendMessage` 还是 `/api/v1/bot/sendMessage`（nginx 反代前缀见 049 部署形态，最终以官方 API 文档为准）。

Step 4：收第一条消息

  • 机制：走路径①/②时，Bot 通过 POST /v1/bot/events 长轮询拉取事件（消息、卡片回调、成员变更等）；处理完要调 POST /v1/bot/events/:event_id/ack 确认，服务端保证 at-least-once 投递（可能重复，Bot 侧要做幂等）。
  • 不支持 webhook 被动推送（截至当前源码阅读范围）：OCTO Bot API 目前只支持长轮询拉事件，不支持把消息主动 POST 到 Bot 指定的回调 URL（这是和 Slack/飞书 Bot 模型的一个重要区别）。

⚠️ 待确认：events 长轮询的超时参数、cursor 机制、事件类型完整清单（消息/card_action/成员变更/群变更/入群邀请…）——待 061-P0-API与鉴权 Q3 回答。

Step 5：验证与调试

  • 用你自己的普通用户账号在群里 @Bot 发一句话，看 Bot 是否收到事件、是否能回消息；
  • 发卡片前先调 GET /v1/bot/card/profile 查服务端 manifest，确认哪些卡片能力/limits 被启用（避免客户端不支持时卡片被拒）。

五、常见坑 / 注意事项（基于源码已验证事实）

  1. 不要以为用户身份能发卡片——只有 bot_token 才能发卡片；普通用户 token 发卡片 payload 会被服务端拒绝（046）。
  2. raw 和 template 不能同时传——`POST /v1/bot/sendMessage` 的 payload 中，raw 内容与 template_ref 是 XOR 关系，同时传会被拒（044A schema）。
  3. 不要硬编码 limits 数值——卡片渲染预算、消息长度、文件大小等 limits 以服务端运行时 manifest 为准，客户端/插件不要硬写数值（卡片正式口径 v1.0）。
  4. render_profile 由服务端决定——Bot 传的 render_profile 字段可能被服务端覆盖/覆盖校验，不要以为自己传什么就用什么（044C v0.4）。
  5. register 和 heartbeat 必须豁免限流——这两个路径不能被你自己实现的限流器挡住，否则 2026-08-05 事故会重演（同 IP Bot 互饿死锁）。
  6. 事件要 ACK，且要做幂等——服务端 at-least-once 投递，你处理完一定要调 `/v1/bot/events/:event_id/ack`；你的业务逻辑要能处理重复投递。
  7. 本地开关已废弃——不要试图通过本地配置关闭/开启卡片能力，全部以服务端 `/v1/bot/card/profile` 返回的 manifest 为准（卡片正式口径 v1.0）。
  8. 版本别乱猜——octo-web 用日期版本号、server 用 SemVer、插件用 SemVer，版本之间没有同步关系；生产锁版本请按官方兼容矩阵（待确认）。

六、已知待确认项汇总（等 061 提问稿回答回填）

⚠️ 以下信息目前在源码/已有产品管家回答中找不到确定答案，已纳入 061 三批 P0 提问稿，产品管家回答后回填本文。开发者对接时如遇这些问题，请先联系内部 API 负责人确认，不要按本文猜测实现。

# 待确认项 对应 061 问题
K1 Bot 创建/管理入口（admin 后台 vs BotFather）、token 申请流程、权限要求 P0-API与鉴权 Q2
K2 bot_token 形态、生命周期、吊销方式、限流阈值 P0-API与鉴权 Q2
K3 完整 API 分类清单（Bot/Admin/Open/User-facing）与端点前缀 P0-API与鉴权 Q1
K4 sendMessage payload 字段完整 schema、channel_type 常量、响应格式 P0-API与鉴权 Q3
K5 是否支持 Webhook 被动推送（vs 仅长轮询） P0-API与鉴权 Q3
K6 群/Thread/成员管理 API 的写操作能力（建群/踢人/改公告）开放范围 P0-API与鉴权 Q4
K7 各组件版本兼容矩阵（server/web/plugin/mobile/WuKongIM 推荐搭配版本） P0-版本与命名 Q1
K8 octo-server 最新 release tag（生产锁版本用具体 tag 还是 latest） P0-版本与命名 Q3
K9 消息类型完整清单与每种 content 格式 P0-API与鉴权 Q3
K10 Bot 文件上传大小/类型限制（以服务端 manifest 为准，但需要官方确认如何查询） P0-API与鉴权 Q4
K11 App 概念（app_bot 模块）对开发者的开放范围 P0-API与鉴权 Q1
K12 incoming webhook 配置入口、URL 格式、消息类型支持 下一批 P1 提问

七、下一步阅读

  • 写代码前：06-api-integration/OCTO-Bot-API接入快速上手指南-v0.1.md v0.1 —— 三种接入路径的代码骨架、curl 示例、11 项待确认清单。
  • 理解概念：02-architecture/OpenClaw-Agent-Bot-OCTO关系说明.md v1.0 —— Agent/Bot/插件/平台的完整关系图与口径红线。
  • 发卡片前必看：售前交付/openclaw-channel-octo卡片能力正式口径-v1.0.md v1.0 —— 卡片三模式、能力协商、渲染边界、降级策略。
  • 部署/网络问题：03-deployment-ops/OCTO部署形态总览.md v1.0 —— 端口、反代、必选/可选依赖。
  • 端点全貌：06-api-integration/Bot-API概览.md v0.1 —— 9 组 40+ 端点分组导航骨架。

v0.1 骨架边界说明

  • 本文定位"接入前准备"，不是 API 参考文档；字段级 schema、错误码、SDK 信息留待 061 回答后升 v0.2。
  • 所有 UI 操作路径、具体 URL 前缀、具体数值均标"待确认"，不给编造的可运行 curl/截图。
  • 卡片能力细节不展开（见卡片正式口径 v1.0）；本文只提示"发卡片前先查 profile"。
  • 管理员如何在后台创建 Bot、如何配置 openclaw-channel-octo 插件等操作类内容，后续在 管理员手册.md 中补齐。
← 返回文档中心