消息网关
通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、BlueBubbles (iMessage)、QQ、Yuanbao、Microsoft Teams、LINE、ntfy 或浏览器与 Kopi Agent 聊天。网关是一个单一的后台进程,可连接你配置的所有平台、管理会话、运行 cron 任务并投递语音消息。
有关完整的语音功能集 — 包括 CLI 麦克风模式、消息中的语音回复以及 Discord 语音频道对话 — 请参阅语音模式和在 Kopi Agent 中使用语音模式。
机器人需要同时具备模型 provider 和工具 provider(TTS、web)。KOPI Proxy 订阅捆绑了所有这些服务。
平台对比
| 平台 | 语音 | 图片 | 文件 | 话题 | 表情回应 | 输入指示 | 流式 |
|---|---|---|---|---|---|---|---|
| Telegram | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Discord | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Slack | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Google Chat | — | ✅ | ✅ | ✅ | — | ✅ | — |
| — | ✅ | ✅ | — | — | ✅ | ✅ | |
| Signal | — | ✅ | ✅ | — | — | ✅ | ✅ |
| SMS | — | — | — | — | — | — | — |
| — | ✅ | ✅ | ✅ | — | — | — | |
| Home Assistant | — | — | — | — | — | — | — |
| Mattermost | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Matrix | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| DingTalk | — | ✅ | ✅ | — | ✅ | — | ✅ |
| Feishu/Lark | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| WeCom | ✅ | ✅ | ✅ | — | — | — | — |
| WeCom Callback | — | — | — | — | — | — | — |
| Weixin | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |
| BlueBubbles | — | ✅ | ✅ | — | ✅ | ✅ | — |
| ✅ | ✅ | ✅ | — | — | ✅ | — | |
| Yuanbao | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |
| Microsoft Teams | — | ✅ | — | ✅ | — | ✅ | — |
| LINE | — | ✅ | ✅ | — | — | ✅ | — |
| ntfy | — | — | — | — | — | — | — |
| Raft | — | — | — | — | — | — | — |
| IRC | — | — | — | — | — | — | — |
语音 = TTS 音频回复和/或语音消息转写。图片 = 发送/接收图片。文件 = 发送/接收文件附件。话题 = 话题式对话。表情回应 = 消息上的 emoji 回应。输入指示 = 处理时显示"正在输入"。流式 = 通过编辑消息实现渐进式更新。
架构
每个平台 adapter 接收消息,通过按聊天划分的会话存储进行路由,并将其分发给 AIAgent 进行处理。网关还会运行 cron 调度器,每 60 秒触发一次以执行到期的任务。
有意静默 token
对于群聊、hook 和自动化流程,Kopi Agent 支持显式静默 token。如果 agent 的最终回复恰好是单个受支持的 token,网关将抑制消息外发,不向聊天发送任何内容。
支持的 token:
[SILENT]SILENTNO_REPLYNO REPLY
空白字符和大小写会被规范化,但整个最终回复必须就是该 token。像 "Use [SILENT] when nothing changed" 这样的句子会正常投递。
静默仅影响消息投递。Kopi Agent 仍会将助手的静默轮次保留在会话记录中,因此对话仍会正常交替进行:
user: side-channel chatter
assistant: [SILENT] # stored, not delivered
user: next message
失败的轮次仍会作为错误呈现;Kopi Agent 不会仅仅因为文本看起来像静默 token 就隐藏失败。
快速设置
配置消息平台最简单的方式是使用交互式向导:
kopi gateway setup # Interactive setup for all messaging platforms
该向导会通过方向键选择逐步引导你配置每个平台,显示哪些平台已配置好,并在完成后提供启动/重启网关的选项。
网关命令
kopi gateway # Run in foreground
kopi gateway setup # Configure messaging platforms interactively
kopi gateway install # Install as a user service (Linux) / launchd service (macOS)
sudo kopi gateway install --system # Linux only: install a boot-time system service
kopi gateway start # Start the default service
kopi gateway stop # Stop the default service
kopi gateway status # Check default service status
kopi gateway status --system # Linux only: inspect the system service explicitly
聊天命令(消息内使用)
| 命令 | 说明 |
|---|---|
/new 或 /reset | 开始全新对话 |
/model [provider:model] | 显示或更改模型(支持 provider:model 语法) |
/personality [name] | 设置人格 |
/retry | 重试上一条消息 |
/undo | 删除上一次交互 |
/status | 显示会话信息 |
/whoami | 显示你在此范围内的斜杠命令权限(admin / user / unrestricted) |
/stop | 停止正在运行的 agent |
/approve | 批准待处理的危险命令 |
/deny | 拒绝待处理的危险命令 |
/sethome | 将此聊天设置为主频道 |
/compress | 手动压缩对话上下文 |
/title [name] | 设置或显示会话标题 |
/resume [name] | 恢复之前命名的会话 |
/usage | 显示此会话的 token 用量 |
/insights [days] | 显示用量洞察与分析 |
/reasoning [level|show|hide] | 更改推理强度或切换推理显示 |
/voice [on|off|tts|join|leave|status] | 控制消息语音回复及 Discord 语音频道行为 |
/rollback [number] | 列出或恢复文件系统检查点 |
/background <prompt> | 在独立的后台会话中运行 prompt |
/reload-mcp | 从 config 重新加载 MCP server |
/update | 将 KOPI AI AGENT 更新到最新版本 |
/help | 显示可用命令 |
/<skill-name> | 调用任意已安装的 skill |
会话管理
会话持久性
会话在消息之间持续存在,直到被重置。agent 会记住你的对话上下文。
重置策略
默认情况下,会话永不自动重置 —— 上下文会一直保留,直到你 /reset
手动重置,或触发上下文压缩。如果你希望自动重置,可以通过 ~/.kopi/config.yaml 中的
session_reset 部分进行选择启用:
session_reset:
mode: idle # "idle", "daily", "both", or "none" (default)
idle_minutes: 1440 # for idle/both: minutes of inactivity before reset
at_hour: 4 # for daily/both: hour of day (0-23, local time)
| 模式 | 描述 |
|---|---|
none | 永不自动重置(默认) |
daily | 每天在指定小时重置 |
idle | 在 N 分钟无活动后重置 |
both | 哪个先触发就用哪个 |
一个活跃的后台进程(通过 terminal(background=true) 启动)通常会保护其会话不被重置,
以免输出丢失。为了防止被遗忘的进程 —— 比如一个预览服务器 —— 让会话永远保持
开启,存在时间超过 bg_process_max_age_hours(默认 24)的后台进程将不再阻止重置。该进程
不会被终止,只是被重置守卫忽略。将其设为 0 可禁用这一时限
(任何活跃进程都会阻止重置,即旧行为),或者如果你运行需要保持存活状态以让对话
持续开启的多日任务,可以调高该值。
在 ~/.kopi/gateway.json 中按平台配置覆盖项:
{
"reset_by_platform": {
"telegram": { "mode": "idle", "idle_minutes": 240 },
"discord": { "mode": "idle", "idle_minutes": 60 }
}
}
安全
默认情况下,gateway 会拒绝所有不在允许列表中、也未通过 DM 配对的用户。 对于拥有终端访问权限的 bot 来说,这是安全的默认设置。
# Restrict to specific users (recommended):
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2
# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321
# Or explicitly allow all users (NOT recommended for bots with terminal access):
GATEWAY_ALLOW_ALL_USERS=true
DM 配对(允许列表的替代方案)
无需手动配置 user ID,未知用户在向 bot 发送 DM 时会收到一个一次性配对码。Email 是例外:未知的 email 发件人会被忽略,除非显式启用了 email 配对。
# The user sees: "Pairing code: XKGH5N7P"
# You approve them with:
kopi pairing approve telegram XKGH5N7P
# Other pairing commands:
kopi pairing list # View pending + approved users
kopi pairing revoke telegram 123456789 # Remove access
配对码 1 小时后过期,有速率限制,并使用加密随机数。
管理员与普通用户
允许列表回答的是"这个人到底能不能联系到 bot?"而 admin / user 划分回答的是"既然他们进来了,他们被允许做什么?"
每个被允许的用户在每个作用域(DM 与群组/频道)中都属于两个层级之一:
- Admin —— 完全访问权限。可以运行每一个已注册的 slash command(内置 + plugin),并使用每一项受控能力。
- 普通用户 —— 受限访问权限。可以正常与 agent 聊天,但只能运行你显式启用的 slash command。始终允许的底线是
/help和/whoami。
这些层级按平台和按作用域配置。DM 的 admin 身份并不意味着拥有群组/频道的 admin 身份 —— 每个作用域都有各自的管理员列表。
目前这些层级控制的内容: slash command。该划分贯穿实时命令注册表,因此无需逐项功能接线就能覆盖内置命令和 plugin 注册的命令。普通聊天不受影响 —— 非管理员仍然可以与 agent 对话。
未来可能会受控的内容: 更多能力入口(工具访问、模型切换、高开销操作)将随着我们逐步添加,同样挂在 admin / user 区分之下。现在就配置好这一划分,意味着那些未来的限制能顺畅落地,你无需重新建模谁是管理员。
配置
gateway:
platforms:
discord:
extra:
allow_from: ["111", "222", "333"]
allow_admin_from: ["111"] # admins → all slash commands
user_allowed_commands: [status, model] # what non-admins may run
# Optional: separate group/channel scope
group_allow_admin_from: ["111"]
group_user_allowed_commands: [status]
向后兼容: 如果某个作用域未设置 allow_admin_from,则该作用域的层级划分被禁用,每个被允许的用户都拥有完全访问权限。现有安装无需任何改动即可继续工作 —— 需要区分时再选择启用。
查看你的访问权限
在任意平台上使用 /whoami,可查看当前作用域、你的层级(admin / user / unrestricted)以及你可以运行哪些 slash command。参见 Telegram 和 Discord 页面了解各平台的具体示例。
打断 Agent
在 agent 工作时发送任意消息即可打断它。关键行为:
- 进行中的终端命令会被立即终止(先发送 SIGTERM,1 秒后发送 SIGKILL)
- 工具调用会被取消 —— 只有当前正在执行的那个会运行,其余全部跳过
- 多条消息会被合并 —— 打断期间发送的消息会被拼接成一条 prompt
/stop命令 —— 打断但不排队后续消息
排队 vs 打断 vs 引导(忙碌输入模式)
默认情况下,向忙碌中的 agent 发消息会打断它。另外还有两种模式可用:
queue—— 后续消息会等待,并在当前任务完成后作为下一个轮次运行。steer—— 后续消息会通过/steer注入到当前运行中,在下一次工具调用之后到达 agent。不打断,也不开启新轮次。如果 agent 尚未开始,则回退到queue行为。
display:
busy_input_mode: steer # or queue, or interrupt (default)
busy_ack_enabled: true # set to false to suppress the ⚡/⏳/⏩ chat reply entirely
在任意平台上首次向忙碌中的 agent 发消息时,Kopi Agent 会在忙碌确认(busy-ack)后附加一行说明该开关("💡 First-time tip — …")的提示。该提示每次安装只触发一次 —— onboarding.seen.busy_input_prompt 下的一个标志会将其锁定。删除该键即可再次看到提示。
如果你觉得忙碌确认(busy-ack)太吵 —— 尤其是在使用语音输入或连续快速发消息时 —— 请设置 display.busy_ack_enabled: false。你的输入仍会照常排队/引导/打断,只是聊天回复被静音。
工具进度通知
控制在 ~/.kopi/config.yaml 中显示多少工具活动:
display:
tool_progress: all # off | new | all | verbose
tool_progress_command: false # set to true to enable /verbose in messaging
# How progress is grouped on platforms that support message editing:
# accumulate (default) — edit one bubble in place as tools run
# separate — send one message per tool (pre-v0.9 style; noisier)
# Only applies where tool_progress is already enabled.
tool_progress_grouping: accumulate # accumulate | separate
模型上下文中的消息时间戳
默认关闭。启用后,Kopi Agent 会在模型上下文中的每条用户消息前加上一个人类可读的时间戳
(例如 [Tue 2026-04-28 13:40:53 CEST]),让 agent 知道消息是什么时候发送的 —— 对时间推理很有用
("你是今天早上问的……",注意到一段长时间的间隔)。它不会被添加到
assistant 消息或 system prompt 中。
gateway:
message_timestamps:
enabled: false # set true to show send-times to the model
持久化的对话记录始终保持干净 —— 无论该开关如何,时间戳都会作为消息 元数据存储,因此之后启用它同样会展示过去消息的发送时间,而且重放(replay)时 不会累积重复的前缀。
启用后,bot 会在工作时发送状态消息:
💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...
后台会话
在独立的后台会话中运行 prompt(提示词),这样 agent(智能体)就能独立处理任务,而你的主聊天仍保持响应:
/background Check all servers in the cluster and report any that are down
Kopi Agent 会立即确认:
🔄 Background task started: "Check all servers in the cluster..."
Task ID: bg_143022_a1b2c3
工作原理
每个 /background prompt(提示词)都会生成一个独立的 agent 实例,以异步方式运行:
- 隔离的会话 — 后台 agent 拥有自己的会话和自己的对话历史。它不了解你当前的聊天上下文,只会收到你提供的 prompt。
- 相同的配置 — 继承你当前 gateway(网关)设置中的 model(模型)、provider(服务提供商)、toolsets(工具集)、推理设置以及 provider 路由。
- 非阻塞 — 你的主聊天保持完全可交互状态。你可以发送消息、运行其他命令,或在它工作时启动更多后台任务。
- 结果传递 — 任务完成后,结果会发送回你发出命令所在的同一聊天或频道,并以"✅ Background task complete"作为前缀。如果失败,你会看到"❌ Background task failed"以及错误信息。
后台进程通知
当运行后台会话的 agent 使用 terminal(background=true) 启动长时间运行的进程(服务器、构建等)时,gateway 可以向你的聊天推送状态更新。通过 ~/.kopi/config.yaml 中的 display.background_process_notifications 控制此行为:
display:
background_process_notifications: all # all | result | error | off
| 模式 | 你会收到的内容 |
|---|---|
all | 运行输出更新以及最终完成消息(默认) |
result | 仅最终完成消息(无论退出代码是什么) |
error | 仅在退出代码非零时发送最终消息 |
off | 完全不发送进程监视器消息 |
你也可以通过环境变量进行设置:
KOPI_BACKGROUND_NOTIFICATIONS=result
用例
- 服务器监控 — "/background Check the health of all services and alert me if anything is down"
- 长时间构建 — "/background Build and deploy the staging environment",同时你可以继续聊天
- 调研任务 — "/background Research competitor pricing and summarize in a table"
- 文件操作 — "/background Organize the photos in ~/Downloads by date into folders"
消息平台上的后台任务是"发后即忘"的 — 你无需等待或查看它们。任务完成后,结果会自动出现在同一聊天中。
服务管理
Linux (systemd)
kopi gateway install # Install as user service
kopi gateway start # Start the service
kopi gateway stop # Stop the service
kopi gateway status # Check status
journalctl --user -u kopi-gateway -f # View logs
# Enable lingering (keeps running after logout)
sudo loginctl enable-linger $USER
# Or install a boot-time system service that still runs as your user
sudo kopi gateway install --system
sudo kopi gateway start --system
sudo kopi gateway status --system
journalctl -u kopi-gateway -f
在笔记本电脑和开发机上使用用户服务。在 VPS 或无头主机上使用系统服务,这些主机需要在开机时自动恢复运行,而不依赖 systemd linger。
ExecStopPost kill drop-inKopi Agent 安装的 unit 已经通过 KillMode=mixed + KillSignal=SIGTERM 干净地关闭 gateway,并使用 Restart=always 配合 RestartForceExitStatus,使更新和 /restart 能够正确地重新生成进程。不要添加诸如 ExecStopPost=/bin/kill -9 $MAINPID 这样的 systemd drop-in — ExecStopPost 会在每次停止时触发,包括干净的重启,因此它会在新生成的实例稳定之前将其 SIGKILL,而 Restart=always 会立即将其重新生成。结果就是无限重启循环(在 Telegram 上还会导致重启消息刷屏)。如果你已经添加了这样的 drop-in,请将其移除:systemctl --user edit kopi-gateway(如果是系统服务则用 sudo systemctl edit kopi-gateway),删除 ExecStopPost 那一行,然后 systemctl --user daemon-reload。
系统服务每次重启都需要 root 权限 — 包括 kopi update 结束时的 gateway 自动重启。当 kopi update 以非 root 用户身份运行时,它会尝试免密的 sudo systemctl;如果不可用,它会跳过重启并打印手动执行的 sudo systemctl restart kopi-gateway 命令(它绝不会阻塞在交互式密码提示上)。
对于你从不登录的无头虚拟机,启用 lingering 的用户服务能在完全不涉及 root 的情况下提供相同的开机自启行为:
kopi gateway install # user service
sudo loginctl enable-linger $USER # one-time: start at boot, survive logout
之后,kopi update 就能在无需任何权限的情况下重启 gateway。如果你倾向于保留系统服务,可以使用 sudo kopi update 运行更新,或者为服务账户授予 systemctl 的免密 sudo 权限,例如在 sudo visudo -f /etc/sudoers.d/kopi-gateway 中:
kopi ALL=(root) NOPASSWD: /usr/bin/systemctl --no-ask-password reset-failed kopi-gateway*, /usr/bin/systemctl --no-ask-password start kopi-gateway*, /usr/bin/systemctl --no-ask-password restart kopi-gateway*
除非确实有意为之,否则请避免同时保留用户和系统两套 gateway unit。如果 Kopi Agent 检测到两者同时存在,它会发出警告,因为启动/停止/状态行为会变得不明确。
如果你在同一台机器上运行多个 Kopi Agent 安装实例(使用不同的 KOPI_HOME 目录),每个实例都会有自己的 systemd 服务名称。默认的 ~/.kopi 使用 kopi-gateway;其他安装实例使用 kopi-gateway-<hash>。kopi gateway 命令会自动针对你当前 KOPI_HOME 对应的正确服务。
macOS (launchd)
kopi gateway install # Install as launchd agent
kopi gateway start # Start the service
kopi gateway stop # Stop the service
kopi gateway status # Check status
tail -f ~/.kopi/logs/gateway.log # View logs
生成的 plist 位于 ~/Library/LaunchAgents/ai.kopi.gateway.plist。它包含三个环境变量:
- PATH — 你在安装时的完整 shell PATH,前面加上了 venv 的
bin/和node_modules/.bin。这确保用户安装的工具(Node.js、ffmpeg 等)对 WhatsApp bridge 等 gateway 子进程可用。 - VIRTUAL_ENV — 指向 Python 虚拟环境,以便工具能够正确解析软件包。
- KOPI_HOME — 将 gateway 的作用范围限定在你的 Kopi Agent 安装目录。
launchd plist 是静态的 — 如果你在设置 gateway 之后安装了新工具(例如通过 nvm 安装新版本的 Node.js,或通过 Homebrew 安装 ffmpeg),请再次运行 kopi gateway install 以捕获更新后的 PATH。gateway 会检测到过期的 plist 并自动重新加载。
与 Linux systemd 服务类似,每个 KOPI_HOME 目录都有自己的 launchd label(标签)。默认的 ~/.kopi 使用 ai.kopi.gateway;其他安装实例使用 ai.kopi.gateway-<suffix>。
平台专属工具集
每个平台都有自己的工具集:
| 平台 | 工具集 | 功能 |
|---|---|---|
| CLI | kopi-cli | 完全访问权限 |
| Telegram | kopi-telegram | 完整工具(含终端) |
| Discord | kopi-discord | 完整工具(含终端) |
kopi-whatsapp | 完整工具(含终端) | |
| WhatsApp Cloud API | kopi-whatsapp | 完整工具(含终端)(与 Baileys bridge 共享工具集) |
| Slack | kopi-slack | 完整工具(含终端) |
| Google Chat | kopi-google_chat | 完整工具(含终端) |
| Signal | kopi-signal | 完整工具(含终端) |
| SMS | kopi-sms | 完整工具(含终端) |
kopi-email | 完整工具(含终端) | |
| Home Assistant | kopi-homeassistant | 完整工具 + HA 设备控制(ha_list_entities、ha_get_state、ha_call_service、ha_list_services) |
| Mattermost | kopi-mattermost | 完整工具(含终端) |
| Matrix | kopi-matrix | 完整工具(含终端) |
| DingTalk | kopi-dingtalk | 完整工具(含终端) |
| Feishu/Lark | kopi-feishu | 完整工具(含终端) |
| WeCom | kopi-wecom | 完整工具(含终端) |
| WeCom Callback | kopi-wecom-callback | 完整工具(含终端) |
| Weixin | kopi-weixin | 完整工具(含终端) |
| BlueBubbles | kopi-bluebubbles | 完整工具(含终端) |
| QQBot | kopi-qqbot | 完整工具(含终端) |
| Yuanbao | kopi-yuanbao | 完整工具(含终端) |
| Microsoft Teams | kopi-teams | 完整工具(含终端) |
| API Server | kopi-api-server | 完整工具(不含 clarify、text_to_speech——程序化访问没有交互式用户) |
| Webhooks | kopi-webhook | 完整工具(含终端) |
| Raft | kopi-raft | 仅唤醒通道;agent 使用 Raft CLI 进行消息收发 |
运维多平台 gateway
gateway 通常会同时运行多个 adapter(Telegram + Discord + Slack 等)。以下各节涵盖跨所有平台的日常运维(day-2)操作。
/platform 命令
gateway 启动后,可以从任意已连接的 CLI 会话或聊天中使用 /platform 斜杠命令来检查并控制各个 adapter,而无需重启整个 gateway:
/platform list # show all adapters and their state
/platform pause <name> # stop dispatching new messages to one adapter
/platform resume <name> # re-enable a paused adapter
/platform list 会显示每个 adapter 是处于 running、paused(手动)还是 paused-by-breaker 状态(见下文)。暂停会使 adapter 保持已加载状态,其后台循环也继续运行——收到的消息会被直接丢弃,但连接本身保持打开,因此恢复是瞬时的。
另请参阅更全面的状态汇总命令 /platforms。
自动熔断器
每个 adapter 都包裹在一个熔断器(circuit breaker)中。反复出现可重试的故障(网络抖动、限流回复、5xx 上游响应、websocket 断连)会导致熔断器跳闸——adapter 会被自动暂停,若配置了其他在线平台的主频道,则会向该频道发送运维通知,并输出一条结构化日志行。
熔断器不会自动恢复——它会保持断开状态,直到你手动运行 /platform resume <name>。这是有意为之:如果某个平台正在经历持续性故障,你不希望 gateway 反复疯狂重连。
平台暂停时应查看的位置
当某个 adapter 被暂停时,请检查:
- Gateway 日志(
~/.kopi/logs/gateway.log或 systemd / launchd 单元日志)。搜索平台名称以及circuit breaker、paused或disabled。跳闸事件中包含失败次数和最后一次错误。 /platform list输出——显示当前状态和最后一次原因。- provider(服务提供商)的状态页面(Telegram bot API status、Discord status 等)。熔断器跳闸是因为平台处于不健康状态;在平台恢复之前不要尝试恢复。
一旦上游恢复正常,/platform resume <name> 会清除熔断器并重新武装 adapter。
重启通知
当 gateway 重启(或在存在进行中会话的情况下关闭)时,它可以向每个平台的主频道发送一条一次性的"agent 回来了"/"agent 被中断"消息。这通过 gateway-config.yaml 中按平台配置的 gateway_restart_notification 标志控制,默认值为 true:
gateway:
platforms:
telegram:
home_chat_id: "123456789"
gateway_restart_notification: false # opt out for this platform
discord:
home_chat_id: "987654321"
# gateway_restart_notification omitted → defaults to true
在嘈杂或低优先级的平台上将其禁用,同时为主要聊天保留启用状态。每次重启只发送一次通知,无论当时有多少会话正在进行。
输入指示器
当 agent 正在处理消息时,gateway 会在支持该功能的平台上显示实时的输入状态——Telegram/Discord/Signal 上的"正在输入…"气泡,或 Slack 上的"is thinking…"助手状态。这通过 gateway-config.yaml 中按平台配置的 typing_indicator 标志控制,默认值为 true:
gateway:
platforms:
slack:
typing_indicator: false # don't show "is thinking…" on Slack
telegram:
# typing_indicator omitted → defaults to true
在不希望显示该指示器的任何平台上将 typing_indicator: false 设为禁用。有些用户觉得 Slack 的"is thinking…"状态很吵(由于它使用 Slack 的 Assistant API,在显示期间还会短暂禁用输入框)。禁用它只会抑制指示器——消息投递及其他一切功能均不受影响。该标志是通用的,因此同一个键适用于所有平台。
跨 gateway 重启的会话恢复
当 gateway 在存在进行中的 tool call 或生成任务的情况下关闭时,受影响的会话会被标记为 restart_interrupted。在下次启动时,gateway 会为每个这样的会话安排自动恢复——用户会在聊天中收到一条简短提示("重启后发送任意消息,我会尝试从你上次中断的地方继续。"),当他们回复时,会话将从最后一个已提交的回合继续。
此行为默认开启,并在 gateway 启动时记录日志:
Scheduled auto-resume for N restart-interrupted session(s)
无需任何配置。如果不希望收到该提示,请在相应平台上设置 gateway_restart_notification: false。
面向移动端的进度默认值
Telegram 通常是移动收件箱,因此默认值针对该界面进行了调整:
tool_progress默认为off——不会有一条条 tool 面包屑流刷屏聊天记录。busy_ack_detail默认为off——忙碌状态确认和长时间运行的心跳保持简短(不含iteration 21/60调试细节)。interim_assistant_messages保持 开启——真正的回合中途助手评论(模型明确告诉你它即将做什么)是有用信号,不是噪音。long_running_notifications保持 开启——一个原地编辑的"⏳ Working — N min"气泡每隔几分钟更新一次,这样你会收到心跳提示,而不必盯着typing…看上半个小时。
可以按平台选择退出这两个保持开启的默认值,或重新开启详细进度:
display:
platforms:
telegram:
# Re-enable the tool-progress stream
tool_progress: new
# Show "iteration N/M, running: tool" in heartbeats and busy acks
busy_ack_detail: true
# Or quiet them entirely
interim_assistant_messages: false
long_running_notifications: false
进度气泡清理(可选启用)
Tool 进度消息、"still working…"心跳以及状态回调气泡也可以在最终响应落地后自动删除。通过 display.platforms.<platform>.cleanup_progress 按平台启用:
display:
platforms:
telegram:
cleanup_progress: true
discord:
cleanup_progress: true
默认值为 false。只有 adapter 实现了 delete_message 的平台才会遵守该设置(目前是 Telegram 和 Discord)。失败的运行会跳过清理,因此气泡会作为面包屑保留下来。
后续步骤
- Telegram 设置
- Discord 设置
- Slack 设置
- Google Chat 设置
- WhatsApp 设置
- WhatsApp Business Cloud API 设置
- Signal 设置
- SMS 设置 (Twilio)
- Email 设置
- Home Assistant 集成
- Mattermost 设置
- Matrix 设置
- DingTalk 设置
- Feishu/Lark 设置
- WeCom 设置
- WeCom 回调设置
- Weixin(微信)设置
- BlueBubbles 设置 (iMessage)
- QQBot 设置
- Yuanbao 设置
- Microsoft Teams 设置
- Teams Meetings 流水线
- Open WebUI + API Server
- Raft 设置
- IRC 设置
- Webhooks