Hermes API Server 的价值，是把 Agent 从 CLI 或消息入口变成可以被外部系统调用的后端能力。这个变化很重要，也很危险。
CLI 里的错误通常只影响当前会话；API 一旦接入外部系统，就会面对重复请求、并发、鉴权、跨域、日志、超时和权限放大。
先判断是否真的需要 API
不是所有集成都需要 API Server。
| 需求 | 更适合方式 |
|---|---|
| 临时聊天或个人操作 | CLI |
| 消息软件中使用 | Messaging Gateway |
| 定时任务 | Cron |
| 外部系统主动调用 | API Server |
| 自建 Web UI 或内部 dashboard | API Server |
如果你只是想让 Hermes 每天提醒你，cron 就够了；如果你想让内部系统在某个事件后调用 Hermes 分析并返回结果，才更像 API 场景。
一个更像真实项目的判断方式
很多团队不是“要不要 API”这个抽象问题，而是卡在具体场景里：
- 要做一个内部运营后台，让同事点按钮生成日报。
- 要从 CI、工单系统或 webhook 把事件推给 Hermes 处理。
- 要给前端或移动端做一个受控的 Agent 面板。
- 要把 Hermes 接到已经兼容 OpenAI API 的现有工具里。
只要请求会从“当前操作者的终端”变成“别的系统代替人来调用”，你就应该把它当成服务化边界，而不是普通 CLI 习惯的延伸。
鉴权不是可选项
API Server 上线前，至少要配置 bearer token。应用层要记住两点：
- token 不要写进前端公开代码。
- 不同环境最好使用不同 token 和不同 profile。
如果浏览器端直接调用 API，还要考虑 CORS。CORS allowlist 应该写明确域名，不要为了省事开宽泛通配。
建议把第一阶段的调用主体压缩到最少：
| 调用主体 | 建议 |
|---|---|
| 内部后端服务 | 推荐，便于保管 token 和限流 |
| 受控内网前端 | 可以，但必须配合明确 CORS 和最小化动作 |
| 公开网页前端 | 不建议直接调用 Hermes API |
| 第三方自动化平台 | 仅在你能控制 token、回调和日志时考虑 |
OpenAI-compatible API 适合什么
OpenAI-compatible 接口的价值在于生态兼容：一些已有客户端、内部工具或 UI 可以用相似方式接入。
但兼容不代表边界相同。Hermes 背后可能有 memory、skills、tools、profile、cron 等长期能力，所以外部客户端能触发什么，必须额外限制。
适合 OpenAI-compatible API 的典型任务：
- 在已有聊天 UI 里接一层 Hermes。
- 让内部工具快速复用兼容 SDK。
- 先验证“接得通”，再决定是否进入更复杂的 runs 工作流。
不适合它的情况：
- 你需要清楚展示长任务的排队、执行和结果状态。
- 你需要对同一个任务做轮询、重试和回放。
- 你要把一次请求拆成多步执行并追踪生命周期。
Runs API 适合什么
长任务不适合只靠一次请求等待结果。Runs API 这类能力更适合：
- 生成较长报告。
- 执行多步分析。
- 调用 skill。
- 需要展示任务进度。
- 需要重试或查询结果。
如果调用方是 dashboard 或内部系统，不要让用户一直盯着 spinning 状态。给任务一个可查询状态，体验和治理都会更稳。
外部系统最容易漏掉的 4 个边界
1. profile 边界
不要让默认 profile 同时承担个人聊天、定时任务和外部 API。更稳的做法是给 API 单独 profile，至少把 memory、skills、默认工作目录和日志责任拆开。
2. 工具边界
第一阶段只开放低风险只读能力，例如检索、总结、状态说明、已有文档问答。把写文件、发消息、执行脚本、提交代码这类动作留在人工审批之后。
3. 并发边界
外部系统会自然地产生重复点击、重试和并发请求。你要先定义：
- 相同任务是否允许并发执行。
- 请求超时后是否继续后台运行。
- 调用方重试时如何避免重复副作用。
4. 日志边界
API 接口一旦进入团队使用，日志就不再只是调试材料。你需要决定保留什么请求元数据、输出什么错误信息，以及哪些内容不应该进日志。
外部系统调用清单
上线前逐项确认：
- 哪些系统可以调用 API。
- 使用哪个 profile。
- 能读取哪些目录或资源。
- 能否调用 tools。
- 能否调用 skills。
- 能否写文件、发消息、创建任务。
- 请求和响应日志保留多久。
- 失败、超时、重复请求如何处理。
把这些写清楚，比多接一个客户端更重要。
一个保守但实用的上线顺序
- 先用单一 profile 跑通本地或内网测试。
- 只接一个内部调用方，不同时开放多个入口。
- 先开放只读分析和问答型任务。
- 再补 runs 查询、超时处理和失败重试。
- 最后再考虑写操作、自动化联动和更大范围的调用方。
这样做会慢一点，但能把问题定位在清楚的边界里，而不是一开始就把 UI、权限、并发和副作用混在一起。
不建议开放的动作
API 第一阶段不建议直接开放：
- 自动部署。
- 自动提交和 push。
- 修改 secrets 或权限。
- 创建或删除 cron job。
- 向群聊或客户发送未经审核的消息。
- 对生产系统执行不可逆操作。
API 会把一个人的 Agent 变成系统能力。系统能力必须先受控，再扩展。
上线前可执行清单
- 为 API 单独准备 profile、token 和 owner。
- 调用方只保留明确 allowlist，不做开放式接入。
- 前端直连场景已经配置具体 CORS 域名。
- 高风险动作默认关闭或转人工审批。
- 长任务有 runs 状态查询、超时与重试策略。
- 日志保留策略和敏感字段处理方式已经写清。
- 已准备回滚方式：停 API、停 token、停调用方。
完成检查
- 你知道为什么需要 API，而不是 CLI、gateway 或 cron。
- 你配置了 token 和明确 CORS 范围。
- 你知道外部调用使用哪个 profile。
- 你把高风险动作排除在第一阶段之外。
- 你准备了长任务状态、日志和失败处理。
下一步建议继续看 Hermes Profiles 多环境指南、Hermes Profiles 与 API Server 教程 和 Hermes Cron 自动化，把 profile、服务接口和后台任务放进同一套治理图里。