LLM Endpoint Doctor

English | 简体中文

输入一个 LLM 中转地址和 API Key，即可获得正确的 Base URL、支持的协议、 模型列表、流式输出状态、各协议的工具调用兼容性，以及可直接使用的客户端配置。

状态：可用的 V0.2 MVP。CLI 无运行时依赖。

什么时候需要它？

你拿到了一个 LLM 中转站、自建模型服务或 OpenAI-compatible API。普通聊天 似乎可以使用，但你并不确定它能否支持更复杂的工作流。

典型情况包括：

• 你想用中转站 API 构建智能体，但不知道它是否支持完整的工具调用循环。
• 你想让 Codex、Cline、OpenCode 或其他 Coding Agent 使用这个接口，但不确定 应该使用 Chat Completions 还是 Responses API。
• 你准备进行数据标注、批量分类或结构化信息抽取，需要先确认普通生成和流式响应 是否可靠。
• 你不知道 Base URL 是否需要添加 /v1，或者拿到的地址已经是完整 Endpoint。
• 普通对话能够成功，但模型调用工具后无法接收工具结果并继续生成。
• 你想使用 MCP，但不确定接口是否具备客户端侧 MCP 所需的 Function Calling 能力。
• 中转站声称兼容 OpenAI API，但你不知道它具体兼容哪些协议和模型。
• 同一个模型在官方 API 中可用，在中转站中却不断返回 400、404 或难以解释的 流式错误。

LLM Endpoint Doctor 会在正式接入之前执行自动发现和最小能力测试。它不会只验证 接口能否回答一句“你好”，而是尝试判断这个接口能否支撑真实应用、智能体和自动化 工作流。

它能回答什么

• Base URL 是否需要添加 /v1？
• 输入的是 Base URL，还是完整的 /chat/completions / /responses 地址？
• 中转站是否支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages？
• 能否读取 /models？应该优先测试哪个文本模型？
• SSE 流式输出是否真的产生了可识别事件？
• 每种协议能否完成完整的函数/工具调用闭环？
• 客户端 MCP 是否可能工作？通过哪种协议工作？
• Responses 端点是否通过 Codex 的普通请求、流式输出和完整 Agent 检测？

“客户端 MCP 可能可用”只表示普通函数调用闭环成功。它不代表支持 OpenAI 托管 MCP、Anthropic MCP Connector、联网搜索、文件搜索、Computer Use 或其他 由供应商托管的工具。

当前版本也不会验证 JSON Schema / Structured Outputs 的长期稳定性，且尚未生成 Cline 或 OpenCode 的专用配置模板。这些能力列在路线图中，不会被当前报告误标为 已经验证。

运行要求

• Node.js 20 或更高版本
• 从源码目录运行时不需要执行 npm install

安装

全局安装 CLI：

npm install -g llm-endpoint-doctor
endpoint-doctor --version

也可以不进行全局安装：

npx llm-endpoint-doctor probe https://api.example.com

面向 Agent 的本地 JSON

只需提供 Base URL，Codex 或其他 Agent 就可以创建本地配置：

endpoint-doctor init https://api.example.com --model gpt-5

该命令会生成 .endpoint-doctor.local.json：

{
  "baseUrl": "https://api.example.com",
  "apiKey": "PASTE_API_KEY_HERE",
  "apiKeyEnv": null,
  "model": "gpt-5",
  "quick": false,
  "aggressive": false,
  "timeoutMs": 15000,
  "maxCandidates": 4,
  "requirements": [],
  "output": "report.json"
}

用户只需要替换 PASTE_API_KEY_HERE，之后 Agent 可以直接运行：

endpoint-doctor probe

CLI 会自动发现默认本地配置，该文件已加入 .gitignore。但它仍然是包含明文 密钥的文件：不要提交、上传、打印或粘贴到聊天中。在 CI 或共享机器上，建议保留 API Key 占位符，并将 apiKeyEnv 设置为机密环境变量的名称。

仓库中提供了可以提交的 endpoint-doctor.example.json 模板。也可以显式指定其他 本地配置路径：

endpoint-doctor probe --config ./private/relay.json

当本地配置提供密钥时，如果命令行传入了不同的 URL，CLI 会拒绝执行，避免密钥被 静默发送到其他端点。

直接使用 CLI

export API_KEY='sk-...'
endpoint-doctor probe https://api.example.com --key-env API_KEY

也可以直接从源码目录运行：

node ./bin/endpoint-doctor.mjs probe https://api.example.com --key-env API_KEY

工具可能会产生若干次小额计费的模型请求。使用 --quick 可以只进行模型发现和 基础协议检测。

常用选项：

--config FILE            读取本地 JSON 配置
--quick                  跳过流式和工具闭环测试
--aggressive             额外尝试 /api/v1、/openai/v1 等路径
--model MODEL            指定模型，不从 /models 自动选择
--require LIST           要求指定能力，缺失时返回退出码 2
--json                    输出机器可读的 JSON
--out report.json        保存可复用的报告
--timeout 30000          单次请求超时，单位为毫秒
--max-candidates 4       限制候选 URL 数量

自动化能力要求

Agent 和 CI 可以声明精确的能力要求，而不需要解析人类可读输出：

endpoint-doctor probe --config .endpoint-doctor.local.json \
  --require openai-responses,openai-responses-stream,openai-responses-tools

退出码 0 表示所有要求均已通过。退出码 2 表示报告已经生成，但至少一项能力 要求未通过。可用名称如下：

openai-chat                 openai-chat-stream       openai-chat-tools
openai-responses            openai-responses-stream  openai-responses-tools
anthropic                   anthropic-stream         anthropic-tools
codex-basic                 codex-stream             codex-agent
client-mcp                  any-stream               any-tools

codex-agent 使用严格判断：Responses 普通生成、SSE 流式输出和 Responses 函数/工具续接必须全部通过。只有 Chat Completions 工具闭环成功，不会再让端点被 判定为兼容 Codex Agent。

生成客户端配置

endpoint-doctor config report.json --target codex
endpoint-doctor config report.json --target curl
endpoint-doctor config report.json --target openai-js

检测到可用的 Responses API 后，工具会生成 Codex 配置。如果完整 Codex Agent 兼容性没有通过，生成的配置会包含警告，而不会把端点描述为已经完整验证。

工具闭环测试

测试会向模型提供一个无副作用的函数：

get_magic_number() -> 42

模型必须调用它，并在收到结果后返回 84。这可以发现某些网关虽然接受 tools， 但在回传 tool / function_call_output 结果后失败的问题。

安全说明

• 优先使用本地 JSON、--key-env 或 apiKeyEnv，避免通过 --key 把密钥写入命令历史。
• .endpoint-doctor.local.json 已被 Git 忽略，但其中包含明文密钥。
• 密钥不会写入诊断 JSON 报告。
• CLI 不会保存完整请求头。
• 配置中的密钥不能配合另一个命令行 URL 使用。
• 测试使用很短的提示词，但仍可能产生上游费用。
• 工具不会直接修改任何客户端配置文件。

当前范围

V0.2 已包含：

• URL 规范化和 /v1 路径发现
• OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages
• 使用 Bearer 与 Anthropic 两种认证方式尝试获取模型列表
• 普通生成、SSE 流式输出和完整函数/工具续接
• 按协议分别判断工具能力和 Agent 就绪状态
• 自动发现面向 Agent 的本地 JSON
• 可由机器强制检查的能力要求和退出码
• 人类可读报告和 JSON 报告
• Codex、curl、环境变量和 OpenAI JavaScript 配置输出

尚未包含：

• 操作系统钥匙串凭据存储
• Codex Skill、插件或 MCP Server 封装
• 托管 MCP 执行
• 供应商托管的 web_search、file_search、computer 或代码解释器
• Chat Completions ↔ Responses 代理模式
• GUI、密钥轮换、计费、路由或负载均衡

开发

npm test
npm run check

测试使用本地 Mock 中转站，覆盖全部三种协议。两个命令均可跨平台运行。

贡献与安全

提交 Pull Request 前请阅读 CONTRIBUTING.md。安全漏洞请按照 SECURITY.md 中的流程报告，不要在公开 Issue 中粘贴有效 API Key 或私有端点。

路线图

1. 增加操作系统钥匙串支持，并将明文本地 JSON 保留为显式备用方案。
2. 增加本地 STDIO MCP Server 和 Codex Skill，再将二者打包为插件。
3. 增加推理内容丢失和流式工具调用格式错误等诊断特征。
4. 增加默认关闭的托管工具探针。
5. 为 Agent 驱动的数据集生成增加带预算限制的本地代理。

许可证

MIT