PinableAgents

Appearance

概述 ​

Gateway 是 pinable-desktop 的多通道消息接入层，同时支持 Telegram、飞书（Feishu） 和 企业微信（WeCom） 三个通道。通过 Gateway，用户可以在这些 IM 平台中直接与 AI 交互，发起工作流执行，接收执行结果。

           ┌──────────────────────────────────────────┐
           │            pinable-desktop                │
           │              Gateway                       │
           │  ┌────────┐ ┌────────┐ ┌────────────┐  │
 Telegram ──┤  │TG Channel│ │Feishu  │ │  WeCom     │  │
           │  └────┬───┘ └────┬───┘ └─────┬──────┘  │
           │       │           │            │          │
           │  ┌────┴───────────┴────────────┴────┐   │
           │  │         Session Manager             │   │
           │  │  · 多通道会话管理                   │   │
           │  │  · Handoff 追踪                    │   │
           │  │  · 消息路由                        │   │
           │  └─────────────────┬──────────────────┘   │
           │                    │                       │
           │  ┌─────────────────┴──────────────────┐  │
           │  │      AgentSession / Workflow        │  │
           │  │  · 工作流自动触发                   │  │
           │  │  · 终端执行                        │  │
           │  └───────────────────────────────────┘  │
           └──────────────────────────────────────────┘

实例管理 ​

Gateway 支持多个独立实例，每个实例有自己独立的通道配置和会话管理。

创建实例：在 Gateway 页面点击"Add Instance"按钮，输入实例名称即可创建新实例。

实例操作：

  • 启动/停止：每个实例独立启停，状态实时显示
  • 重命名：点击实例名称直接编辑
  • 删除：删除实例（会同时清除该实例的所有会话和消息历史）

通道配置 ​

Gateway 页面有四个 Tab：Defaults、Channels、Messages、Sessions。

Defaults Tab - 默认执行参数 ​

每个 Gateway 实例有全局默认执行参数：

参数说明默认值
Backend默认 AI 后端-
Model默认模型-
Provider Group默认 Provider 组-
Workdir默认工作目录.
Workflow默认工作流-
Execution Mode执行模式background（后台）
Terminal Busy Policy终端忙碌策略queue（排队）

终端忙碌策略说明：

  • queue：当终端忙碌时，新任务进入队列等待
  • reject：当终端忙碌时，拒绝新任务

Channels Tab - 通道配置 ​

三个通道的详细配置：

Telegram ​

配置项说明
Enabled是否启用 Telegram 通道
Bot TokenTelegram Bot 的 API Token（向 @BotFather 申请）
Allow From允许交互的用户 ID 列表（留空允许所有人）

申请 Bot Token：

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot 创建新 Bot
  3. 复制 Bot Token 填入配置

飞书（Feishu） ​

配置项说明
Enabled是否启用飞书通道
Auto Start on Launch启动时自动开启 Gateway
Mode连接模式（ws WebSocket 推荐）
App ID飞书应用 App ID
App Secret飞书应用 App Secret
Verification Token飞书事件订阅的 Verification Token
Encrypt Key飞书事件订阅的 Encrypt Key（可选）
Port本地监听端口（默认 9800）
Allow From允许交互的用户 ID 列表
Bot Name机器人名称覆盖
Bot Registry多 Bot 注册表配置

飞书应用申请：

  1. 访问 飞书开放平台
  2. 创建企业自建应用
  3. 申请权限：im:message、contact:user.base:readonly
  4. 配置事件订阅，使用 WebSocket 模式

企业微信（WeCom） ​

配置项说明
Enabled是否启用企业微信通道
Corp ID企业 ID
Agent ID应用 Agent ID
Secret应用 Secret
Token事件订阅 Token
Encoding AES Key事件加密 AES Key
Port本地监听端口（默认 9801）
Allow From允许交互的用户 ID 列表

会话管理 ​

Session Key 机制 ​

Gateway 为每个 IM 会话分配一个唯一的 session_key，用于：

  • 追踪同一用户的多轮对话上下文
  • 在 waiting_input 状态下恢复会话
  • 关联 AgentSession 和 IM 消息

Handoff 机制 ​

Handoff 是 Gateway 中的核心概念，用于追踪任务在不同处理阶段之间的流转：

IM Message → Gateway → AgentSession Created → Workflow Running
                                                      ↓
IM Message ← Gateway ← Result/Response ← Workflow Done/Waiting

Handoff 状态：

  • Unbound：新收到的消息尚未绑定到 AgentSession
  • Bound：已绑定到某个 AgentSession，正在处理中
  • Recoverable：会话可以恢复（处于 waiting_input 等中间状态）

Status 页面会显示所有 Gateway 实例的 Handoff 统计，包括未绑定的 Handoff 数量（unbound_handoffs）。未绑定 Handoff 过多通常意味着系统繁忙或 AgentSession 创建失败。

多通道消息路由 ​

Gateway 自动根据消息来源（channel）路由到对应的处理逻辑：

  • Telegram 消息：/do <任务> 启动 do 工作流
  • 飞书消息：支持 slash 命令和工作流触发
  • 企业微信消息：与飞书类似的多命令格式

消息历史 ​

Messages Tab ​

Messages Tab 展示实时消息流日志：

消息字段：

  • channel：消息来源通道（telegram/feishu/wecom）
  • sender_id/sender_name：发送者 ID 和名称
  • chat_id：IM 平台聊天 ID
  • direction：消息方向（inbound/outbound）
  • trigger_status：触发状态（triggered/skipped 等）
  • skip_reason：如果跳过，原因是什敏
  • session_key：关联的会话 Key
  • workflow_sid：关联的工作流 Session ID
  • content：消息内容
  • time：时间戳

过滤功能：

  • 按通道过滤（All/Telegram/飞书/企微）
  • 搜索消息内容
  • 实时滚动显示最新消息（最多保留 1000 条）

Sessions Tab ​

Sessions Tab 展示当前 Gateway 实例的所有活跃 Chat Session：

Session 字段：

  • session_key：会话唯一标识
  • chat_id：IM 聊天 ID
  • channel：所属通道
  • agent_session_id：关联的 AgentSession
  • status：会话状态
  • created_at：创建时间

操作：

  • 点击 Session 可查看该会话的所有消息
  • 从 Session 可直接恢复关联的 AgentSession

与其他页面的联动 ​

Gateway → Terminal ​

Gateway 触发的工作流自动在 Terminal 页面执行。用户可以在 Terminal 中：

  • 查看实时执行输出
  • 在 waiting_input 状态下提供输入继续执行
  • 中断正在执行的任务

Gateway → Status（Doctor） ​

Status 页面实时显示所有 Gateway 实例的状态：

  • Gateway Statuses：每个实例的状态（running/stopped/error）
  • Online Gateways：当前在线的 Gateway 实例数
  • Active Gateway Sessions：活跃会话数
  • Active Gateway Handoffs：活跃 Handoff 数
  • Queued Gateway Tasks：队列中的任务数
  • Unbound Gateway Handoffs：未绑定 Handoff 数

Gateway → Conversations ​

Gateway 触发的对话会自动记录到 Conversations 页面，Token 消耗和消息内容均可在 Conversations 页面查看。

配置验证与启动 ​

启动 Gateway 实例前，系统会进行配置验证：

  1. Backend 必须配置：至少需要配置一个 Backend（AI 后端）
  2. Model 必须配置：至少需要一个 Model
  3. Workdir 必须配置：工作目录不能为空
  4. 至少启用一个通道：Telegram/飞书/企微至少启用一个

验证失败时，Gateway 会显示具体错误信息（如 missing_backend、missing_model、no_channels）。

License 要求 ​

Gateway 功能（多通道接入）属于 Team License 专属功能。Community 和 Pro 版本用户无法使用 Gateway。

查看当前 License 状态：进入 License 页面 激活或升级。 完整授权差异见授权等级。

故障排查 ​

Gateway 无法启动 ​

  1. 检查配置是否完整（Backend/Model/Workdir/至少一个通道）
  2. 检查端口是否被占用（Telegram 默认无需端口，飞书默认 9800，企微默认 9801）
  3. 查看 Status 页面的 Gateway 错误告警

消息未触发工作流 ​

  1. 确认通道已启用且 Gateway 实例正在运行
  2. 检查 Allow From 是否包含你的用户 ID
  3. 查看 Messages Tab 是否有消息到达记录
  4. 查看 Status 页面的 Handoff 统计是否有 unbound 情况

Handoff 堆积 ​

Handoff 堆积说明工作流执行速度跟不上消息到达速度：

  1. 增加终端数量（License 允许范围内）
  2. 调整终端忙碌策略为 queue 以排队而非拒绝
  3. 在 Status 页面查看是否有 provider 处于 cooldown/degraded 状态

Workflows / Orchestration / Execution

Copyright © 2026 PinableAgents · PinableLab