Pi Relay

Pi Relay 是一个 Pi-native 聊天中继，用于构建长期运行的 Telegram / Mattermost Agents Assistant。该仓库从 anyagent fork 而来，并简化为仅支持 Pi。Codex/Claude adapter 与旧的文本输出契约不再作为运行时路径使用。

How to use

安装

Pi Relay 要求 Node.js 22.19 或更高版本，并会在 agent 运行时调用 pi CLI。请通过 npm 安装 Pi 和 Pi Relay，并在启动 relay 前完成 Pi 配置：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
npm install -g @kky42/pi-relay

创建并连接第一个 Telegram agent

先用 BotFather 创建 Telegram bot，并保存 bot token 和 bot username。

创建本地 Pi Relay agent 配置：

pi-relay agent add my-agent

编辑 ~/.pi-relay/agents/my-agent/config.json：

• 将 profile.workdir 设置为 agent 的工作目录。生成的 profile 类似：

{
  "profile": {
    "workdir": "/absolute/path/to/workdir",
    "auto": "medium",
    "model": "default",
    "reasoningEffort": "default",
    "loadAmbientExtensions": false,
    "loadAmbientSkills": false,
    "loadAmbientContext": false
  }
}

当 profile.model 和 profile.reasoningEffort 均设为 "default" 时，Pi Relay 不传对应的 CLI 参数，由用户自己的 Pi 配置或恢复的会话决定实际值。

profile.auto 为每次 Pi 运行选择内置 sandbox 策略：low 为只读，medium 允许写入 workspace 和临时目录，high 不限制。Sandbox 作用于 Pi 内置 shell 和文件 tools，网络访问仍不受限制。底层在 macOS 使用 sandbox-exec，在 Linux 使用 bubblewrap；需要安装 ripgrep（Linux 还需要 socat）。

三个严格 boolean 类型的 loadAmbient* 配置分别控制 Pi 是否从其常规用户级/项目级来源发现 ambient extensions、skills 和 context files。它们默认均为 false，使 relay 运行保持隔离和可复现；只有明确需要某类 ambient 来源时才将对应字段设为 true。Ambient prompt templates 和 themes 始终禁用。这些开关不会禁用 Pi 内置 tools，也不会禁用 relay 通过显式路径加载的 Pi Relay extensions（src/pi_tools/extension.ts 和 src/pi_tools/pi-sandbox/extension.ts）。

• bindings.telegram 是 Telegram bot 配置列表。username 和 token 必填。访问设置属于各个 bot，不再提供平台级访问默认值：
  • accessMode：默认为 "allowlist"；设为 "public" 时允许任何用户发起私聊。
  • allowedUsernames：允许与该 bot 私聊的用户。
  • managerUsernames：允许在该 bot 上执行 manager-only 命令的用户；manager 会自动获得私聊访问权限。
  • 用户名均不带 @。

[
  {
    "username": "relay_bot_username",
    "token": "123456:telegram-bot-token",
    "accessMode": "allowlist",
    "allowedUsernames": ["alice", "bob"],
    "managerUsernames": ["ops_admin"]
  }
]

bindings.mattermost 是 Mattermost bot 配置列表。serverUrl、username 和 token 必填，访问设置同样只属于各个 bot。Pi Relay 会根据 server host 和 username 生成内部 binding identity：

[
  {
    "serverUrl": "https://chat.example.com",
    "username": "relaybot",
    "token": "mattermost-bot-token",
    "accessMode": "allowlist",
    "allowedUsernames": ["alice", "bob"],
    "managerUsernames": ["ops_admin"]
  }
]

新建配置会提供完整的 Telegram 和 Mattermost bot 列表占位项，并在各 bot 内包含访问列表。*_without_at 表示用户名必须去掉 @。启动前请替换所用平台的全部占位值，并删除不使用平台的 bot 占位项；否则 daemon 会尝试连接这些占位 bot。allowedUsernames 和 managerUsernames 只是角色示例，不表示配置创建者或 bot owner。

启动后台 relay daemon：

pi-relay daemon start
pi-relay daemon status

打开 Telegram，进入和 bot 的私聊并发送消息。若要在群里使用，将 bot 加入群聊后在消息或命令里 mention 它，例如 /status @your_bot_username。

管理 daemon 和 agents

Pi Relay 自行管理后台 daemon：

pi-relay daemon start
pi-relay daemon restart
pi-relay daemon stop
pi-relay daemon status

使用以下命令管理 agent 配置及其相关运行数据：

pi-relay agent add my-agent
pi-relay agent list
pi-relay agent remove my-agent

配置好新添加的 agent 后，执行 pi-relay reset --agent my-agent，即可在已经运行的 daemon 中激活它。执行 agent remove 前必须先停止 daemon；remove 会永久删除 agent 配置、conversation state、schedules 和附件缓存。Pi session 文件由 Pi 自己管理，Pi Relay 只持久化 resume 所需的 session ID。

私聊访问策略在每个 bot 上独立配置为 accessMode: "allowlist" | "public"。该配置不改变群聊行为；仅 manager 可执行的命令仍由 managerUsernames 控制。修改访问设置后，可以 reload 单个 agent 或全部 agents，且不中断 session、queue、schedule 或现有 timer：

pi-relay reload --agent my-agent
pi-relay reload

当配置或 runtime bindings 需要完整协调时，可以 reset 单个 agent 或全部 agents：

pi-relay reset --agent my-agent
pi-relay reset

Schedule 是 conversation-local 的 heartbeat turn：它在同一个 front-agent session 中运行，并获得与用户 turn 相同的 Pi Relay tools，包括 add_schedule、list_schedule 和 remove_schedule。

运行数据默认保存在 ~/.pi-relay。在每条命令前设置 PI_RELAY_HOME，即可运行一个拥有独立 agents、state、cache、daemon control files 和 logs 的实例：

PI_RELAY_HOME="$HOME/.pi-relay-dev" pi-relay daemon start
PI_RELAY_HOME="$HOME/.pi-relay-dev" pi-relay daemon status

不同实例不能使用相同的 Telegram bot token 或 Mattermost bot 账号。Pi 继续在其常规用户级目录中管理和保存 sessions；Pi Relay 只记录对应的 session ID。