AgentRelay

AgentRelay 是一个本地 Agent CLI Web 中间层。现在支持 Codex，目标是后续通过适配层接入 OpenCode、Claude Code 等工具。

它的核心价值：用手机或浏览器控制本机 Codex，同时不破坏 Codex 原生会话历史。

核心亮点

• 无侵入接入 Codex 历史：直接读取和续写 Codex 本地会话。你在 AgentRelay 里继续的对话，之后不用 AgentRelay 也还能在 Codex 原生历史里看到。
• 服务端维护运行状态：刷新浏览器不会把正在运行的任务误判成“已连接”。AgentRelay 会记录 running、reconnecting、error 等状态。
• 长会话增量加载：不在每次刷新时拉完整历史；新消息增量更新，旧消息向上滚动再加载，手机上更省流量。
• 工具调用实时同步：聊天、命令执行、命令输出、工具调用、审批请求走同一套事件流，对话区和工具记录一起更新。
• 手机优先：移动端简洁界面、左右侧边栏（手机上左滑右滑调出侧边栏）、任务状态、中断按钮、输入框。
• 本地优先，远程可用：Codex app-server 保持在 127.0.0.1，外部只访问带认证的 AgentRelay。支持本地、Cloudflare Tunnel、FRPC。
• 面向多后端扩展：前端只认识 AgentRelay 协议，Codex/OpenCode/Claude Code 差异留在后端适配层。

和同类工具的区别

Happy、HAPI、Polpo、RemCodex、Remodex、Vibe Kanban、Claudia 等工具都在解决 Agent 远程控制或多 Agent 管理问题。

AgentRelay 的定位更小、更偏基础设施：

• 不做完整移动端产品套件。
• 不依赖官方云端或托管 relay。
• 不另建一套割裂的 Codex 会话系统。
• 不把 provider runtime 直接暴露给公网。
• 不为了大型 kanban 工作台牺牲手机端即时控制体验。

简单说，AgentRelay 更像一个可自托管的本地 Agent Session Hub。

安装

npm i -g @wojwo/agentrelay
agentrelay

要求：

• Node.js 20+
• 使用 Codex 后端时，codex 命令需要在 PATH 中

首次启动会要求输入访问令牌，只保存哈希到：

~/.agentrelay/config.toml

启动方式

交互启动：

agentrelay

非交互启动：

AGENTRELAY_TOKEN=your-token agentrelay --connection local
agentrelay --agent codex --connection local
agentrelay --connection cloudflare
agentrelay --connection frpc --frpc-config ./frpc.toml

如果 FRPC 配置有公网地址，可以加：

public_url = "https://your-domain.example"

当前状态

已支持：

• Codex 会话列表、恢复、新建
• 读取和续写 Codex 原生历史
• 实时 assistant 输出
• 工具调用和命令输出记录
• 增量消息加载
• 运行状态追踪
• 中断当前任务
• 编辑用户消息并回退会话
• 新建项目
• Cloudflare Tunnel 二维码
• FRPC 配置启动

计划：

• OpenCode 后端
• Claude Code 后端
• 更严格的计划模式权限控制
• 更完整的后端契约测试

开发

npm install
npm run typecheck
npm run build

常用脚本：

npm run dev          # 前端开发服务器
npm run dev:server   # 后端 watcher
npm run start        # 运行构建后的后端

源码入口：

src/client/main.tsx
src/client/App.tsx
src/server/index.ts
src/shared/types.ts