Matrix 设置
KOPI AI AGENT 与 Matrix 集成,Matrix 是一种开放的、支持联邦的即时通讯协议。Matrix 让你可以运行自己的 homeserver,也可以使用 matrix.org 这样的公共服务器——无论哪种方式,你都能掌控自己的通信。机器人通过 mautrix Python SDK 连接,通过 KOPI AI AGENT pipeline 处理消息(包括工具使用、记忆和推理),并实时响应。它支持文本、文件附件、图片、音频、视频,以及可选的端到端加密(E2EE)。
Kopi Agent 可与任何 Matrix homeserver 配合使用——Synapse、Conduit、Dendrite 或 matrix.org。
在开始设置之前,先说说大多数人最想知道的部分:Kopi Agent 连接后的行为表现。
Kopi Agent 的行为表现
| 场景 | 行为 |
|---|---|
| 私聊(DM) | Kopi Agent 会响应每条消息,无需 @mention。每个私聊都有独立的 session。设置 MATRIX_DM_MENTION_THREADS=true,可在机器人在私聊中被 @mentioned 时开启 thread。 |
| 房间 | 默认情况下,Kopi Agent 需要 @mention 才会响应。设置 MATRIX_REQUIRE_MENTION=false,或将房间 ID 添加到 MATRIX_FREE_RESPONSE_ROOMS,即可获得自由响应的房间。房间邀请会被自动接受。 |
| Thread | Kopi Agent 支持 Matrix thread(MSC3440)。如果你在 thread 中回复,Kopi Agent 会将该 thread 的上下文与主房间时间线隔离。机器人已参与过的 thread 无需 @提及即可响应。 |
| 自动创建 thread | 默认情况下,Kopi Agent 会在房间中为它响应的每条消息自动创建一个 thread,从而保持对话相互隔离。设置 MATRIX_AUTO_THREAD=false 可禁用此功能。设置 MATRIX_DM_AUTO_THREAD=true(默认为 false)可为私聊消息也自动创建 thread——这与 MATRIX_DM_MENTION_THREADS 不同,后者仅在机器人在私聊中被 @mentioned 时才开启 thread。 |
| 命令 | 当你的 Matrix 客户端发送普通 /commands 时,Kopi Agent 会接受它们。如果你的客户端将 / 保留用于本地命令,请改用 !commands;Kopi Agent 会将已知的 !command 别名规范化为 /command。 |
| 交互式控制 | 危险命令审批和 /model 选择可以使用 Matrix reactions。审批 reaction 可以限制为仅发起该操作的用户可用。 |
| 思考与工具活动 | 当启用 gateway 进度显示时,Matrix 使用带 thread 的、可编辑的思考/工具活动面板,因此更新不会刷屏主房间时间线。 |
| 多用户共享房间 | 默认情况下,Kopi Agent 会在房间内按用户隔离 session 历史。同一房间中的两个人不会共享同一份对话记录,除非你明确禁用该隔离。 |
机器人在被邀请时会自动加入房间。只需将机器人的 Matrix 用户邀请到任意房间,它就会加入并开始响应。
Capability Matrix(能力矩阵)
下表基于 Matrix adapter(适配器)的能力声明和 Matrix 测试覆盖率整理而成。E2EE 采用基于模式的方式,因为各部署环境可自行选择禁用加密房间、机会性加密或强制加密。
| Capability(能力) | Matrix |
|---|---|
| text(文本) | yes |
| threads(话题线程) | yes |
| reactions(表情回应) | yes |
| approvals(审批) | yes |
| model picker(模型选择器) | yes |
| thinking panes(思考面板) | yes |
| images(图片) | yes |
| multiple images(多图片) | yes |
| files(文件) | yes |
| voice/audio(语音/音频) | yes |
| video(视频) | yes |
| E2EE | off / optional / required(关闭 / 可选 / 必须) |
| diagnostics(诊断) | yes |
Session Model in Matrix(Matrix 中的会话模型)
默认情况下:
- 每个 DM(私聊)拥有独立的会话
- 每个 thread(话题线程)拥有独立的会话命名空间
- 共享房间中的每个用户在该房间内拥有各自的会话
这由 config.yaml 控制:
group_sessions_per_user: true
仅当你明确希望整个房间共享一个对话时,才将其设置为 false:
group_sessions_per_user: false
共享会话在协作型房间中可能很有用,但同时意味着:
- 用户共享上下文增长和 token 成本
- 一个人的长时间、重度工具调用任务可能让其他所有人的上下文膨胀
- 一个人正在进行的运行可能会中断同一房间中另一个人的后续消息
Mention and Threading Configuration(提及与自动开线程配置)
你可以通过环境变量或 config.yaml 配置提及和自动开线程行为:
matrix:
require_mention: true # Require @mention in rooms (default: true)
allowed_users: # Matrix users allowed to trigger agent turns
- "@alice:matrix.org"
allowed_rooms: # Matrix rooms allowed to trigger agent turns
- "!abc123:matrix.org"
free_response_rooms: # Rooms exempt from mention requirement
- "!abc123:matrix.org"
ignore_user_patterns: # Bridge/appservice ghost users to ignore
- "^@telegram_"
- "^@whatsapp_"
process_notices: false # Ignore m.notice by default
session_scope: room # auto|room|thread; room is recommended for project rooms
auto_thread: true # Auto-create threads for responses (default: true)
dm_mention_threads: false # Create thread when @mentioned in DM (default: false)
或者通过环境变量:
MATRIX_REQUIRE_MENTION=true
MATRIX_ALLOWED_USERS=@alice:matrix.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.org
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@whatsapp_'
MATRIX_PROCESS_NOTICES=false
MATRIX_SESSION_SCOPE=room # recommended for stable project-room context
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true # default: true — emoji reactions during processing
MATRIX_ALLOW_ROOM_MENTIONS=false
MATRIX_REACTIONS=false 会关闭 bot 在收到消息时发布的处理生命周期 emoji 表情回应(👀/✅/❌)。适用于表情回应事件噪音较大或并非所有参与客户端都支持的房间。
Kopi Agent 会为明确的 Matrix ID(例如 @alice:example.org)发送结构化的 Matrix 用户提及。房间级 @room 通知默认处于禁用状态;仅在允许 bot 通知所有人的房间中才设置 MATRIX_ALLOW_ROOM_MENTIONS=true。
如果你是从一个尚不具备 MATRIX_REQUIRE_MENTION 的版本升级而来,此前 bot 会响应房间中的所有消息。若要保留该行为,请设置 MATRIX_REQUIRE_MENTION=false。
Project Room Isolation(项目房间隔离)
如果你在多个项目房间中使用同一个 Matrix bot,请配置稳定的房间级会话:
MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=false
MATRIX_SESSION_SCOPE 接受以下值:
| Scope(作用域) | Behavior(行为) |
|---|---|
auto | 向后兼容的默认值。现有的 MATRIX_AUTO_THREAD 行为控制合成的 thread(话题线程)。 |
room | 非 thread 的房间消息保持在同一个稳定的房间会话中。真实的 Matrix thread 仍使用其 thread 根节点。 |
thread | 非 thread 的房间消息会根据触发事件 ID 合成一个 thread/会话。 |
Kopi Agent 现在会在 agent prompt 中包含当前的 Matrix 房间名称、房间 ID、主题、消息 ID,以及一条 Matrix 房间边界说明。/status 还会显示当前的 Matrix 房间/会话作用域,而 /resume 不会静默地从另一个 Matrix 房间恢复命名会话,除非你明确使用 /resume --cross-room <session name>。
MATRIX_SESSION_SCOPE=room 控制房间/thread 通道。现有的 group_sessions_per_user 设置仍控制该房间内的用户是否共享该通道。在 group_sessions_per_user: true(默认)下,Alice 和 Bob 会获得各自的 Project B 会话。在 group_sessions_per_user: false 下,该房间共享一份 Project B 记录。
本指南将带你完成完整的设置流程 — 从创建 bot 账户到发送你的第一条消息。
Step 1: Create a Bot Account(第 1 步:创建 bot 账户)
你需要一个用于 bot 的 Matrix 用户账户。有几种方式可以完成:
Option A: Register on Your Homeserver (Recommended)(选项 A:在你的 homeserver 上注册(推荐))
如果你运行自己的 homeserver(Synapse、Conduit、Dendrite):
- 使用 admin API 或注册工具创建一个新用户:
# Synapse example
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
- 选择一个类似
kopi的用户名 — 完整的 user ID 将是@hermes:your-server.org。
Option B: Use matrix.org or Another Public Homeserver(选项 B:使用 matrix.org 或其他公共 homeserver)
- 前往 Element Web 并创建一个新账户。
- 为你的 bot 选择一个用户名(例如
kopi-bot)。
Option C: Use Your Own Account(选项 C:使用你自己的账户)
你也可以以你自己的用户身份运行 Kopi Agent。这意味着 bot 以你的身份发帖 — 适合个人助理场景。
Step 2: Get an Access Token(第 2 步:获取 access token)
Kopi Agent 需要一个 access token 来与 homeserver 进行身份验证。你有两个选择:
Option A: Access Token (Recommended)(选项 A:access token(推荐))
获取 token 最可靠的方式:
Via Element(通过 Element):
- 使用 bot 账户登录 Element。
- 前往 Settings → Help & About。
- 向下滚动并展开 Advanced — access token 就显示在这里。
- 立即复制它。
Via the API(通过 API):
curl -X POST https://your-server/_matrix/client/v3/login \
-H "Content-Type: application/json" \
-d '{
"type": "m.login.password",
"user": "@hermes:your-server.org",
"password": "your-password"
}'
响应中包含一个 access_token 字段 — 复制它。
access token 可以完全访问 bot 的 Matrix 账户。切勿公开分享它或将其提交到 Git。如果泄露,请通过登出该用户的所有会话来撤销它。
Option B: Password Login(选项 B:密码登录)
除了提供 access token,你也可以向 Kopi Agent 提供 bot 的 user ID 和密码。Kopi Agent 会在启动时自动登录。这种方式更简单,但意味着密码会存储在你的 .env 文件中。
MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-password
Step 3: Find Your Matrix User ID(第 3 步:找到你的 Matrix User ID)
KOPI AI AGENT 使用你的 Matrix User ID 来控制谁可以与 bot 交互。Matrix User ID 的格式为 @username:server。
找到你的 ID:
- 打开 Element(或你偏好的 Matrix 客户端)。
- 点击你的头像 → Settings。
- 你的 User ID 显示在个人资料顶部(例如
@alice:matrix.org)。
Matrix User ID 始终以 @ 开头,包含一个 :,其后是服务器名称。例如:@alice:matrix.org、@bob:your-server.com。
Step 4: Configure KOPI AI AGENT(第 4 步:配置 KOPI AI AGENT)
Option A: Interactive Setup (Recommended)(选项 A:交互式设置(推荐))
运行引导式设置命令:
kopi gateway setup
出现提示时选择 Matrix,然后按提示提供你的 homeserver URL、access token(或 user ID + 密码)以及允许的 user ID。
Option B: Manual Configuration(选项 B:手动配置)
将以下内容添加到你的 ~/.kopi/.env 文件中:
Using an access token(使用 access token):
# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***
# Optional: user ID (auto-detected from token if omitted)
# MATRIX_USER_ID=@hermes:matrix.example.org
# Security: restrict who can interact with the bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org
# Optional: restrict which rooms can trigger the bot
MATRIX_ALLOWED_ROOMS=!abc123:matrix.example.org
# Multiple allowed users (comma-separated)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org
Using password login(使用密码登录):
# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***
# Security
MATRIX_ALLOWED_USERS=@alice:matrix.example.org
私有部署加固
对于私有的 Matrix 部署,请同时设置用户和房间允许列表。如果
MATRIX_ALLOWED_USERS 未设置,任何能在已加入房间中联系到 bot 的发送者都可以触发 agent 执行轮次。如果
MATRIX_ALLOWED_ROOMS 未设置,bot 加入的任何房间都可以触发 agent 执行轮次。一个严格锁定的部署应同时设置两者:
MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org
MATRIX_ALLOWED_ROOMS=!ops:matrix.example.org,!dmroom:matrix.example.org
Bridge 和 appservice 部署需要额外的循环防护。Kopi Agent 默认会忽略自身事件、本地部分以 _ 开头的 Matrix appservice 风格用户、重复的 event ID、旧的启动事件、编辑替换事件以及 m.notice 事件。当你的 bridge 使用不同的命名约定时,请添加特定于部署的 bridge ghost 模式:
MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@slack_,^@whatsapp_'
只有在受信任的人工工作流确实会发送 m.notice 时,才启用 notice:
MATRIX_PROCESS_NOTICES=true
出站的全房间通知默认处于禁用状态。除非明确允许 bot 使用 @room 唤醒整个房间,否则请保持 MATRIX_ALLOW_ROOM_MENTIONS=false 不变。
诊断和调试负载会脱敏处理 Matrix access token、recovery key、设备标识符和消息正文。媒体下载仅限于 Matrix mxc:// content URI,且在超出 MATRIX_MAX_MEDIA_BYTES 时会被拒绝。请将联邦房间和不受信任的 homeserver 视为不受信任的输入:保持房间允许列表严格收紧,在涉及大量工具调用的工作中优先使用 DM 或私有房间,并避免将 bridge ghost 或 appservice puppet 授权为允许的用户。
~/.kopi/config.yaml 中的可选行为设置:
group_sessions_per_user: true
group_sessions_per_user: true在共享房间中隔离每位参与者的上下文
启动 Gateway
配置完成后,启动 Matrix gateway:
kopi gateway
bot 应在几秒内连接到你的 homeserver 并开始同步。向它发送一条消息——无论是 DM 还是在它已加入的房间中——以进行测试。
你可以在后台运行 kopi gateway,或将其作为 systemd 服务运行以实现持久化操作。详情请参阅部署文档。
端到端加密(E2EE)
Kopi Agent 支持 Matrix 端到端加密,因此你可以在加密房间中与你的 bot 聊天。
前提条件
E2EE 需要带加密扩展(encryption extras)的 mautrix 库以及 libolm C 库:
# Install mautrix with E2EE support
pip install 'mautrix[encryption]'
# Or install with kopi extras
cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[matrix]"
你还需要在系统上安装 libolm:
# Debian/Ubuntu
sudo apt install libolm-dev
# macOS
brew install libolm
# Fedora
sudo dnf install libolm-devel
启用 E2EE
将以下内容添加到你的 ~/.kopi/.env:
MATRIX_E2EE_MODE=required
MATRIX_E2EE_MODE 接受:
| 模式 | 行为 |
|---|---|
off | 不初始化 Matrix E2EE。 |
optional | 在依赖项可用时尝试 E2EE,但如果加密无法初始化,则保持未加密房间正常工作。 |
required | 如果 E2EE 依赖项或加密设置不可用,则采用 fail closed 策略(终止并拒绝服务)。 |
可选模式(optional)在加密设置不可用时可能会回退到非 E2EE 操作。必需模式(required)则会采用 fail closed 策略,而不是静默降级。
为了向后兼容,MATRIX_ENCRYPTION=true 仍然会启用必需的 E2EE 行为。
启用 E2EE 后,Kopi Agent 会:
- 将加密密钥存储在
~/.kopi/platforms/matrix/store/(旧版安装位置:~/.kopi/matrix/store/)中 - 首次连接时上传设备密钥
- 自动解密传入消息并加密传出消息
- 受邀时自动加入加密房间
Matrix 工具与控制
在 Matrix 对话中,Kopi Agent 会向 agent 暴露 Matrix 特有的工具:
matrix_send_reactionmatrix_redact_messagematrix_create_roommatrix_invite_usermatrix_fetch_historymatrix_set_presence
这些工具的作用域限定在 Matrix 上下文中,在非 Matrix 工具集中不可用。管理类工具默认禁用:撤回(redaction)需要 MATRIX_TOOLS_ALLOW_REDACTION=true,邀请需要 MATRIX_TOOLS_ALLOW_INVITES=true,创建房间需要 MATRIX_TOOLS_ALLOW_ROOM_CREATE=true。创建公共房间还需要 MATRIX_ALLOW_PUBLIC_ROOMS=true。
Matrix 工具默认仅限于当前 Matrix 房间。显式指定的跨房间目标需要 MATRIX_TOOLS_ALLOW_CROSS_ROOM=true;撤回和邀请类跨房间操作还需要 MATRIX_TOOLS_ALLOW_CROSS_ROOM_DESTRUCTIVE=true。如果设置了 MATRIX_ALLOWED_ROOMS,Matrix 工具只能以这些房间为目标。
Reaction 控制使用:
- ✅ 批准一次
- ♾️ 总是批准
- ❌ 拒绝
- 数字 reaction 用于
/model选项
如果你有意想让房间中的任何已授权 Matrix 用户操作批准/模型选择提示,请设置 MATRIX_APPROVAL_REQUIRE_SENDER=false。当 Kopi Agent 知道是谁发起该操作时,默认为与请求者绑定。
媒体限制
Kopi Agent 通过 Matrix 媒体 API 上传和下载 Matrix 图片、文件、音频和视频。多张生成的图片会作为单个有序的逻辑批次发送,并在批次中保留说明文字和话题上下文。
默认情况下,超过 100 MB 的 Matrix 媒体会在上传/下载前被拒绝。可通过以下方式覆盖此限制:
MATRIX_MAX_MEDIA_BYTES=104857600
传入媒体必须使用 Matrix mxc:// content URI。Kopi Agent 会拒绝 Matrix 事件中的任意 HTTP(S) 媒体 URL,以避免将联邦房间变成不受限制的下载器。
Synapse 集成测试
Kopi Agent 包含一个可选启用的 Synapse 测试工具,用于本地验证:
docker compose -f tests/e2e/matrix_synapse_gateway/docker-compose.yml up -d
KOPI_MATRIX_SYNAPSE_INTEGRATION=1 \
scripts/run_tests.sh -m "integration and matrix_synapse" \
tests/e2e/matrix_synapse_gateway/test_gateway.py
docker compose -f tests/e2e/matrix_synapse_gateway/docker-compose.yml down -v
该工具通过 Synapse 的 shared-secret 注册方式创建临时用户,覆盖私密房间的发送/接收、具名房间的邀请/加入、媒体上传/下载、bot 响应投递,以及启动时的旧事件过滤。E2EE 冒烟测试覆盖单独标记为 matrix_e2ee,以便在开发者机器上保持可选启用。
交叉签名验证(推荐)
如果你的 Matrix 账户启用了交叉签名(Element 中的默认设置),请设置恢复密钥,以便 bot 在启动时能自行对其设备签名。否则,在设备密钥轮换后,其他 Matrix 客户端可能拒绝与 bot 共享加密会话。
MATRIX_RECOVERY_KEY=EsT... your recovery key here
在哪里找到它: 在 Element 中,前往 Settings(设置)→ Security & Privacy(安全与隐私)→ Encryption(加密)→ 你的恢复密钥(也称为 "Security Key")。这就是你首次设置交叉签名时被要求保存的密钥。
每次启动时,如果设置了 MATRIX_RECOVERY_KEY,Kopi Agent 会从 homeserver 的安全密钥存储中导入交叉签名密钥并对当前设备签名。此操作是幂等的,可以安全地永久启用。
如果 Kopi Agent 引导生成了新的 Matrix 恢复密钥,它绝不会记录原始密钥。在启动前设置 MATRIX_RECOVERY_KEY_OUTPUT_FILE=/secure/path/matrix-recovery-key.txt,即可将生成的密钥一次性写入文件,文件权限模式为 0600;如果文件已存在则不会被覆盖。
如果你删除 ~/.kopi/platforms/matrix/store/crypto.db,bot 将丢失其加密身份。仅使用相同设备 ID 重启不会完全恢复——homeserver 仍持有用旧身份密钥签名的一次性密钥,对端无法建立新的 Olm 会话。
Kopi Agent 会在启动时检测到此情况并拒绝启用 E2EE,同时记录日志:device XXXX has stale one-time keys on the server signed with a previous identity key。
最简单的恢复方式:生成新的 access token(这样会获得一个全新的设备 ID,没有任何过期的密钥历史)。参见下文的“从启用了 E2EE 的旧版本升级”一节。这是最可靠的路径,并且无需触碰 homeserver 数据库。
手动恢复(高级用法——保留相同的设备 ID):
-
停止 Synapse 并从其数据库中删除旧设备:
sudo systemctl stop matrix-synapse
sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "
DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
"
sudo systemctl start matrix-synapse或者通过 Synapse 管理 API(注意 URL 编码的用户 ID):
curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID'注意:通过管理 API 删除设备也可能使关联的 access token 失效。之后你可能需要生成新的 token。
-
删除本地加密存储并重启 Kopi Agent:
rm -f ~/.kopi/platforms/matrix/store/crypto.db*
# restart kopi
其他 Matrix 客户端(Element、matrix-commander)可能会缓存旧的设备密钥。恢复后,在 Element 中输入 /discardsession 以强制与 bot 建立新的加密会话。
如果未安装 mautrix[encryption] 或缺少 libolm,bot 会自动回退到普通(未加密)客户端。你会在日志中看到一条警告。
主房间
你可以指定一个"主房间"(home room),bot 会在其中发送主动消息(例如定时任务输出、提醒和通知)。有两种设置方式:
使用斜杠命令
在 bot 所在的任意 Matrix 房间中输入 /sethome。该房间即成为主房间。
如果你的 Matrix 客户端会拦截斜杠命令,请改为输入 !sethome。
手动配置
将以下内容添加到你的 ~/.kopi/.env:
MATRIX_HOME_ROOM=!abc123def456:matrix.example.org
房间允许列表(allowed_rooms)
将 bot 限制在一组固定的 Matrix 房间中。设置后,bot 只在 ID 出现在列表中的房间内响应——其他任何房间的消息都会被静默忽略,即使消息中提到了 bot 也一样。
私聊(直接聊天房间)不受此过滤器限制,因此获得授权的用户始终可以与 bot 一对一联系。
matrix:
allowed_rooms:
- "!abc123def456:matrix.example.org"
- "!opsroom789:matrix.example.org"
或通过环境变量(逗号分隔)设置:
MATRIX_ALLOWED_ROOMS="!abc123def456:matrix.example.org,!opsroom789:matrix.example.org"
行为:
- 为空 / 未设置 → 不做限制(默认)。
- 非空 → 房间 ID 必须在列表中。此检查在任何其他门控(提及要求、发送者允许列表等)之前运行。
- 请使用房间的内部 ID(
!abc...:server),而不是其别名(#room:server)。你可以在 Element 中通过 Room → Settings → Advanced 找到房间的内部 ID。
另请参阅:admin/user slash command split。
要查找 Room ID:在 Element 中,进入该房间 → Settings(设置)→ Advanced(高级)→ 其中显示的 Internal room ID(内部房间 ID)即为所求(以 ! 开头)。
Matrix 中的命令
Kopi Agent 在 Matrix 中支持与其他消息平台相同的网关命令,包括 /commands、/model、/stop、/queue、/steer、/goal、/subgoal、/background、/bg、/btw、/tasks 和 /yolo。
某些 Matrix 客户端会将开头的 / 保留用于本地客户端命令,可能不会将未知的斜杠命令发送到房间。在这种情况下,请使用 ! 作为 Matrix 兼容的别名:
!commands
!model
!model gpt-5.5 --provider openrouter
!queue continue with the next task
!stop
Kopi Agent 仅在命令属于网关已知命令、已注册的 plugin 命令或已安装的 skill 命令时,才会规范化 !command。普通的感叹语句(例如 !important)仍作为普通聊天消息处理。
故障排查
机器人不响应消息
原因:机器人尚未加入房间,MATRIX_ALLOWED_USERS 中未包含你的 User ID,MATRIX_ALLOWED_ROOMS 中未包含该房间,或者房间消息中没有提及(mention)机器人。
修复:邀请机器人加入房间 —— 被邀请后它会自动加入。确认你的 User ID 位于 MATRIX_ALLOWED_USERS 中(使用完整的 @user:server 格式),如果配置了该白名单,还需确认房间 ID 位于 MATRIX_ALLOWED_ROOMS 中。在房间中提及机器人,或将该房间添加到 MATRIX_FREE_RESPONSE_ROOMS。重启网关。
机器人加入了房间但静默丢弃所有消息(时钟偏移)
原因:主机的系统时钟被设置得超前于真实时间。Matrix 适配器会应用 5 秒的启动宽限过滤(event_ts < startup_ts - 5),以忽略初始同步时重放的事件。当系统时钟超前时,每个传入事件看起来都"早于启动时刻",因此在到达消息处理器之前就被丢弃 —— 机器人看起来已连接,但从不回复。参见 #12614。
症状:网关日志显示 Matrix: dropped N live events as 'too old' more than 30s after startup。
修复:使用 NTP 同步主机时钟并重启机器人:
# Debian/Ubuntu
sudo timedatectl set-ntp true
timedatectl status # confirm "System clock synchronized: yes"
# macOS
sudo sntp -sS time.apple.com
启动时出现 "Failed to authenticate" / "whoami failed"
原因:access token 或 homeserver URL 不正确。
修复:确认 MATRIX_HOMESERVER 指向你的 homeserver(包含 https://,末尾不带斜杠)。检查 MATRIX_ACCESS_TOKEN 是否有效 —— 用 curl 试一下:
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://your-server/_matrix/client/v3/account/whoami
如果返回了你的用户信息,说明 token 有效。如果返回错误,则需要生成一个新 token。
"mautrix not installed" 错误
原因:未安装 mautrix Python 包。
修复:安装它:
pip install 'mautrix[encryption]'
或者使用 Kopi Agent extras:
cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[matrix]"
加密错误 / "could not decrypt event"
原因:缺少加密密钥、未安装 libolm,或机器人的设备未被信任。
修复:
- 确认你的系统上已安装
libolm(参见上文的 E2EE 部分)。 - 确认在你的
.env中设置了MATRIX_ENCRYPTION=true。 - 在你的 Matrix 客户端(Element)中,进入机器人的个人资料 -> Sessions -> 验证/信任机器人的设备。
- 如果机器人刚刚加入一个加密房间,它只能解密它加入之后发送的消息。更早的消息无法访问。
从使用 E2EE 的旧版本升级
如果你还手动删除了 crypto.db,请参阅上文 E2EE 部分中"删除 crypto store"的警告 —— 清除 homeserver 中的过期一次性密钥(one-time keys)还需要额外的步骤。
如果你之前使用 Kopi Agent 的 MATRIX_ENCRYPTION=true,现在升级到使用基于 SQLite 的新 crypto store 的版本,机器人的加密身份已发生变化。你的 Matrix 客户端(Element)可能缓存了旧的设备密钥,并拒绝与机器人共享加密会话。
症状:机器人可以连接,并在日志中显示 "E2EE enabled",但所有消息都显示 "could not decrypt event",机器人从不响应。
发生了什么:旧的加密状态(来自之前的 matrix-nio 或基于序列化的 mautrix 后端)与新的 SQLite crypto store 不兼容。机器人会创建一个全新的加密身份,但你的 Matrix 客户端仍然缓存着旧密钥,并且不会与密钥已更改的设备共享房间的加密会话。这是 Matrix 的一项安全特性 —— 客户端会将同一设备的 identity key 变更视为可疑行为。
修复(一次性迁移):
-
生成新的 access token 以获得全新的 device ID。最简单的方法:
curl -X POST https://your-server/_matrix/client/v3/login \
-H "Content-Type: application/json" \
-d '{
"type": "m.login.password",
"identifier": {"type": "m.id.user", "user": "@hermes:your-server.org"},
"password": "***",
"initial_device_display_name": "KOPI AI AGENT"
}'复制新的
access_token并更新~/.kopi/.env中的MATRIX_ACCESS_TOKEN。 -
删除旧的加密状态:
rm -f ~/.kopi/platforms/matrix/store/crypto.db
rm -f ~/.kopi/platforms/matrix/store/crypto_store.* -
设置你的 recovery key(如果你使用 cross-signing —— 大多数 Element 用户都会使用)。添加到
~/.kopi/.env:MATRIX_RECOVERY_KEY=EsT... your recovery key here这能让机器人在启动时使用 cross-signing 密钥自行签名,从而使 Element 立即信任新设备。如果不这样做,Element 可能会将新设备视为未验证,并拒绝共享加密会话。你可以在 Element 的 Settings → Security & Privacy → Encryption 中找到你的 recovery key。
-
强制你的 Matrix 客户端轮换加密会话。在 Element 中,打开与机器人的私聊房间,输入
/discardsession。这会强制 Element 创建新的加密会话,并将其共享给机器人的新设备。 -
重启网关:
kopi gateway run如果设置了
MATRIX_RECOVERY_KEY,你应该会在日志中看到Matrix: cross-signing verified via recovery key。 -
发送一条新消息。机器人应当能正常解密并响应。
迁移完成后,升级之前发送的消息无法被解密 —— 旧的加密密钥已经不存在了。这只会影响过渡阶段;新消息可以正常工作。
全新安装不受影响。 只有当你之前已有基于 Kopi Agent 旧版本的可用 E2EE 配置并进行升级时,才需要执行此迁移。
为什么要新的 access token? 每个 Matrix access token 都绑定到特定的 device ID。在新的加密密钥下重复使用相同的 device ID,会导致其他 Matrix 客户端不信任该设备(它们会将 identity key 的变更视为潜在的安全威胁)。新的 access token 会获得一个全新的 device ID,不带有任何过期的密钥历史记录,因此其他客户端会立即信任它。
代理模式(macOS 上的 E2EE)
Matrix E2EE 需要 libolm,而它无法在 macOS ARM64(Apple Silicon)上编译。kopi-ai-agent[matrix] extra 仅限 Linux 平台。如果你使用 macOS,代理模式可以让你在 Linux 虚拟机的 Docker 容器中运行 E2EE,而实际的 agent 则在 macOS 上原生运行,并完整访问你的本地文件、内存和 skills。
工作原理
macOS (Host):
└─ kopi gateway
├─ api_server adapter ← listens on 0.0.0.0:8642
├─ AIAgent ← single source of truth
├─ Sessions, memory, skills
└─ Local file access (Obsidian, projects, etc.)
Linux VM (Docker):
└─ kopi gateway (proxy mode)
├─ Matrix adapter ← E2EE decryption/encryption
└─ HTTP forward → macOS:8642/v1/chat/completions
(no LLM API keys, no agent, no inference)
Docker 容器只处理 Matrix 协议 + E2EE。当消息到达时,容器会解密它并通过标准 HTTP 请求将文本转发给主机。主机运行 agent、调用工具、生成响应并将其流式传回。容器随后加密该响应并发送到 Matrix。所有会话都是统一的——CLI、Matrix、Telegram 以及任何其他平台都共享相同的内存和对话历史。
第 1 步:配置主机(macOS)
启用 API server,使主机能够接收来自 Docker 容器的传入请求。
添加到 ~/.kopi/.env:
API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0
API_SERVER_HOST=0.0.0.0绑定到所有网络接口,以便 Docker 容器能够访问它。API_SERVER_KEY对于非回环绑定是必需的。请使用一个足够强的随机字符串。- API server 默认运行在端口 8642 上(如需更改,可使用
API_SERVER_PORT)。
启动 gateway:
kopi gateway
你应该会看到 API server 与你配置的其他平台一起启动。验证它能从虚拟机访问:
# From the Linux VM
curl http://<mac-ip>:8642/health
第 2 步:配置 Docker 容器(Linux 虚拟机)
容器需要 Matrix 凭据和代理 URL。它不需要 LLM API key。
docker-compose.yml:
services:
kopi-matrix:
build: .
environment:
# Matrix credentials
MATRIX_HOMESERVER: "https://matrix.example.org"
MATRIX_ACCESS_TOKEN: "syt_..."
MATRIX_ALLOWED_USERS: "@you:matrix.example.org"
MATRIX_ENCRYPTION: "true"
MATRIX_DEVICE_ID: "KOPI_BOT"
# Proxy mode — forward to host agent
GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
GATEWAY_PROXY_KEY: "your-secret-key-here"
volumes:
- ./matrix-store:/root/.kopi/platforms/matrix/store
Dockerfile:
FROM python:3.11-slim
RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[matrix]"
CMD ["hermes", "gateway"]
这就是整个容器。不需要 OpenRouter、Anthropic 或任何推理 provider(服务提供商)的 API key。
第 3 步:启动两者
-
先启动主机 gateway:
kopi gateway -
启动 Docker 容器:
docker compose up -d -
在加密的 Matrix 房间中发送消息。容器会解密消息,转发给主机,并将响应流式传回。
配置参考
代理模式在容器端(轻量 gateway)进行配置:
| 设置项 | 描述 |
|---|---|
GATEWAY_PROXY_URL | 远程 Kopi Agent API server 的 URL(例如 http://192.168.1.100:8642) |
GATEWAY_PROXY_KEY | 用于身份验证的 Bearer token(必须与主机上的 API_SERVER_KEY 一致) |
gateway.proxy_url | 与 GATEWAY_PROXY_URL 相同,但在 config.yaml 中 |
主机端需要:
| 设置项 | 描述 |
|---|---|
API_SERVER_ENABLED | 设置为 true |
API_SERVER_KEY | Bearer token(与容器共享) |
API_SERVER_HOST | 设置为 0.0.0.0 以启用网络访问 |
API_SERVER_PORT | 端口号(默认:8642) |
适用于任何平台
代理模式不仅限于 Matrix。任何平台 adapter 都可以使用它——在任意 gateway 实例上设置 GATEWAY_PROXY_URL,它就会转发到远程 agent,而不在本地运行 agent。当平台 adapter 需要与 agent 在不同环境中运行时(网络隔离、E2EE 要求、资源限制),此功能非常有用。
会话连续性通过 X-Kopi Agent-Session-Id header 维护。主机的 API server 根据该 ID 跟踪会话,因此对话会像本地 agent 一样在各条消息之间保持连续。
限制(v1): 远程 agent 的工具进度消息不会转发回来——用户只能看到流式传输的最终响应,而看不到各个工具调用。危险命令的审批提示在主机端处理,不会转发给 Matrix 用户。这些问题可在后续更新中解决。
Bot 能连接并发送消息,但忽略接收的消息
原因:只有当同步负载通过 mautrix 的 handle_sync() 机制分发时,Matrix 事件处理器才会触发。一个从未调用 handle_sync() 的原始 client.sync() 轮询可能使 adapter 保持连接状态(发送正常),但接收的消息永远不会到达 _on_room_message。
修复:Kopi Agent 使用显式同步循环,在初始同步和每个增量同步响应时都调用 client.handle_sync()。这与上游 issue #7914 和已关闭的 PR #37807 中的诊断一致,但保留了 Kopi Agent 自己的后台维护任务(已加入房间跟踪、邀请处理、E2EE 密钥共享),而不是将完整生命周期委托给 client.start()。如果重启 gateway 后接收消息仍然失败,请验证处理器是否在首次同步之前完成注册,并检查日志中的 sync event dispatch error。
同步问题 / bot 响应滞后
原因:长时间运行的工具执行可能延迟同步循环,或者 homeserver 运行缓慢。
修复:同步循环在出错时会每 5 秒自动重试。请检查 Kopi Agent 日志中的同步相关警告。如果 bot 持续滞后,请确保你的 homeserver 有足够的资源。
Bot 处于离线状态
原因:Kopi Agent gateway 未运行,或连接失败。
修复:检查 kopi gateway 是否正在运行。查看终端输出中的错误信息。常见问题包括:homeserver URL 错误、access token 过期、homeserver 无法访问。
“User not allowed” / Bot 忽略你
原因:你的 User ID 不在 MATRIX_ALLOWED_USERS 中。
修复:将你的 User ID 添加到 ~/.kopi/.env 中的 MATRIX_ALLOWED_USERS,然后重启 gateway。请使用完整的 @user:server 格式。
Bot 忽略整个房间
原因:设置了 MATRIX_ALLOWED_ROOMS 但当前房间 ID 未列入其中,或者该房间要求提及 bot 而消息中并未提及 bot。
修复:将房间 ID 添加到 MATRIX_ALLOWED_ROOMS,如果是个人部署,也可以移除房间 allowlist。要在 Element 中查找 Room ID,请打开房间设置并查看 Advanced。
桥接消息循环或重复回显
原因:某个 bridge/appservice puppet 将 bot 的输出作为新用户消息转发回来,或者某个 bridge 使用了非标准的 ghost user ID。
修复:将 bridge ghost 排除在 MATRIX_ALLOWED_USERS 之外,添加匹配的 MATRIX_IGNORE_USER_PATTERNS 条目,并保留 MATRIX_PROCESS_NOTICES=false 的设置,除非 notices 是受信任工作流的一部分。
安全性
务必设置 MATRIX_ALLOWED_USERS;对于共享/私有部署,还需设置 MATRIX_ALLOWED_ROOMS。如果不设置,任何能够在已加入的房间中向机器人发送消息的人都可能触发 agent(智能体)。只授权你信任的用户和房间 —— 被授权的用户将拥有对 agent 功能的完全访问权限,包括工具使用和系统访问。
有关保护 KOPI AI AGENT 部署安全的更多信息,请参阅安全指南。
说明
- 任意 homeserver:可与 Synapse、Conduit、Dendrite、matrix.org 或任何符合规范的 Matrix homeserver 一起使用,无需特定的 homeserver 软件。
- 联邦(Federation):如果你使用的是支持联邦的 homeserver,机器人可以与其他服务器上的用户通信 —— 只需将其完整的
@user:serverID 添加到MATRIX_ALLOWED_USERS即可。 - 自动加入:机器人会自动接受房间邀请并加入。加入后立即开始响应。
- 媒体支持:Kopi Agent 可以发送和接收图片、音频、视频以及文件附件。媒体会通过 Matrix 内容仓库 API 上传到你的 homeserver。
- 原生语音消息(MSC3245):Matrix 适配器会自动为发出的语音消息加上
org.matrix.msc3245.voice标志。这意味着 TTS 响应和语音音频会在 Element 及其他支持 MSC3245 的客户端中显示为原生气泡,而不是普通的音频文件附件。带有 MSC3245 标志的传入语音消息也会被正确识别并路由到语音转文字(speech-to-text)转录流程。无需任何配置 —— 此功能自动生效。