> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 理解模型协议兼容性

Hexagon 的模型连接 provider 表示请求协议，而不是供应商品牌。代理按允许路径转发，不在 Messages、Chat Completions 和 Responses 之间自动转换，也不在失败时猜测另一种协议。

| Connection provider | 请求接口 | 选择依据 |
| - | - | - |
| anthropic-compatible | /v1/messages | 端点明确提供 Messages 契约 |
| openai-compatible | /v1/chat/completions | 端点提供 Chat Completions |
| openai-responses | /v1/responses | 端点提供 Responses |

## 当前 Harness 协议契约

| Harness / Runtime protocol | Messages | Chat Completions | Responses |
| - | - | - | - |
| 内置 Pi 1.5.2 / OpenCode 1.2.27 | 声明支持 | 声明支持 | 声明支持 |
| pi-v1 / opencode-v1 / openclaw-v1 | 声明支持 | 声明支持 | 声明支持 |
| codex-v1 | 不支持 | 不支持 | 声明支持 |
| hermes-v1 | 不支持 | 声明支持 | 不支持 |
| claude-code-v1 / deepseek-v1 / aider-v1 / hexagon-json-v1 | 声明支持 | 不支持 | 不支持 |

表格描述当前 Hexagon 适配器契约，不代表上游项目的全部能力，也不代表所有镜像和端点已实云验证。OCI 注册固定版本与兼容性元数据；已有注册不会因为适配器后来更新而自动扩展，按当前注册项核对，需要时注册新版本。

## 带日期的端点实例

以下是仓库在 2026 年 11 月 18 日记录的验收观察，不是本次可用性检查，也不是更换供应商的建议。三行模型 ID 均为 `MiniMax-M3`，每行协议分别测试；品牌相同不代表接口可以互换。

| 精确内置 Harness 版本 | 协议 | 已测试 API base | 证据与限制 |
| - | - | - | - |
| Pi 1.5.2 / OpenCode 1.2.27 | Messages | `https://api.minimaxi.com/anthropic` | Python / TypeScript 独立任务；操作路径追加为 `/v1/messages` |
| Pi 1.5.2 / OpenCode 1.2.27 | Chat Completions | `https://api.minimaxi.com/v1` | Python / TypeScript 独立任务；不能据此推断 Responses |
| Pi 1.5.2 / OpenCode 1.2.27 | Responses | `https://api.minimaxi.com/v1` | Python / TypeScript 独立任务；不承诺后台或 WebSocket 扩展 |

[带日期的矩阵](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-18-minimax-matrix.md)说明支持 Tools 的组合覆盖两轮任务、实际分配的 MCP 调用、输入、环境、产物和清理；其中也保留早期未知创建记录，成功任务行不能证明全局资源全部清理。这些记录补充而不替代预览、审批与故障恢复旅程。使用时检查所选 Sandbox 的精确条目。OCI 路径还需要镜像 digest 与 command，不能把内置验证当作 OCI 验证。

## 协议相同也要验证行为

完整任务依赖文本流、工具调用格式、工具结果、后续对话、错误形状和模型实际能力。只通过一条问候消息不证明 Tool calling 正常。同样，模型端点自称兼容不保证每个可选字段或运行模式都支持。

Responses 的当前验证请求使用 store:false。Hexagon 不据此承诺服务端内置工具、后台任务轮询、WebSocket 模式或其他 Responses 扩展。Harness 工具仍通过平台 Tool mailbox 和审批机制执行。

OpenCode / Pi 的部分 Responses 契约使用真实二进制与确定性端点测试；这证明对应协议分支，不是所有真实供应商账户认证。实云记录应包含精确模型端点、模型 ID、Harness 版本、SDK 与任务范围。

## 在请求链路中定位失败

| 证据 | 能缩小到什么范围 | 仍未证明什么 |
| - | - | - |
| 连接验证通过 | 控制平面用配置凭据访问了端点，并接受了有界响应形状 | Sandbox 入口、Harness 流式、工具调用和接续 |
| Session 预检 ready | 注册 Harness 与选定模型协议通过结构兼容检查 | 实际执行，以及 Run 时的账户配额 |
| 首次纯文本 Run 成功 | 该 Harness/端点组合完成了这次任务 | 工具 schema、工具结果接续、长输出及第二轮 |
| Tool 任务和第二轮成功 | 此精确组合的已观察操作和接续有效 | 所有操作或未来模型/版本变化 |

验证错误可能在分配 Sandbox 之前出现；后续 Run 也可能因为 Sandbox 无法访问凭据入口失败，即使控制平面仍能访问模型端点。分别诊断两段网络。协议不匹配不应靠轮换凭据解决，入口被阻断也不应靠把上游密钥写入 guest 配置解决。

## 如何选择和定位错误

先核对账户端点提供的协议，再选 Harness 支持的交集。比如使用 codex-v1 时应配置真正的 Responses 端点；给 Messages URL 改一个 provider 名称不能完成转换。base URL 不附加最终操作路径，避免生成重复路径。

预检 incompatible\_model 时检查协议类型而不是密钥；验证失败时再看实际网络、权限、模型 ID 和响应格式。修正后重新验证与启用，最后运行需要的真实旅程。

依据：[Runtime 协议表](https://github.com/NexusFox88/docs/blob/main/resources/modules/harnesses/protocols.ts)、[内置 Pi](https://github.com/NexusFox88/docs/blob/main/resources/integrations/harnesses/pi.ts)、[内置 OpenCode](https://github.com/NexusFox88/docs/blob/main/resources/integrations/harnesses/opencode.ts)。下一步：[模型配置](https://docs.hexagon.autos/zh-CN/integrations/models.md)、[已验证组合](https://docs.hexagon.autos/zh-CN/integrations/verified-combinations.md)、[错误参考](https://docs.hexagon.autos/zh-CN/reference/errors.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.