远程连接
飞书机器人接入
创建飞书应用，配置 SoniBot 渠道并通过用户配对控制访问。
通过飞书渠道，你可以在飞书会话中向 SoniBot 助手发送任务，并在运行 SoniBot 的机器上执行。
准备飞书应用
- 打开飞书开放平台；
- 创建企业自建应用；
- 为应用启用机器人能力；
- 按飞书机器人指引配置接收消息所需的权限和事件；
- 发布或启用应用，使目标成员可以找到机器人；
- 在“凭证与基础信息”中获取 App ID 与 App Secret。
飞书后台的权限名称和发布流程可能调整，应以开放平台当前页面为准。只申请收发机器人消息所需的最小权限。
在 SoniBot 中连接
- 进入“设置 → Channels → 飞书”；
- 填入 App ID；
- 填入 App Secret；
- 如果飞书应用启用了事件加密或校验，再展开可选项，填写 Encrypt Key 与 Verification Token；
- 点击“测试并连接”；
- 连接成功后，SoniBot 会保存凭据并启用飞书渠道；
- 确认渠道状态显示已连接。
不要在截图、工单或聊天消息中暴露 App Secret。怀疑泄露时，应先在飞书开放平台重置，再更新 SoniBot 配置。
选择助手
在飞书渠道设置中选择一个已启用助手。该助手决定：
- 由哪个 Agent 执行；
- 使用哪些规则和技能；
- 默认权限和工具范围；
- 内置 Agent 场景下使用哪个默认模型。
选择前先在桌面端用该助手完成一次测试会话。用于飞书的助手应避免依赖只能人工拖入的临时文件，规则中也不要包含本机敏感路径。
用户配对
- 让用户在飞书中向机器人发送消息；
- 机器人返回或触发配对申请；
- 在 SoniBot 飞书设置的“待处理配对”中核对显示名、平台用户与配对码；
- 在有效期内批准或拒绝；
- 批准后，用户出现在“已授权用户”中；
- 需要收回访问时，点击撤销。
只批准你能确认身份的用户。配对码有有效期，过期后让用户重新发起。
更换凭据
当已有授权用户时，凭据输入可能被锁定。建议按以下顺序处理：
- 通知正在使用的用户；
- 停用飞书渠道；
- 撤销已授权用户；
- 在飞书开放平台重置或更换凭据；
- 在 SoniBot 填入新凭据并测试；
- 重新启用并完成用户配对。
常见问题
测试连接失败
- 检查 App ID 与 App Secret 是否来自同一个应用；
- 确认没有复制多余空格；
- 确认应用状态和 Bot 能力正常；
- 查看飞书后台是否缺少必要权限；
- 检查企业网络能否访问飞书接口。
机器人在线但不响应
- 确认 SoniBot 主机保持运行；
- 检查飞书应用的消息事件配置与发布范围；
- 确认渠道仍是启用状态；
- 检查绑定助手与 Agent 是否可用；
- 查看是否存在待批准的配对申请或权限确认。
可以对话但任务无法完成
- 在桌面端打开对应会话，查看 Agent 的错误和权限请求；
- 检查项目工作空间是否仍存在；
- 检查助手默认技能和 MCP 是否可用；
- 涉及文件发送时，确认文件位于允许的目录。