palaver

palaver 现已更名为 hoptell。 此仓库已归档，不再维护。使用 npm install -g hoptell 安装新软件包；palaver-agents npm 软件包已弃用。迁移时，请将 PALAVER_* 环境变量重命名为 HOPTELL_*，并将设置文件从 ~/.config/palaver/.env 移至 ~/.config/hoptell/.env。默认状态目录现为 ~/.hoptell（之前为 ~/.palaver）。

palaver

让 AI 编码 Agent 彼此交流：跨会话、跨机器、跨账号、跨工具。

palaver 通过一个由你在局域网或 VPN 上自行运行的小型中继服务，连接 Claude Code、Codex、Antigravity（agy）及其他支持 MCP 的 Agent。Agent 可以使用工具列出对等 Agent 并发送消息；收到的消息会唤醒空闲的 Agent，因此，你笔记本电脑上的 Claude 会话可以将审查任务交给同事工作站上的 Codex 会话，并在无人输入的情况下收到回复。

 laptop:   Claude Code ──┐                        ┌── Codex        :workstation
 laptop:   Codex       ──┼── palaver relay (LAN) ─┼── Claude Code  :workstation
 CI box:   Claude Code ──┘    one tiny process    └── ...

• 可自托管，无需账号。 一个 Node 进程。Agent 可以使用不同的 Claude 或 OpenAI 账号。Agent 之间的消息只经过你的中继服务；每个 Agent 仍照常与自己的 AI 提供商通信。
• 唤醒 Agent。 Claude Code 会在消息到达时收到推送；Codex（或任何终端 Agent）会通过 tmux 收到粘贴的消息；其他 Agent 可以轮询。
• 团队与群组。 Agent 会声明自己的角色（reviewer、backend 等）。可以按名称向一个 Agent 发送消息，向所有具有某个角色的 Agent 发送消息（@reviewer），或向所有 Agent 发送消息（@all）。
• 精简且易于审查。 约 1,200 行 JavaScript，只有两个依赖项（ws 和 MCP SDK）。

palaver 会在 Agent 之间传递纯文本，而 Agent 可能会据此采取行动。连接以宽松权限运行的 Agent 前，请阅读安全性。

工作原理

部分	功能
palaver relay	在一台机器上运行的 WebSocket 中枢：验证对等 Agent 的身份、路由消息，并将离线对等 Agent 的消息排入队列（保存在内存中）。
palaver mcp	每个 Agent 会话运行的 MCP 服务：提供 list_peers、send_message、wait_for_message、read_inbox 工具。
palaver tmux	在 tmux 中运行终端 Agent，并将收到的消息粘贴到其中，以唤醒 Agent。
palaver send / list / wait / listen	面向脚本、CI 作业和不使用 MCP 的 Agent 的命令行工具。

收到的消息如何传达到 Agent：

Agent	启动命令	收到的消息
Claude Code（推送）	claude --dangerously-load-development-channels server:palaver	作为 <channel source="palaver"> 事件推送到会话中
Claude Code（普通模式）	claude	MCP 服务会要求 Claude 在后台持续运行 palaver listen；命令返回时 Claude 会被唤醒
Antigravity（agy）	agy	在后台运行 palaver listen，与普通模式的 Claude Code 相同
Codex、Antigravity 或任何终端 Agent	palaver tmux <name> -- codex	粘贴到 Agent 的提示词中
其他任何 Agent	—	使用 wait_for_message / read_inbox 工具，或使用 palaver wait

推送功能使用 Claude Code 的 channels（研究预览版）。自定义 channel 需要 --dangerously-load-development-channels 标志；每次 Claude Code 使用此标志启动时，都会要求你确认“开发 channels”警告。palaver 会检测此标志并相应调整。设置 PALAVER_PUSH=channel|listener 可覆盖检测结果。如果不使用此标志，后台监听器会在你于会话中首次输入提示词后启动。

快速开始

要求：Node.js 20+；若要唤醒 Codex/终端 Agent，还需 tmux 3.2+。支持 macOS 和 Linux；在 Windows 上，仅中继服务和轮询工具可用。

1. 安装（每台机器）

npm install -g palaver-agents    # puts `palaver` on your PATH

也可以从源代码安装：git clone https://github.com/EminUZUN/palaver && cd palaver && npm install && npm link。

Claude Code 用户也可以将 palaver 安装为插件。插件会询问中继 URL 和令牌（存储在 Claude Code 的安全存储中），无需单独注册 MCP：

/plugin marketplace add EminUZUN/palaver
/plugin install palaver@palaver
claude --dangerously-load-development-channels plugin:palaver@palaver   # with push

中继镜像为 ghcr.io/eminuzun/palaver，该服务已在 MCP Registry 中登记，名称为 io.github.EminUZUN/palaver。

2. 启动中继（在一台机器上）

mkdir -p ~/.config/palaver
cat > ~/.config/palaver/.env <<EOF
PALAVER_TOKEN=$(openssl rand -hex 32)
PALAVER_HOST=192.0.2.10
EOF
chmod 600 ~/.config/palaver/.env
palaver relay

将上方中继设置中的 192.0.2.10 替换为这台机器的局域网或 VPN 地址。 使用 Docker 时，请使用相同的地址，并将 ... 替换为生成的令牌： docker run -d -p 192.0.2.10:7777:7777 -e PALAVER_TOKEN=... ghcr.io/eminuzun/palaver。 仅在该地址上发布端口。如果不指定主机地址，-p 7777:7777 默认会在所有主机地址上发布。 请参阅 examples/。健康检查：GET /healthz。

3. 配置每台机器

~/.config/palaver/.env（chmod 600）：

PALAVER_RELAY=ws://192.0.2.10:7777
PALAVER_TOKEN=<the same token>

检查：palaver list 应能连接并列出对等端（目前还没有）。

4. 连接你的 Agent

Claude Code：注册一次 MCP 服务（用户范围，适用于所有项目）：

claude mcp add --scope user palaver -- palaver mcp

如果 Agent 找不到 palaver（例如使用 nvm 时），请在此处和下方的配置中使用 command -v palaver 输出的完整路径。

然后启动启用了推送功能的 Claude：

PALAVER_NAME=laptop-claude claude --dangerously-load-development-channels server:palaver

在此仓库的克隆副本中，.mcp.json 会为你注册该服务。

Codex：添加到 ~/.codex/config.toml：

[mcp_servers.palaver]
command = "palaver"
args = ["mcp"]
tool_timeout_sec = 1800                  # wait_for_message can block up to 1500s
default_tools_approval_mode = "approve"  # optional: no approval prompt per palaver tool call

然后通过 tmux 启动 Codex，以便消息唤醒它：

palaver tmux laptop-codex -- codex

启动器会通过 -c 覆盖选项将对等端名称传递给 Codex，因为交互式 Codex 会从共享守护进程启动 MCP 服务，而该守护进程不会继承你的 shell 环境。使用 Ctrl-b d 分离会话，使用 tmux attach -t palaver-laptop-codex 重新连接。

Antigravity（agy）：注册一次 MCP 服务：

agy mcp add palaver palaver mcp
PALAVER_NAME=laptop-agy agy                      # listener mode, after your first prompt
palaver tmux laptop-agy --roles gemini -- agy    # or: woken through tmux

5. 试用

向任一 Agent 提问：“列出 palaver 对等端，并向 laptop-codex 打个招呼。”

面向组织

palaver 没有中央服务：每个组织都运行自己的中继，Agent 从用户的机器连接。

1. 运行中继：在你的网络内运行 Docker 镜像（examples/docker-compose.yml），或运行 systemd 单元（examples/palaver-relay.service），并置于 VPN 或 TLS 代理之后。

2. 发放成员专属令牌：使用成员文件（参阅团队与集群），避免用户使用彼此的 Agent 名称。

3. 部署客户端：安装 Claude Code 插件，或运行 npm install -g palaver-agents，并为 Codex 和 Antigravity 配置 MCP。

4. 将频道加入允许列表（Claude Code）：借助托管设置，用户可以启动 claude --channels plugin:palaver@palaver，无需开发标志及其提示：

   {
     "channelsEnabled": true,
     "allowedChannelPlugins": [{ "marketplace": "palaver", "plugin": "palaver" }]
   }
   

团队与集群

名称。 每个 Agent 都有一个对等名称（PALAVER_NAME；默认值为 <hostname>-<pid>）： 由字母、数字、_ 和 - 组成。已有连接占用的名称再次连接时，会替换旧连接。

角色。 设置 PALAVER_ROLES=reviewer,backend（或运行 palaver tmux <name> --roles reviewer -- codex）。 list_peers 会显示角色。发送给 @reviewer 的消息会送达所有在线且具有该角色的对等端， 而 @all 会送达所有在线对等端。忙碌的对等端会将消息排在尚未确认的消息之后。离线对等端不会收到扇出消息。直接 发送给某个名称的消息会在该对等端离线时排队等待（每个对等端最多 50 条，存储在中继内存中）。 角色是 Agent 自行选择、用于路由工作的标签，不代表权限。

多人协作。 为每个人分配自己的令牌，确保没人能冒充其他人的 Agent。在中继上创建成员文件（chmod 600）：

{ "members": [
    { "name": "alice", "token": "<openssl rand -hex 32>" },
    { "name": "bob",   "token": "sha256:<hex sha256 of bob's token>" } ] }

运行 palaver relay --members members.json，或设置 PALAVER_MEMBERS。成员只能使用名称 <member> 或以 <member>- 开头的名称（alice-claude、alice-codex-2）。 中继会拒绝重叠的成员名称，例如 alice 和 alice-bob。 成员文件可以与共享的 PALAVER_TOKEN 配合使用；令牌持有者可以使用任何名称。 若要为不同团队分别运行服务，请启动多个中继。一个中继只是一个轻量级进程。

在一台机器上运行的集群示例：

palaver tmux alice-planner  --roles planner  -- claude
palaver tmux alice-codex-1  --roles backend  -- codex
palaver tmux alice-codex-2  --roles backend  -- codex
palaver tmux alice-reviewer --roles reviewer -- claude

然后告诉规划 Agent：“拆分任务，将后端工作发给 @backend，并将结果发给 @reviewer”。

防护措施。 每个连接每 10 秒最多可发送 30 条消息，因此，两个不断互相回复的 Agent 会触及速率限制，而不是向所有人发送大量消息。消息为纯文本，最长 100,000 个字符。

CLI

palaver relay --host <ip> [--port 7777] [--members file.json]
palaver mcp
palaver tmux <name> [--roles a,b] -- <agent command...>
palaver list
palaver send <to> <message...>        # to: name, @role or @all; sends as $PALAVER_NAME without going online
palaver wait [seconds]                # goes online as $PALAVER_NAME and prints the next message
palaver listen <name> [seconds]       # waits on <name>'s local inbox (no relay connection)

设置项取自环境变量；否则依次读取以下文件中第一个存在的文件：$PALAVER_ENV、~/.config/palaver/.env、<package>/.env。请参阅 .env.example。在设置文件中， 双引号括起来的值会按 JSON 风格解码转义字符（\"、\\、\n），单引号括起来的值则按字面处理；空值视为未设置。

变量	使用方	含义
PALAVER_RELAY	对等端	中继 URL，ws://host:7777，或 TLS 后方的 wss://
PALAVER_TOKEN	双方	共享密钥，或成员自己的令牌
PALAVER_NAME	对等端	此 Agent 的对等名称
PALAVER_ROLES	对等端	逗号分隔的角色
PALAVER_PUSH	对等端	channel 或 listener，覆盖自动检测结果
PALAVER_HOME	对等端	本地状态目录（默认 ~/.palaver）
PALAVER_HOST、PALAVER_PORT	中继	监听地址（必填）和端口（默认 7777）
PALAVER_MEMBERS	中继	包含各成员令牌的成员文件

安全

palaver 的作用是将一个 Agent 的文本发送给另一个 Agent。请做好以下准备：

• 任何持有有效令牌的人都可以向你的 Agent 发送消息，而以宽松权限（--dangerously-skip-permissions、自动批准）运行的 Agent 可能会据此采取行动。请妥善保管令牌，在群组中为每位成员使用独立令牌，并且仅在专用网络或 VPN 上运行中继。
• 消息会标记来源，但不代表可信。 Agent 会获知 palaver 消息来自其他 Agent，而非其用户。消息文本无法关闭通道标签或伪造消息边界。这只是对模型的指导，并非沙箱。
• 在不受信任的网络之外使用 TLS。 中继使用明文 ws://。请将其置于 VPN（WireGuard、Tailscale）或 TLS 代理之后，例如 Caddy： caddy reverse-proxy --from relay.example.com --to 127.0.0.1:7777，然后使用 PALAVER_RELAY=wss://relay.example.com。
• tmux 注入器会向运行中的终端输入文本。 注入器只会向启动 Agent 时所在的窗格粘贴文本，不会粘贴到其他窗格；识别到屏幕上的批准提示时会暂停输入。这只是尽力而为，依据的是屏幕上显示的内容；相比自动批准模式，更建议使用在执行风险操作前会征求确认的 Agent。如果消息本身看起来像提示词，则绝不会输入：Agent 会收到简短通知，要求通过 read_inbox 获取消息。该窗格中任何已输入但尚未提交的内容都会与消息一起提交。
• 本地收件箱位于 ~/.palaver/inbox/<name>/（0700/0600）。每条消息都包含经中继验证的发送者名称。

如需报告漏洞，请参阅 SECURITY.md。

限制

• 中继会将离线队列保存在内存中；重启中继会清空队列。
• 消息至少投递一次。“已投递”表示接收端机器已将消息存入 Agent 的收件箱或推送到会话中，并不表示 Agent 已处理该消息。未确认的消息会在接收端重新连接后再次投递，因此极少数情况下会收到两次。接收端最多可有 50 条未确认消息；超出的消息会留在队列中。
• 推送功能依赖 Claude Code channels（研究预览版）；标志名称可能会更改。
• 按设计，本项目不内置 TLS、持久化、消息历史记录或 Web 界面：中继会保持轻量。

路线图

符合轻量中继设计的构想，按大致优先级排列：

• palaver doctor：检查设置来源、中继连通性、身份、投递模式、收件箱和注入器
• 消息过期时间（TTL）和回复 ID，用于请求/响应自动化
• 无需重启中继即可撤销令牌并重新加载；可选的成员级发送规则
• 可选的磁盘队列，让中继重启后仍能保留未投递的消息

开发

npm install
npm test        # starts its own relay on a random port; tmux tests run when tmux is installed

npm run test:e2e 是一项可选的端到端测试，会使用真实 Agent。它会启动一个中继和两台运行 Claude Code、Codex 与 Antigravity 的 Docker“机器”，随后检查点名消息（@all）以及在两台机器上的所有 Agent 之间传递的接力棒。测试需要 Docker 和 Agent 登录信息（--use-local-logins 会在本次运行中将此机器的登录信息复制到测试容器中；也可使用 CLAUDE_CODE_OAUTH_TOKEN / OPENAI_API_KEY；请参阅 test/e2e/run.mjs），会使用你的模型订阅，并需要几分钟时间。测试只会在你的机器上运行，绝不会在 CI 中运行。

请参阅 CONTRIBUTING.md。本项目基于 Apache License 2.0 授权。