将 DeepSeek Responses API 接入 Hermes Agent（完整方案分析）

DeepSeek 于 2026 年 7 月新增了 Responses API 支持。本文分析两种 API 格式的核心差异，以及如何在 Docker 部署的 Hermes Agent 中接入使用。

一、背景：两种 API 格式

DeepSeek 新增的 Responses API 与传统的 Chat Completions API 是两套不同的协议：

关键限制（截至 2026-08）：

• previous_response_id / conversation：不支持（无状态 API）
• store / background / metadata：不支持
• truncation：不支持，超出上下文窗口返回 400
• file_search / code_interpreter / computer_use / mcp 等内置工具：忽略
• 不支持图片、文件输入（input_image 会被替换为占位文本）

二、核心发现：Hermes 已原生支持

Hermes Agent 的 ProviderProfile.api_mode 支持四个值：

chat_completions | codex_responses | anthropic_messages | bedrock_converse

codex_responses 就是 Responses API 格式的传输层。在 config.yaml 的 custom_providers 中设 api_mode: codex_responses 即可切换。

api_mode 选择优先级

1. 用户显式覆盖（config.yaml 的 model.api_mode）
2. OpenCode 的每模型分发
3. URL 自动检测（/anthropic 后缀 → anthropic_messages，api.openai.com → codex_responses 等）
4. 配置文件 api_mode 作为回退
5. 默认值 chat_completions

需要显式设置 api_mode: codex_responses，因为 URL 自动检测未必能命中 DeepSeek 域名。

三、当前架构分析

典型部署场景中，Hermes 通过 API 网关统一调用上游模型：

Hermes → POST /v1/chat/completions → API 网关 → 上游模型

API 网关对外暴露标准 OpenAI Chat Completions 接口。如果要走 Responses API，需要让网关知道如何处理新格式的请求。

四、三种可行方案

方案 A：直连 DeepSeek（绕开网关）⭐ 最简单

在 config.yaml 新增一个直连 provider：

custom_providers:
  - name: ds-responses
    base_url: https://api.deepseek.com
    api_key: ${DS_API_KEY}
    model: deepseek-v4-flash
    api_mode: codex_responses

优点：零开发，改配置即用。

局限：

• 绕过网关的负载均衡 / 故障转移 / 用量统计
• Responses API 仅支持 deepseek-v4-flash

方案 B：网关增加 /responses 路由透传 ⭐⭐ 推荐

在网关新增路由处理器，将 /responses 路径的请求原样转发到 DeepSeek：

Hermes → POST /responses → 网关 → POST https://api.deepseek.com/responses

Hermes 配置指向网关：

custom_providers:
  - name: gateway-responses
    base_url: https://你的网关地址
    api_key: ${GATEWAY_API_KEY}
    model: deepseek-v4-flash
    api_mode: codex_responses

注意：api_mode: codex_responses 会告诉 Hermes 发 /responses 而非 /v1/chat/completions。

优点：

• 保留网关中间层能力
• 统一入口管理
• SSE 流式事件原样回传即可，无格式转换

预估开发量：网关新增一个 route handler，约 50-100 行代码。

方案 C：Chat Completions ↔ Responses 格式互转 ⚠️ 不推荐

在网关做格式翻译：收 Chat Completions → 转 Responses → 调 DeepSeek → 转回 Chat Completions。

不推荐原因：

• 两种格式语义差异大（item 结构、流式事件、工具调用），翻译层极易出 bug
• DeepSeek Responses API 本身有多项不支持的限制，翻译会加剧丢失
• 维护成本高

五、推荐落地路径

方案 B（网关加路由） > 方案 A（直连尝鲜） >> 方案 C（格式互转，不做）

方案 B 实施步骤

1. 网关侧：新增 POST /responses 路由，透传到 DeepSeek /responses，保持 SSE 流式事件原样回传
2. Hermes 侧：config.yaml 新增 custom_providers 条目，api_mode: codex_responses，base_url 指向网关
3. 验证：先用 deepseek-v4-flash 跑一轮 tool calling + streaming，确认事件序列完整

核心结论

• Hermes 本身完全具备接入 Responses API 的能力（codex_responses 模式）
• 唯一待解决的问题是网关侧的透传路由——这在 Hermes 框架之外
• 如果只求快速验证，方案 A 改配置 5 分钟即可跑通

六、参考

• DeepSeek Responses API 官方文档
• OpenAI Responses API 参考