简体中文 · English
一个只依赖 Go 标准库的命令行工具，用来快速验收任何 OpenAI 兼容 API 的接入配置。 它适用于自建网关、云服务、企业代理和独立第三方中转站，不把任何供应商写死在代码里。
默认是只读检查。 工具只请求
GET /models；只有你明确同时传入--chat和--model时，才会发送一次固定的最小聊天请求。它不会自动选择模型、上传文件、启用工具调用或开启流式输出。
“Base URL、Key、模型名都填了”并不代表兼容性真的成立。这个工具把最常见的验收步骤固定下来：
- 检查 URL 是否明确、是否使用 HTTPS，以及是否误带查询参数或用户信息；
- 验证
/models是否返回标准的data数组； - 可选验证
/chat/completions是否接受一个最小请求； - 把认证失败、限流、上游故障、网络/TLS、端点和响应格式问题分开归类；
- 输出主机、路径、状态、延迟和模型数量，不输出 Authorization、响应正文或聊天内容。
Go 1.22 是最低源码兼容版本。安装和生产构建应使用仍受 Go 团队支持的最新补丁工具链，不要使用已停止安全更新的 Go 1.22.x 生产构建。
go install github.com/airouter-dev/openai-compatible-api-smoke-test/cmd/oai-smoke@latestmacOS 或 Linux 用户也可以从维护方的 Homebrew tap 安装带固定校验和的发布归档：
brew install airouter-dev/tap/oai-smoketap 的合并门禁会在 Intel macOS、Apple Silicon macOS 与 Linux 上执行 Homebrew 审计、真实安装和功能测试。
从 v0.1.2 开始，GitHub Release 同时提供 Linux、macOS 与 Windows 的
AMD64/ARM64 归档、checksums.txt 和 GitHub artifact attestation。
下载归档与同一版本的校验文件后，先执行校验再安装：
sha256sum --check checksums.txt --ignore-missingmacOS 可使用 shasum -a 256 -c checksums.txt。安装 GitHub CLI 后还可以验证
制品证明：
gh attestation verify oai-smoke_0.1.2_darwin_arm64.tar.gz \
--repo airouter-dev/openai-compatible-api-smoke-test也可以从 canonical GitHub 仓库克隆后在本地构建：
go build -trimpath -ldflags='-s -w' -o oai-smoke ./cmd/oai-smoke源码和 Go module tag 的权威上游是 https://github.com/airouter-dev/openai-compatible-api-smoke-test。其它代码托管镜像不是 Go module 的发布权威源。
工具不会内置默认服务地址，避免误把测试请求发到错误的上游。API Key 只从环境变量读取，命令行参数里没有 --api-key：
export OPENAI_API_KEY='在当前 shell 中临时设置自己的 Key'
oai-smoke \
--base-url https://api.example.com/v1 \
--models-only成功时会报告模型数量。若要进行一次真实聊天验收，必须显式指定模型；请求正文是固定的 Reply with OK.，并限制 max_tokens=8：
oai-smoke \
--base-url https://api.example.com/v1 \
--chat \
--model YOUR_MODEL_ID本地 mock 服务可使用 HTTP，但必须明确加 --allow-http，且地址只能是 localhost、127.0.0.1 或 ::1：
oai-smoke --base-url http://127.0.0.1:8080/v1 --allow-http --no-auth如果供应商使用不同的环境变量名：
export MY_PROVIDER_KEY='...'
oai-smoke --base-url https://gateway.example/v1 --api-key-env MY_PROVIDER_KEY人类可读输出只包含安全诊断，例如：
target: https://gateway.example/v1
mode: models-only
[PASS] GET /v1/models status=200 latency=42.7ms models=3
summary: PASS
自动化场景使用 --json。JSON 的顶层 schema 固定为 oai-smoke/v1，可安全存档：
{
"schema": "oai-smoke/v1",
"success": true,
"target": "https://gateway.example/v1",
"mode": "models-only",
"checks": [
{
"name": "models",
"method": "GET",
"path": "/v1/models",
"success": true,
"status_code": 200,
"latency_ms": 42.7,
"model_count": 3
}
]
}| 退出码 | 类别 | 常见含义 |
|---|---|---|
| 0 | success | 所选检查全部通过 |
| 2 | config | URL、Key、模型或参数不合法 |
| 3 | network | DNS、连接、超时或 TLS 失败 |
| 4 | auth | HTTP 401/403 |
| 5 | endpoint / schema | 路径、协议或响应结构不符合预期 |
| 6 | rate_limit | HTTP 429 或额度限制 |
| 7 | server | HTTP 5xx |
工具检查的是常见的 OpenAI 风格约定，而不是宣称所有供应商完全等价：
GET <base-url>/models返回 JSON，并含数组字段data；--chat时，POST <base-url>/chat/completions接受model、messages、max_tokens和stream=false；- 成功聊天响应含非空
choices数组。
如果你的网关使用自定义路径，请把完整路径放入 --base-url，例如 https://host/custom/v1。模型 ID 必须由你明确指定；工具不会把第一个模型当成“默认模型”。
- HTTPS 是默认要求；
--allow-http只对回环地址生效。 - 拒绝 URL 查询串、片段和用户信息，避免把密钥或临时参数误放入地址。
- 跨源重定向会被阻止，防止 Authorization 被带到另一台主机。
- 使用系统 CA、请求超时和 1 MiB 默认响应上限；不会无限读取响应。
- Key 只在进程内存中使用，不写文件、不发送遥测、不打印日志。
- 启用认证时，Key 中的 CR 或 LF 会在构造请求前被拒绝。
- 聊天检查的模型 ID 必须是有效 UTF-8，只包含可打印 Unicode 字符，首尾无空白且不超过 256 字节。
- 错误正文、模型响应正文和生成内容不会进入报告；只保留状态和静态错误类别。
- 默认只读
/models；聊天检查是显式选择，可能产生上游费用，请先确认服务商规则。
完整的威胁模型与剩余风险见 docs/THREAT_MODEL.md。
把 Key 配置为 GitHub Actions Secret 或 GitLab masked/protected variable，不要写入 YAML：
smoke:
script:
- go run ./cmd/oai-smoke --base-url "$OPENAI_BASE_URL" --api-key-env OPENAI_API_KEY --models-only --json仓库自带的 CI 只运行本地测试和静态检查，包括跨平台测试、格式检查、go vet、race detector 与 govulncheck；不会访问任何真实模型 API。
本项目由 AI-ROUTER 维护，但 CLI 不包含默认服务商、默认端点、默认模型、遥测、返利行为或任何服务商专属运行时代码。该维护关系不代表 OpenAI、Anthropic 或其他服务商的联属、认证或背书。
make test
make vet欢迎提交兼容性案例、错误分类改进和测试。请不要提交真实 Key、生产 URL 中的临时签名参数或包含用户内容的日志。详见 CONTRIBUTING.md。
MIT. See LICENSE.