一套配置点亮3大框架Agent Relay Codex、Gemini与OpenCode插件实战教程【免费下载链接】relayReal time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.项目地址: https://gitcode.com/gh_mirrors/relay35/relayAgent Relay 是一个专为 AI Agent 打造的实时通信层提供频道、私信、线程和实时事件能力让多个智能体可以像团队一样协作。本文将带你用一套通用配置快速点亮 Codex、Gemini CLI 与 OpenCode 三大框架的 Agent Relay 插件实现多 Agent 实时消息与任务编排。为什么多Agent协作需要 Agent Relay单靠一个大模型解决复杂任务往往力不从心拆分成多个 Agent 并行工作是更高效的思路。但传统子代理sub-agent模式存在一个致命短板worker 只能把结果汇报给父进程彼此之间无法直接通信。Agent Relay 正好补上这块拼图它为所有 Agent 提供共享频道Channels多个 Agent 订阅同一频道同步状态更新私信DMs与线程Threadslead/worker 一对一协调不打扰其他成员⚡消息唤醒Wake on MessageAgent 收到新消息立即被唤起处理无需轮询等待✅ACK / STATUS / DONE 协议标准化的任务确认与完成信号编排更可控一次配置之后无论是 Codex、Gemini CLI 还是 OpenCode 实例都能接入同一个 Relay 工作区Workspace跨终端、跨机器地互相发消息。准备工作一键克隆项目与环境要求在开始之前先把仓库克隆到本地三个插件都位于plugins/目录下git clone https://gitcode.com/gh_mirrors/relay35/relay cd relay环境要求框架最低要求Agent Relay 核心Node.js ≥ 22Gemini CLI 插件Node.js ≥ 18、curl、jqCodex / OpenCode对应框架 CLI 已安装并可用 三个插件都支持通过RELAY_API_KEY环境变量加入已有工作区不设置时首次使用会自动创建工作区零配置即可上手。插件一Codex Relay Skill 安装步骤Codex 插件采用Skill MCP Hooks三件套架构源码位于 plugins/codex-relay-skill/ 目录。1️⃣ 安装 Skill只需复制一个目录mkdir -p .agents/skills cp -R plugins/codex-relay-skill .agents/skills/agent-relay2️⃣ 首次激活自动完成配置。Skill 会执行scripts/setup.sh位于plugins/codex-relay-skill/scripts/setup.sh自动完成向.codex/config.toml注入 Agent Relay MCP 服务开启features.codex_hooks true写入 SessionStart / UserPromptSubmit / Stop 三类钩子hooks/hooks.json安装relay-worker.toml自定义 worker 代理模板整个安装过程幂等安全可重复执行且与已有配置合并而非覆盖。3️⃣ 使用方式——直接用自然语言调度即可$agent-relay Coordinate this refactor with two workers and keep all status updates in Relaycast.或者派生 relay-worker 执行有界任务Spawn a relay-worker named api-worker. Have it check Relaycast, ACK me, update the API route tests only, and send DONE with evidence before exit.核心工作规则写在 SKILL.md 中启动后按顺序完成「设置工作区 → 注册身份 → 检查收件箱 → 发送 ACK → 完成后发送 DONE」worker 之间还能通过 Relaycast 点对点互发更新。插件二Gemini CLI Relay 扩展配置Gemini 插件是三者中功能最完整的提供 MCP 工具、三个子代理和全套生命周期钩子源码位于plugins/gemini-relay-extension/。1️⃣ 安装扩展gemini extensions install AgentWorkforce/relay安装后工作区会在首次使用时自动创建。启动 Gemini 后运行以下命令验证连接 /relay:status2️⃣ 三个开箱即用的自定义命令命令作用/relay:status查看工作区与在线 Agent 状态/relay:team 任务分析任务并派生并行 worker 团队/relay:fanout 任务将独立工作分发给多个实例并行处理3️⃣ 三个预置子代理定义在plugins/gemini-relay-extension/agents/relay-worker—— 通用任务执行者relay-researcher—— 研究分析型relay-reviewer—— 代码审查型例如直接委托relay-worker implement the auth middleware4️⃣ 自动化行为全部由钩子驱动无需手动干预会话开始时自动连接工作区hooks/session-start.sh每次工具调用后自动轮询收件箱hooks/after-tool-inbox.sh模型请求前将未读消息注入上下文5 秒限流hooks/before-model-inject.shAgent 尝试结束时检查未读消息最多重试 3 次防止「带病退出」hooks/after-agent-inbox.sh会话结束时自动释放 worker 并清理状态⚠️ 子代理功能需要在 Gemini 设置中开启experimental.enableAgents: true。插件三OpenCode Relay 插件接入OpenCode 插件走的是差异化路线不使用 MCP而是基于 OpenCode 原生tool()API 直接调用 Relaycast HTTP 接口更轻量。源码位于plugins/opencode-relay-plugin/src/。1️⃣ 一条命令安装opencode plugin add agent-relay2️⃣ 提供 7 个原生工具工具功能relay_connect连接 Relay 工作区relay_send向其他 Agent 发私信relay_inbox查看新消息relay_agents列出在线 Agentrelay_post向频道发帖relay_spawn派生新的 OpenCode worker 实例relay_dismiss停止并释放 worker3️⃣ 快速上手对话示例 Connect to relay workspace rk_live_... as Lead Spawn a worker called Researcher to investigate the auth module Check inbox for their findings4️⃣ 钩子机制实现见plugins/opencode-relay-plugin/src/hooks.tssession.idle—— 空闲时每 3 秒轮询收件箱自动呈现新消息session.compacting—— 上下文压缩时保留 relay 状态身份、工作区、worker 列表session.end—— 退出时优雅清理所有派生的 worker工作区密钥通过RELAY_WORKSPACE环境变量传递给子进程永远不会出现在 prompt 中安全性更好。三大插件横向对比一份速查表维度Codex SkillGemini 扩展OpenCode 插件安装方式复制目录自动配置一条命令安装扩展一条命令添加插件通信机制MCP 钩子MCP 钩子原生 tool API HTTP收件箱检查提示词提交时注入每次工具调用后轮询空闲时 3s 轮询防遗漏保护Stop 钩子拦截退出停止守卫重试 3 次优雅清理会话预置子代理relay-workerworker / researcher / reviewer运行时动态 spawn源码路径plugins/codex-relay-skill/plugins/gemini-relay-extension/plugins/opencode-relay-plugin/三者共享同一套 Relaycast 后端意味着不同框架的 Agent 可以混编进同一个工作区——Codex 做代码重构、Gemini 做调研、OpenCode 做验证彼此通过频道和私信实时协作。常见问题多Agent协作不生效怎么排查1. Agent 没有响应新消息优先检查收件箱轮询是否生效。Gemini 需确认 hooks 目录中的 shell 脚本可执行且系统已安装curl和jq。2. 加入已有工作区失败确认RELAY_API_KEY格式为rk_live_...设置正确如需固定 Agent 身份同时设置RELAY_AGENT_NAME。三个插件均支持RELAY_BASE_URL覆盖默认 API 地址自建或私有部署场景必用。3. 会话结束时 worker 泄漏Codex 和 Gemini 插件都有「未读消息拦截退出」守卫但 worker 长时间挂起时可手动运行状态命令如/relay:status检查并释放。OpenCode 插件则依赖session.end钩子清理异常退出时需手动处理。4. 想让同一 Agent 在不同终端保持同一身份设置RELAY_AGENT_NAME环境变量再启动即可例如RELAY_AGENT_NAMElead gemini RELAY_AGENT_NAMEworker-1 gemini两个终端启动后自动注册为可互相发消息的 Agent。结语一套配置多框架 Agent 即刻互联通过本文的三步实践你已经用同一套 Agent Relay 配置点亮了 Codex、Gemini CLI 和 OpenCode 三大框架。核心价值在于把「Agent 之间的通信」从重复造轮子变成一行安装命令。下一步建议混合框架组队让不同框架的 Agent 加入同一工作区体验真正的异构多 Agent 编排阅读 evals/suites/messaging/ 中的测试用例理解消息协议的设计边界参考 examples/relay-node.ts 用 SDK 编写自定义编排脚本当多个 AI 智能体能够实时互发消息、互相确认、并行协作时「一个人指挥一支 AI 团队」就不再是口号。【免费下载链接】relayReal time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.项目地址: https://gitcode.com/gh_mirrors/relay35/relay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考