跳到主要内容

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 接受这两种形式。

授权​

默认情况下所有联系人都会被拒绝。你必须执行以下操作之一:

  1. 将 SIMPLEX_ALLOWED_USERS 设置为以逗号分隔的 contactId 列表和/或显示名称(例如 SIMPLEX_ALLOWED_USERS=4,alice 可匹配 contactId 4 或显示名称为 "alice" 的联系人),或
  2. 使用 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 批准他们。