核心用法
relay-to-agent 是一个 Node.js 脚本工具，用于向任何 OpenAI 兼容的 API 端点发送消息并与 AI 代理进行交互。其工作流分为三步：
1. 配置代理：在 agents.json 中定义代理 ID、名称、描述和模型映射
2. 环境准备：设置 RELAY_API_KEY 等环境变量
3. 执行交互：通过 CLI 发送消息、管理会话、查看代理列表
关键功能
- 多轮对话：默认保持会话上下文（最多 50 条消息），支持
--reset清空历史 - 会话隔离：通过
--session参数实现同一代理的并行多线对话 - 广泛兼容：支持 Connect Chat、OpenRouter、LiteLLM、vLLM、Ollama 等主流服务
- 灵活输出：
--json标志输出原始 API 响应便于脚本集成
显著优点
| 维度 | 优势 |
|------|------|
| **生态兼容** | 不绑定特定平台，任何实现 Chat Completions API 的服务均可接入 |
| **轻量无依赖** | 纯 Node.js 实现，无需 Docker 或复杂运行时 |
| **会话持久化** | 本地缓存机制实现"断点续聊"，优于纯无状态调用 |
| **配置驱动** | JSON 配置文件便于团队共享代理定义和端点设置 |
潜在局限
- 本地状态风险：会话存储于
~/.cache/relay-to-agent/，多设备使用会导致状态不同步 - 无内置加密：敏感对话历史以明文形式存储于本地文件系统
- 调试能力有限：未提供日志级别控制或请求/响应详细追踪选项
- Node.js 绑定：依赖特定运行时版本，对纯 Python/Go 生态团队不够友好
适合人群
- AI 应用开发者：需要快速验证多个 OpenAI 兼容端点的行为差异
- 运营团队：通过统一 CLI 调用不同平台的专用代理（如 LinkedIn 文案生成、数据分析）
- 隐私敏感用户：倾向本地会话管理而非云端记忆功能的场景
常规风险
- API 密钥泄露：
RELAY_API_KEY以环境变量传递，存在 shell history 记录风险 - 配置注入：
agents.json若被恶意修改可能导致请求重定向至攻击者服务器 - 缓存膨胀：长期使用的会话文件可能占用磁盘空间，需手动清理
- 模型漂移：上游服务商模型更新可能导致代理行为变化而无感知
> 建议：生产环境使用时配合 direnv 或密钥管理服务隔离敏感配置，定期审计 ~/.cache/relay-to-agent/ 目录。