Channels

channel 让 OpenSquilla 可以从消息平台运行，同时与 CLI 和 Web UI 共享同一套 agent 运行时。当你希望同一个 agent 能从 Slack、Telegram、Feishu/Lark、Discord、 DingTalk、WeCom、Matrix、QQ 或其他受支持的适配器进行回复时，请使用 channel。

支持的 channel 类型

查看本地安装：

opensquilla channels types
opensquilla channels types --json
opensquilla channels describe feishu

该构建提供以下 channel 系列。所有公开的厂商适配器目前均为 YELLOW-experimental；可用并不意味着已达到与该 provider 完整 API 对等的功能。

本地 channels describe <type> 的输出是必填字段、密钥、扩展字段以及重启行为的权威来源。

配置流程

交互式配置：

opensquilla configure channels

显式添加一个 channel：

opensquilla channels add telegram --name personal

按需添加 provider 相关字段。Slack 支持两种模式：

# Slack Socket Mode：出站 websocket，无需公网 URL。
opensquilla channels add slack --name team \
  --field connection_mode=socket \
  --field app_token=xapp-... \
  --token xoxb-...

# Slack Events API webhook：需要公网 Request URL 以及 signing secret。
opensquilla channels add slack --name team-webhook \
  --field connection_mode=webhook \
  --field signing_secret=... \
  --token xoxb-...

配置修改后请重启 gateway 进程：

opensquilla gateway restart

验证运行时连接：

opensquilla channels status
opensquilla channels status personal --json

保存 channel 证明配置已被写入。channels status 则证明运行中的 gateway 是否成功 加载并连接了该 channel；status 不会向 provider 发起出站请求。

运行时安全与投递契约

channel 运行时使用同一个共享边界来处理 provider 身份、访问策略、持久化与投递诊断。 这些保证适用于已实现的运行时，而非适配器未暴露的 provider 特性。

认证准入

正常的 provider 入站会记录不可变的溯源信息：provider、账号、transport、验证方式、 原生事件 ID 以及经过认证的主体。Webhook 签名或 token 由适配器校验；SDK 与 gateway session 会被相应标记。遗留的或直接构造的消息会明确保持为 legacy_unverified， 不会悄然获得受信任状态。

dispatcher 会在创建 session、处理命令、解析审批、下载附件或改动 transcript 之前 做出一次准入决策。它会拒绝认证主体与发送者不匹配的情况，应用 DM/群组与允许名单 策略，并在适配器没有 mention hook 时默认将群组 mention 检查设为拒绝。这是安全边界； provider 元数据本身并不构成授权决策。

经过认证的私信默认 dm_access = "pairing"。首个未知发送者会收到一条固定通知， 其中包含一个简短的请求码；OpenSquilla 会存储该 provider 身份与访问状态，绝不存储 被拒绝的消息内容。运维者可以从 channel 的 Pairings 标签页批准或撤销该身份。 dm_access = "open" 会刻意恢复此前的公开 DM 行为，而 dm_access = "allowlist" 则需要 allowed_senders。

群组会话默认 group_session_scope = "per_sender"，因此同一房间内的两个人不会共享 transcript 上下文。仅当房间确实用于协作时才使用 shared_room。busy_input_mode 控制在某个 turn 运行期间到达的消息：followup、queue、steer 或 interrupt。 运行时会校验所选模式，并保持其有界的待处理队列策略。

持久化入站与出站意图

受管 channel 使用 OpenSquilla 状态目录下的 channel_delivery.sqlite。该数据库采用 SQLite WAL 模式、完整同步提交，并在平台支持时使用仅所有者可访问的文件权限。

• 带有原生事件 ID 的规范化入站事件会在进入 dispatcher 队列之前先提交。处理会被 原子地认领，被中断的认领会在重启后回到 accepted，终态处置会保留以供诊断。 没有稳定 provider ID 的事件无法获得这种持久化去重保证。
• 同步入队事件的 HTTP webhook 处理器会在返回成功之前提交该事件。SDK 与 socket 协议可能需要更早的协议级 ACK；它们在 provider 侧的重放行为仍取决于具体 transport。
• 声明的出站变更会先持久化一个投递 ID、目标、内容哈希以及经过净化的意图。这涵盖 普通消息以及受支持的文件上传、编辑、删除、reaction 与流式操作；通过普通消息信封 发送的卡片走的是同一条路径。已确认的结果会存储 provider 的消息/文件 ID。返回无回执 的遗留适配器会标记为 sent_unconfirmed；异常情况会标记为 unknown，因为重试一个 可能已投递的请求会造成重复。
• outbox 是意图与回执的账本，而非盲目自动重发的 worker。公开 channel 变更接口之外的 provider 专有管理/内容 API 保留各自的操作契约。

投递计数、最久的待处理记录、未知结果以及租约状态都会包含在 channel status 诊断中。

每个账号仅一条活动 transport

在启动适配器之前，manager 会在同一状态数据库中为该 provider 系列及派生的账号身份 获取一个可续期的租约。该租约携带一个单调递增的 fencing token，会在适配器运行期间 续期，并暴露在健康诊断中。使用同一状态数据库的第二个本地 gateway 无法在租约存活时 启动相同账号的 transport。续期失败会将适配器标记为断开并停止它。

这是一个基于 SQLite 的进程/账号所有权守卫，而非分布式多区域租约服务。

能力证据与实时探测

channels status 返回三个独立的视图：

• 面向底层操作的类型化能力 profile；
• 一份涵盖 chat、files、media、attachments、threads、cards、docs、drive、wiki、 permissions 与 scopes 的 provider manifest；
• 每项声明能力的证据以及适配器的成熟度层级。

方法支撑（method-backed）证据表示存在可调用的实现。声明式（declaration）证据涵盖 诸如群组拓扑之类的语义行为。二者都不是端到端的 provider 认证：当前的证明状态为 unverified，这也是公开适配器仍处于 experimental 的原因。

配置 UI 可以运行一次显式的、admin 作用域的实时探测。Slack、Telegram、Discord、 Feishu、DingTalk 以及 WeCom 企业应用模式目前实现了凭据/网络探测。DingTalk 探测会 请求临时的 Stream 连接元数据，但不会打开 websocket 或发送业务数据。Matrix、QQ 以及 WeCom AI Bot websocket 模式会报告 unsupported，而不会再打开第二个入站连接。 verified 探测只确认它所运行的那项检查；它并不能证明回调投递、每一项权限 scope、 出站投递、限流行为或功能完整性。

对于发版认证，请使用仅依赖环境变量的 CLI runner。它会构造一个临时适配器，且绝不会 把所提供的凭据写入 channel 配置或证据输出：

export OPENSQUILLA_CHANNEL_CERT_FEISHU_APP_ID='...'
export OPENSQUILLA_CHANNEL_CERT_FEISHU_APP_SECRET='...'
export OPENSQUILLA_CHANNEL_CERT_DINGTALK_CLIENT_ID='...'
export OPENSQUILLA_CHANNEL_CERT_DINGTALK_CLIENT_SECRET='...'
export OPENSQUILLA_CHANNEL_CERT_TELEGRAM_TOKEN='...'
export OPENSQUILLA_CHANNEL_CERT_DISCORD_TOKEN='...'

opensquilla channels certify \
  --provider feishu \
  --provider dingtalk \
  --provider telegram \
  --provider discord \
  --json

请在本地 shell 或密钥管理器中使用新轮换的凭据；绝不要把它们粘贴到源码、命令历史、 issue 或测试夹具中。默认认证只执行凭据探测。真正的出站测试需要同时满足 --send-test-message、--allow-side-effects 以及一个显式的 --target provider=destination 三个条件。目标与凭据值会从结果证据中省略。QQ 目标 使用 c2c:<openid> 或 group:<group_openid>。DingTalk 出站认证会被报告为 unsupported， 直到某条入站消息提供其临时的 sessionWebhook。Telegram transport 启动被刻意排除在 安全探测之外，因为 polling/webhook 启动会改变 bot 的 webhook 状态。

Channel 审批

当某个 channel turn 触及受限工具时，OpenSquilla 会发送一个简短的审批码，而不是暴露 原始的审批 ID。该持久化绑定会记录发起的发送者、session、channel 条目、会话与线程。 解析必须来自同一个已准入的 session/会话及请求者；在可用时会使用经过认证的主体。

声明支持交互式卡片的适配器可以渲染按钮。每个适配器都有纯文本回退方式 /approve CODE 与 /deny CODE。一次成功的 channel 审批只会放行该受限操作，绝不会 启用会话级的提权模式。

管理 channel

opensquilla channels list
opensquilla channels enable <name>
opensquilla channels disable <name>
opensquilla channels edit <name>
opensquilla channels restart <name>
opensquilla channels logout <name>
opensquilla channels remove <name>

配置变更后请使用 gateway restart。仅对已加载的运行中适配器使用 channels restart <name>。

Slack 模式

Slack Socket Mode 使用出站 websocket，不需要公网 Request URL。它需要 bot token （xoxb-...）以及一个保存为 app_token 的 app-level token（xapp-...）。

Slack webhook 模式使用 Events API Request URL。它需要 bot token 加上 signing_secret， 且 gateway 必须可被 Slack 访问。

当适配器应回复来源会话时，将 slack_channel_id 留空。仅当你希望设置一个默认回退 channel 时才设置它。当回复应保留在 Slack 线程中时，启用 reply_in_thread。

Webhook channel

Slack webhook 模式和 WeCom 需要一个公网可达、provider 可访问的 URL。Feishu 与 Telegram 可能也需要，视模式而定。

对于公网 channel：

• 将 gateway 绑定到可达的网络接口；
• 将其置于可信的反向代理或隧道之后；
• 配置鉴权；
• 仔细核对 provider 的回调 URL 与密钥。

受控网络中的绑定示例：

opensquilla gateway run --listen 0.0.0.0 --port 18791

不要将未鉴权的 gateway 暴露到公网。

Provider 边界与官方参考

以下限制是有意设定的发版边界，并不是对各厂商所支持全部能力的描述。

附件与 artifact

各 channel 适配器在附件与 artifact 投递行为上可能有所不同。OpenSquilla 通过同一套 运行时路径标准化 agent 执行，但平台 transport 仍会控制文件大小限制、消息线程以及 上传/下载能力。

当某个 channel 无法直接投递大体积 artifact 时，使用 Web UI 的 artifact 卡片或 session 导出作为恢复路径。

排障

如果某个 channel 没有响应：

1. 检查配置项：

   opensquilla channels list

2. 检查运行时状态：

   opensquilla channels status <name> --json

3. 配置变更后重启 gateway 进程：

   opensquilla gateway restart

4. 对 webhook channel，确认公网 URL、provider 回调密钥以及 gateway 鉴权/网络边界。

5. 把 sent_unconfirmed 或 unknown 的 outbox 条目视为需要运维者审查的情况。 不要盲目重试它们。

文档索引 · 产品指南 · 改进本页 · 反馈文档问题