Gateway HTTP API
ATM Gateway 同时暴露 模型入口（Agent 流量）和 管理接口（签 key、查日志等）。全部绑定在 127.0.0.1:4317。仅回环，永远不会被另一台机器访问。
健康检查与帮助
GET /health
{ "status": "ok", "timestamp": 1775649906 }
GET /help
可读的 HTML 页面，列出网关所有接口。忘记 API 表面时直接浏览器打开。
模型入口
| 路径 | 协议 | 鉴权 |
|---|---|---|
POST /v1/chat/completions |
OpenAI Chat | Authorization: Bearer atm-… |
POST /v1/responses |
OpenAI Responses（Codex） | Authorization: Bearer atm-… |
POST /v1/messages |
Anthropic Messages | x-api-key: atm-… 或 Authorization: Bearer atm-… |
POST /v1beta/models/{model}:generateContent |
Gemini | x-goog-api-key: atm-… 或 Authorization: Bearer atm-… |
上游支持时，流式响应以 SSE 透传。
签发 key
POST /api/keys/issue
Content-Type: application/json
字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
employeeName |
string | 是 | 人类拥有者展示名。 |
employeeContact |
string | 是 | 推荐邮箱。 |
employeeTeam |
string | 否 | |
employeeRole |
string | 否 | |
agentName |
string | 是 | Agent 展示名。 |
agentType |
string | 是 | claude_code、codex、openclaw_main、openclaw_subagent、generic_agent 等。 |
parentAgentId |
string | 否 | 特化 Agent 必填。 |
parentAgentName |
string | 否 | 仅展示。 |
sourceTool |
string | 否 | 按惯例为工具名。 |
configPath |
string | 否 | Agent 原生配置位置。 |
policyId |
string | 否 | 默认 default。Codex 用 codex_default。 |
成功响应：
{
"employeeId": "emp_self_xxx",
"agentId": "agent_self_xxx",
"policyId": "default",
"keyId": "key_xxx",
"keyPrefix": "atm_a380...",
"keyValue": "atm_a3800987dbb545cebac19163fa702143",
"createdAt": 1775649985
}
keyValue 仅在签发时显示一次。ATM 只存盐处理过的前缀，永远不存原值。丢失就重新签发。
给已有 key 的 Agent 再次签发会轮换。 旧 key 立刻
401。
限流：同 Agent 5 秒 1 次。超过返回 429 Too Many Requests。
调用 /api/keys/issue 不需要鉴权。任何能访问 127.0.0.1:4317 的进程都能签 key（这是合理的，因为是回环）。
列出身份、key、日志、用量
GET /api/agents
返回已知 Agent 列表，带父子关系、当前路由、绑定策略。
GET /api/keys
返回已签发 key（前缀 + 元数据；原值永不返回）。
GET /api/logs
返回最近的网关请求日志。支持查询参数：
| 参数 | 说明 |
|---|---|
agent_id |
按 Agent 过滤。 |
policy_id |
按策略过滤。 |
status |
2xx、4xx、5xx、fallback。 |
since |
Unix 时间戳（秒）。 |
limit |
最大行数，默认 50。 |
每行带身份、target、resolved、token 数、延迟、错误信息（如有）。
GET /api/usage
返回聚合用量。支持同样的过滤，加 pivot 参数（agent、key、provider、model、project）。
状态码
| 码 | 含义 |
|---|---|
200 |
成功。 |
400 |
错误请求（请求体格式错、伪造 atm-… key 前缀、跨家族策略 target 等）。 |
401 |
缺 key 或 key 已撤销。 |
404 |
路径或资源不存在。 |
429 |
限流（目前只有 /api/keys/issue 上有）。 |
502 |
上游不可恢复错误且没有可用 fallback。 |
503 |
所有兼容 Provider 都被熔断打开。 |
示例
健康检查：
curl -s http://127.0.0.1:4317/health
签发并捕获 key：
KEY=$(curl -s -X POST http://127.0.0.1:4317/api/keys/issue \
-H 'Content-Type: application/json' \
-d '{
"employeeName": "Alice",
"employeeContact": "alice@example.com",
"agentName": "My Generic Agent",
"agentType": "generic_agent",
"policyId": "default"
}' | jq -r .keyValue)
echo "$KEY"
发真实请求：
curl -s -X POST http://127.0.0.1:4317/v1/chat/completions \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{"messages":[{"role":"user","content":"Reply with: pong"}]}'
验证：
curl -s "http://127.0.0.1:4317/api/logs?limit=1" | jq