SimpleX Chat
SimpleX Chat 是一个私密的去中心化消息平台,用户拥有自己的联系人和群组。与其他平台不同,SimpleX 不会分配持久的用户 ID —— 每个联系人都通过连接时生成的不透明内部 ID 来标识,这使其成为目前最私密的消息应用之一。
运行
kopi gateway setup并选择 SimpleX,即可获得引导式操作演示。
前提条件
- 已安装 simplex-chat CLI 并以 daemon 方式运行
- Python 包 websockets (
pip install websockets)
安装 simplex-chat
从 simplex-chat GitHub releases 页面下载最新版本:
# Linux / macOS binary
curl -L https://github.com/simplex-chat/simplex-chat/releases/latest/download/simplex-chat-ubuntu-22_04-x86_64 -o simplex-chat
chmod +x simplex-chat
SimpleX Chat 项目不为聊天客户端发布预构建的 Docker 镜像;如需在 Docker 中运行,请从 simplex-chat 仓库 从源码构建。
启动 daemon
simplex-chat -p 5225
daemon 默认在 ws://127.0.0.1:5225 上监听 WebSocket。
配置 Kopi Agent
通过设置向导
kopi gateway setup
选择 SimpleX Chat 并按照提示操作。
通过环境变量
将以下内容添加到 ~/.kopi/.env:
SIMPLEX_WS_URL=ws://127.0.0.1:5225
SIMPLEX_ALLOWED_USERS=<contact-id-1>,<contact-id-2>
SIMPLEX_HOME_CHANNEL=<contact-id>
| 变量 | 是否必需 | 说明 |
|---|---|---|
SIMPLEX_WS_URL | 是 | simplex-chat daemon 的 WebSocket URL |
SIMPLEX_ALLOWED_USERS | 建议 | 以逗号分隔的允许列表。每个条目可以是数字 contactId 或显示名称 —— 两种形式都有效。 |
SIMPLEX_ALLOW_ALL_USERS | 可选 | 设置 true 以允许所有联系人(请谨慎使用) |
SIMPLEX_AUTO_ACCEPT | 可选 | 自动接受传入的联系人请求(默认值:true) |
SIMPLEX_GROUP_ALLOWED | 可选 | bot 参与的群组 ID,以逗号分隔,或使用 * 表示任意群组。省略则完全忽略群组消息 |
SIMPLEX_HOME_CHANNEL | 可选 | 用于 cron 任务投递的默认联系人/群组 ID |
SIMPLEX_HOME_CHANNEL_NAME | 可选 | 主频道的人类可读标签 |
KOPI_SIMPLEX_TEXT_BATCH_DELAY | 可选 | 静默期秒数(默认值:0.8),用于将连续快速传入的文本消息合并为一个事件 |
查找你的联系人 ID 或显示名称
启动 daemon 后,与你的 agent 联系人打开一个会话。数字 contactId 会出现在会话日志中。如果你更愿意使用 SimpleX 界面中显示的名称,同样可以 —— SIMPLEX_ALLOWED_USERS 接受这两种形式。
授权
默认情况下所有联系人都会被拒绝。你必须执行以下操作之一:
- 将
SIMPLEX_ALLOWED_USERS设置为以逗号分隔的contactId列表和/或显示名称(例如SIMPLEX_ALLOWED_USERS=4,alice可匹配 contactId 4 或显示名称为 "alice" 的联系人),或 - 使用 DM pairing —— 向 bot 发送任意消息,它会回复一个配对码。通过
kopi pairing approve simplex <CODE>输入该配对码。
群聊
默认情况下,适配器会忽略群组消息 —— 否则群组中的 bot 会处理每个成员的通信内容。请显式选择启用:
SIMPLEX_GROUP_ALLOWED=12,34 # specific group IDs
# or
SIMPLEX_GROUP_ALLOWED=* # any group the bot is in
通过在 chat ID 前加上 group: 前缀来指定群组,例如
simplex:group:12 可作为 cron deliver= 目标或用于 kopi send 调用。
附件
适配器在双向均支持 SimpleX 原生附件:
- 入站 —— 传入的图片、语音消息和文件通过
daemon 的 XFTP 流程接收(
rcvFileDescrReady→/freceive→ 等待rcvFileComplete),并以MessageEvent.media_urls形式呈现,附带 相应的MessageType(PHOTO、VOICE、TEXT+ document)。 - 出站 ——
send_image_file、send_voice、send_document和send_video均使用带filePath的结构化/_send形式,因此 接收方的 SimpleX 客户端会内联渲染图片并内联播放语音 消息,而不是将其作为下载文件提供。
Agent 回复还可以在纯文本中嵌入 MEDIA:/path/to/file 标签 ——
适配器会从正文中去除该标签,并将文件作为语音消息(音频扩展名)或文档发送。
在 cron 任务中使用 SimpleX
cronjob(
action="create",
schedule="every 1h",
deliver="simplex", # uses SIMPLEX_HOME_CHANNEL
prompt="Check for alerts and summarise."
)
或者通过 cron 任务的 deliver: 字段指定特定联系人,也可以在 shell 脚本中使用 kopi send CLI:
kopi send simplex:<contact-id> "Done!"
隐私说明
- SimpleX 从不泄露电话号码或电子邮件地址 —— 联系人使用不透明 ID
- Kopi Agent 与 daemon 之间的连接是本地 WebSocket (
ws://127.0.0.1:5225) —— 数据不会离开你的机器 - 消息在到达 daemon 之前已由 SimpleX 协议进行端到端加密
故障排查
"Cannot reach daemon" —— 确保 simplex-chat -p 5225 正在运行,且端口与 SIMPLEX_WS_URL 匹配。
"websockets not installed" —— 运行 pip install websockets。
Messages not received —— 检查该联系人的 ID 是否在 SIMPLEX_ALLOWED_USERS 中,或通过 DM pairing 批准他们。