OpenAgentRelay 让队友或另一个 Agent 调用已经在你电脑上运行正常的东西。调用方只需安装一个小型中继 CLI，不需要本仓库、Agent 源代码、依赖、提示词或业务凭证。
用途 把本地任意 Agent 或自动化转换为团队可调用的能力。发布方拥有可工作的 Agent 或自动化，调用方通过中继 CLI 与其交互。如果你不了解如何使用，可以把项目链接直接发给 Codex、Claude Code 或另一个能读取网页的 Agent，告诉它你需要的角色，它可以阅读 README、在不克隆仓库的情况下安装中继 CLI，并引导或完成设置。发布方与调用方均可使用相应的消息模板；访问密钥应通过 RELAY_ACCESS_KEY 提供，不要放在消息正文中。
主要能力
- 调用方无需发布方仓库或 Agent 实现即可调用能力。
- 直接调用默认无状态；支持 Relay 管理的会话以保留上下文，返回 conversation_id 后继续对话。
- Relay 在内存中存储有界文本记录并注入到新的 Agent 执行中；会话默认一小时后过期，服务器重启后消失。本地 Caller ID 仅防止意外跨调用方续话，不是经过认证的个人身份。
- 对另一个 Agent 或自动化调用时，应始终请求 JSON；成功时有 JSON 输出。
- 操作类 CLI 失败以非零退出码结束，并向标准错误写入 JSON 错误。
- 公开的 Agent Card 位于 /.well-known/agent-card.json；浏览器用户也可打开 Relay URL 并输入访问密钥。
安装与使用方式 普通用户不需要克隆仓库，使用 pipx 安装 CLI。若未安装 pipx，按其一次性安装指南操作（macOS 常见路径为 brew install pipx）。如果已在 Python 3.11+ 虚拟环境中，可使用相应方式安装。克隆仓库仅用于开发；已发布版本在 PyPI 上。
端到端示例 examples/ 目录包含三条可复用路径：基于本地 CSV 数据的零依赖只读报告；在专用只读工作区中进行临时 Codex 审查；使用非交互计划模式并阻止写入和 Web 工具的 Claude Code 审查。先从本地报告开始，在接入 Agent 前验证网络和认证。
发布方：共享能力
- 从安全测试开始：选择一个至少 16 个字符的访问密钥且不要放入 shell 历史；启动一个无害的测试能力。成功启动会确认已加载配置的密钥，并打印 Serving uppercase on http://0.0.0.0:8787。若未配置密钥，Relay 会生成并打印一个临时密钥。在发布方电脑上验证服务，预期响应为 {"status":"ok"}。
- 共享连接信息：找到发布方的局域网地址，macOS 常用命令为 ipconfig getifaddr en0，Linux 为 hostname -I。通过可信渠道发送确切的连接值。0.0.0.0 是监听地址，不是调用方应使用的地址；防火墙可能还需允许端口 8787 的入站 TCP 流量。
- 发布已有命令：Relay 为每个请求启动一次命令。命令必须从标准输入读取一个请求，把最终答案写入标准输出，把日志和诊断写入标准错误，并在该请求结束时退出。
- 发布受限的 Codex 能力：使用专用工作区和此能力所需的最小凭证。不要暴露包含所有个人文件、MCP 服务器、Skills 和令牌的日常 Codex 环境。每个请求通常启动一个新的 codex exec；Codex 可以使用该受限工作区中可用的内容，但 Relay 不会自动恢复发布方历史 Codex 会话。
调用方：调用能力 调用方只需要中继 CLI 和连接信息，不需要发布方仓库或 Agent 实现。在不放入命令历史的情况下加载共享密钥。直接执行时；对另一个 Agent 或自动化调用时，始终请求 JSON。成功时有 JSON 输出。直接调用默认无状态；当后续问题需要先前上下文时，启动 Relay 管理的会话，保存返回的 conversation_id 后继续。
把能力交给另一个 Agent 在调用方 Agent 环境中配置 RELAY_ACCESS_KEY，然后给它连接块。Agent 需要 CLI 和连接块，而不是 OpenAgentRelay 仓库。
安全边界
- 承载认证使用一个共享密钥；它不识别单个队友。
- 传输为纯 HTTP。任何能观察局域网流量的人都可能看到密钥、输入和输出。
- --expect-agent 防止配置错误，但不能以密码学方式证明服务器身份。
- 调用方输入不可信。能力强的 Agent 可能读取文件、调用工具或披露其进程可访问的数据。
- 使用专用工作区、只读工具、最小凭证和描述范围狭窄的能力。
- 不要将端口暴露到公网或接入生产写操作。
- 在服务真实 Agent 前阅读 SECURITY.md。
限制与当前范围 relay serve --help 暴露执行超时、请求大小、输出大小、并发和会话过期控制。0.1 版本不包含 TLS、每用户权限、自动发现、文件传输、进度流、持久会话、一个地址后多个 Agent，或由 Relay 提供的沙箱。异步 Hub + Runner 实验仍在 hub-mode 分支上，不属于当前直接模式 Alpha 路径。源码开发见 CONTRIBUTING.md。采用 Apache-2.0 许可。
