同时运行多个网关
在一台机器上以托管服务的形式运行多个 profile —— 每个 profile 拥有各自的 bot token、会话和记忆。本页介绍相关的运维问题:一次性启动全部 profile、跨 profile 查看日志、防止主机休眠,以及应对常见的 launchd/systemd 问题。
如果你只运行一个 Kopi Agent,则无需阅读本页 —— 基础内容请参见 Profiles。
何时使用
当你有两个或更多 Kopi Agent 需要同时在线时,就需要这套方案。常见原因包括:
- 一个 Telegram bot 上运行个人助理,另一个 bot 上运行编程 agent
- 每个家庭成员一个 agent,或每个 Slack 工作区一个 agent
- 同一配置的沙盒实例 + 生产实例
- 一个研究 agent + 一个写作 agent + 一个由 cron 驱动的 bot —— 各自拥有相互隔离的记忆和技能
每个 profile 本身已经拥有各自独立的按平台划分的 LaunchAgent(ai.kopi.gateway-<name>.plist)或 systemd 用户服务(kopi-gateway-<name>.service)。本指南补充了统一管理它们的模式。
快速上手
# Create profiles (once)
kopi profile create coder
kopi profile create personal-bot
kopi profile create research
# Configure each
coder setup
personal-bot setup
research setup
# Install each gateway as a managed service
coder gateway install
personal-bot gateway install
research gateway install
# Start them all
coder gateway start
personal-bot gateway start
research gateway start
就这样 —— 三个相互独立的 agent,各自运行在自己的进程中,崩溃后以及用户登录时都会自动重启。
替代方案:单个网关服务所有 profile(多路复用)
上述模型是每个 profile 运行一个进程。这是默认方式,也是大多数场景下的正确选择。但在拥有大量 profile 的主机上——或者在"每个 profile 一个进程"运维成本过高的容器部署中——你可以改为运行单个多路复用网关:默认 profile 的网关成为唯一的入站进程,并为本机上的所有 profile 提供消息服务。
该功能为可选启用,默认关闭。关闭时,本页的任何内容都不生效——下面描述的所有行为均为空转。
何时优先选择多路复用
- 容器/VPS 部署中,N 个 supervisor 单元、N 个端口和 N 个 PID 文件是种负担。
- 存在大量低流量 profile,每个都独立开一个完整进程并不划算。
- 你希望只管理一个对象的启动、监控和重启。
如果你需要 profile 之间具备硬性的进程级隔离(独立的内存占用、独立的故障域、能在不影响其他 profile 的情况下单独重启某个 profile),请继续使用"每个 profile 一个进程"的模式。
如何启用
在默认 profile上设置该标志(它负责承载多路复用器),然后重启它的网关:
kopi config set gateway.multiplex_profiles true
kopi gateway restart
等价地,在默认 profile 的 ~/.kopi/config.yaml 中设置:
gateway:
multiplex_profiles: true
(为方便起见,该标志也可以作为顶层 multiplex_profiles: true 使用。)下次启动时,默认网关会枚举所有 profile,使用各 profile 自身的凭据启动其已启用的平台,并将每条入站消息路由到所属的 profile。每轮对话都会解析被路由到的 profile 的 config、skills、memory、SOUL,以及 provider keys——凭据绝不会跨 profile 共享。
你不需要为次级 profile 运行 kopi gateway start——默认网关会为它们提供服务。详见下文的契约变更。
启用多路复用后会发生什么变化
启用该标志会改变一些行为。以下所有变化在关闭标志的那一刻即恢复原状。
1. 次级 profile 不得启动自己的网关
多路复用器运行时,为命名 profile 执行 kopi gateway start / run 是硬错误,会把你指回多路复用器:
The default gateway is running as a profile multiplexer and already serves
profile 'coder'. ...
多路复用器是唯一的入站进程;第二个 profile 网关会对该 profile 的平台重复绑定。只有当你确实想为某个 profile 运行独立进程时(多路复用器运行期间不建议这样做),才传入 --force。因此,本页前面提到的跨 profile 生命周期包装脚本在多路复用模式下不会使用——你只需管理默认网关。
2. HTTP 入站平台通过 /p/<profile>/ URL 前缀访问
次级 profile 的 Webhook(及其他 HTTP 入站)流量通过 profile 前缀到达默认监听器,而不是第二个端口:
# default profile
POST http://host:8644/webhooks/<route>
# the "coder" profile, same listener
POST http://host:8644/p/coder/webhooks/<route>
前缀中出现未知或未配置的 profile 会返回 404。由于同一个共享监听器已经以这种方式服务所有 profile,次级 profile 不得自行启用端口绑定型平台——这样做属于配置错误,网关会拒绝启动,并指出具体的 profile 和平台:
Profile 'coder' enables the port-binding platform 'webhook', but
gateway.multiplex_profiles is on. ... Remove platforms.webhook from profile
'coder's config.yaml (configure it only on the default profile).
受此规则约束的端口绑定型平台包括:webhook、api_server、msgraph_webhook、feishu、wecom_callback、bluebubbles、sms。这些平台只能在默认 profile 上配置;每个 profile 都可通过其 /p/<profile>/ 前缀访问。
3. 按凭据工作的平台仍需每个 profile 各自的 token
轮询/连接型平台(Telegram、Discord、Slack、Matrix、Signal 等)在多路复用下工作正常,但启用这些平台的每个 profile 都必须提供自己的 bot token——同一个 token 不能同时被两个 profile 轮询。如果两个 profile 配置了相同的 (platform, token),启动时会立即失败并指明这两个 profile(参见Token 冲突安全——规则没有变化,只是现在在同一个进程内强制执行)。
4. Session key 按 profile 做命名空间隔离
每个 profile 的 sessions 都位于各自的 agent:<profile>:… 命名空间下,因此同一平台上同一聊天中的两个 profile 在共享 session 存储中绝不会冲突。默认 profile 原样保留历史的 agent:main:… 命名空间(逐字节不变),因此现有的默认 profile session 不受影响——无需迁移,也不会产生孤立的历史记录。
5. 单一 PID/锁和单一状态视图
只有一个进程级 PID 和锁(多路复用器,位于默认 home 下)。kopi status 会报告多路复用器及其服务的 profile;kopi status -p <name> 会筛选到单个 profile。每个 profile 仍会在自己的 home 下写入自己的 runtime_status.json,因此现有的按 profile 读取方式继续有效。
哪些不会变化
按 profile 隔离的 .env 凭据隔离得以保留,甚至更为严格:profile 的 keys 从其自身作用域解析,绝不会合并进共享环境(这也意味着 MCP server 和 Kanban worker 等子进程只能看到自己所属 profile 的机密)。Kanban、profile 作用域内的 skills/memory/SOUL,以及模型路由,都与使用独立网关时一样按 profile 正常工作。
一次性启动、停止或重启所有网关
CLI 内置的是单 profile 的生命周期命令。若要跨所有 profile 执行操作,可将它们包在一个 shell 循环中。把下面的代码片段放入 ~/.local/bin/kopi-gateways 并对其执行 chmod +x:
#!/bin/sh
set -eu
# Add or remove profile names here as you create / delete profiles.
profiles="default coder personal-bot research"
usage() {
echo "Usage: kopi-gateways {start|stop|restart|status|list}"
}
run_for_profile() {
profile="$1"
action="$2"
if [ "$profile" = "default" ]; then
kopi gateway "$action"
else
kopi -p "$profile" gateway "$action"
fi
}
action="${1:-}"
case "$action" in
start|stop|restart|status)
for profile in $profiles; do
echo "==> $action $profile"
run_for_profile "$profile" "$action"
done
;;
list)
kopi gateway list
;;
*)
usage
exit 2
;;
esac
然后:
kopi-gateways start # start every configured profile
kopi-gateways stop # stop every configured profile
kopi-gateways restart # restart all
kopi-gateways status # status across all
kopi-gateways list # delegates to `kopi gateway list`
default profile 通过 kopi gateway <action>(不带 -p)来指定,而不是 kopi -p default gateway <action>。上面的包装脚本同时处理这两种形式。
管理单个 profile
每个 profile 都会安装的快捷命令:
coder gateway run # foreground (Ctrl-C to stop)
coder gateway start # start the managed service
coder gateway stop # stop the managed service
coder gateway restart # restart
coder gateway status # status
coder gateway install # create the LaunchAgent / systemd unit
coder gateway uninstall # remove the service file
这些命令等价于 kopi -p coder gateway <action>——当 profile 别名不在 PATH 中,或需要从脚本动态指定 profile 时很有用。
服务文件
每个 profile 都会安装自己的服务,名称各不相同,因此安装过程绝不会互相冲突:
| 平台 | 路径 |
|---|---|
| macOS | ~/Library/LaunchAgents/ai.kopi.gateway-<profile>.plist |
| Linux | ~/.config/systemd/user/kopi-gateway-<profile>.service |
默认 profile 保留原有的名称:ai.kopi.gateway.plist / kopi-gateway.service。
查看日志
每个 profile 都写入自己的日志文件:
# Default profile
tail -f ~/.kopi/logs/gateway.log
tail -f ~/.kopi/logs/gateway.error.log
# Named profile
tail -f ~/.kopi/profiles/<name>/logs/gateway.log
tail -f ~/.kopi/profiles/<name>/logs/gateway.error.log
同时流式输出所有 profile 的日志:
tail -f ~/.kopi/logs/gateway.log ~/.kopi/profiles/*/logs/gateway.log
CLI 还提供了一个结构化日志查看器:
kopi logs -f # follow default profile
kopi -p coder logs -f # follow one profile
kopi logs --help # filters, levels, JSON output
确认实际运行的是什么
kopi profile list # profiles + model + gateway state
kopi-gateways status # full status across every profile
launchctl list | grep kopi # macOS — PIDs and labels
systemctl --user list-units 'kopi-gateway-*' # Linux — units
编辑配置
每个 profile 都把自己的配置保存在各自的目录中:
~/.kopi/profiles/<name>/
├── .env # API keys, bot tokens (chmod 600)
├── config.yaml # model, provider, toolsets, gateway settings
└── SOUL.md # personality / system prompt
默认 profile 直接使用 ~/.kopi/,同样包含这三个文件。
你可以用任意编辑器编辑,或通过 CLI 编辑:
kopi config set model.model anthropic/claude-sonnet-4 # default profile
coder config set model.model openai/gpt-5 # named profile
编辑 .env 或 config.yaml 后,重启受影响的 gateway:
coder gateway restart
# or, for everything:
kopi-gateways restart
让主机保持唤醒
gateway 进程可以整天运行,但操作系统在空闲时仍会尝试休眠。有两种常见做法:
macOS —— caffeinate
caffeinate 是 macOS 内置工具,运行期间会阻止系统休眠,无需额外安装。
caffeinate -dis # block display, idle, and system sleep
caffeinate -dis -t 28800 # same, auto-exit after 8 hours
caffeinate -i -w $(cat ~/.kopi/gateway.pid) & # awake while default gateway runs
# Persistent: run in background and forget
nohup caffeinate -dis >/dev/null 2>&1 &
disown
# Inspect / stop
pmset -g assertions | grep -iE 'caffeinate|prevent|user is active'
pkill caffeinate
| Flag | 效果 |
|---|---|
-d | 阻止显示器休眠 |
-i | 阻止系统空闲休眠(默认) |
-m | 阻止磁盘休眠 |
-s | 阻止系统休眠(仅限接通电源的 Mac) |
-u | 模拟用户活动(防止屏幕锁定) |
-t N | N 秒后自动退出 |
-w P | 当 PID P 退出时退出 |
caffeinate 无法覆盖 MacBook 上由硬件触发的合盖休眠行为。
如需在合盖状态下运行,请调整"节能"/"电池"偏好设置,或使用第三方工具。
Linux —— systemd-inhibit 或 loginctl
# Inhibit suspend while a command runs
systemd-inhibit --what=idle:sleep --who=kopi --why="gateways running" \
sleep infinity &
# Allow user services to keep running after logout (recommended)
sudo loginctl enable-linger "$USER"
启用 lingering(驻留)后,你的 systemd 用户单元(包括 kopi-gateway-<profile>.service)会在 SSH 断开连接和系统重启后继续运行。
Token 冲突防护
每个 profile 在各平台上都必须使用唯一的 bot token。如果两个 profile 共用同一个 Telegram、Discord、Slack、WhatsApp 或 Signal token,第二个 gateway 将拒绝启动,并报出一个指明冲突 profile 的错误。
要进行审计:
grep -H 'TELEGRAM_BOT_TOKEN\|DISCORD_BOT_TOKEN' \
~/.kopi/.env ~/.kopi/profiles/*/.env
更新代码
kopi update 会拉取一次最新代码,并将新增的内置 skill 同步到每个 profile:
kopi update
kopi-gateways restart
用户修改过的 skill 永远不会被覆盖。
故障排查
"Could not find service in domain for user gui: 501"
你是在之前执行过 kopi gateway stop 的情况下运行了 kopi gateway start。CLI 的 stop 会执行完整的 launchctl unload,这会把服务从 launchd 的注册表中移除。CLI 在执行 start 时会捕获这个特定错误,并自动重新加载 plist(↻ launchd job was unloaded; reloading service definition)。服务会正常启动,无需修复。
崩溃后残留的 PID
如果某个 profile 的 gateway 显示 not running,但进程仍然存活:
ps -ef | grep "kopi_cli.*-p <profile>"
cat ~/.kopi/profiles/<profile>/gateway.pid
kill -TERM <pid> # graceful
kill -KILL <pid> # if that fails after a few seconds
<profile> gateway start
强制硬重置单个服务
# macOS
launchctl unload ~/Library/LaunchAgents/ai.kopi.gateway-<profile>.plist
launchctl load ~/Library/LaunchAgents/ai.kopi.gateway-<profile>.plist
# Linux
systemctl --user restart kopi-gateway-<profile>.service
健康检查
kopi doctor # default profile
kopi -p <profile> doctor # one profile