鉴权排错 · 2026-08-04 生产实测

API 401 Invalid Token 排错

MonkeyAI 上的 HTTP 401 多半是鉴权问题，不是整站挂了。先看 JSON 里的 code，只改一条凭据路径，再用 GET /v1/models 复测，最后才动 agent 配置。

Base URL：https://monkeytheme.com/v1 见过的 code：API_KEY_REQUIRED · INVALID_API_KEY 安全探针：GET /v1/models

这里的 401 到底表示什么

结构化 401 说明网关已经应答，并且拒绝了你提交的凭据。它和空白网关页、TLS 失败、504 上游超时不是一类问题。

现象	含义	先做什么
HTTP 401 + JSON	鉴权层拒绝请求	看 `code` 和 Authorization 路径
HTTP 404 / model not found	鉴权可能已经通过	改用 `/v1/models` 里的模型 ID
HTTP 504	上游或代理超时	去看 504 文；换 Key 解决不了
SDK 超时且无 HTTP 状态码	客户端自己先放弃等待	先查网络/超时，而不是先改 Key 文本

生产环境实测响应

以下探测于 2026-08-04 打到 https://monkeytheme.com。未使用真实用户 Key。正文按线上 JSON 归纳。

请求形态	HTTP	code	message 摘要
没有 Authorization 头	`401`	`API_KEY_REQUIRED`	要求 Bearer / x-api-key / x-goog-api-key
Authorization: Bearer 但 token 为空	`401`	`API_KEY_REQUIRED`	同样是缺 Key 提示
Authorization: Basic …	`401`	`API_KEY_REQUIRED`	不接受 Basic；仍要求 Bearer 等方案
Authorization: Bearer sk-invalid-test-key-not-real	`401`	`INVALID_API_KEY`	Invalid API key
x-api-key: sk-invalid-test	`401`	`INVALID_API_KEY`	Invalid API key
x-goog-api-key: sk-invalid-test	`401`	`INVALID_API_KEY`	Invalid API key
POST /v1/chat/completions 不带 Key	`401`	`API_KEY_REQUIRED`	同样是缺 Key 提示

实用分界：code 是 API_KEY_REQUIRED 时，Key 根本没以可接受的头到达网关；code 是 INVALID_API_KEY 时，值已经送到但校验失败。缺头的问题，不要靠“再生成一把 Key”来碰运气。

复现两类失败

直接打公开网关。排查“缺头”时不要塞真实密钥。

# 1) 缺 Key → API_KEY_REQUIRED
curl -sS -i https://monkeytheme.com/v1/models | sed -n '1,20p'

# 2) 错误认证方案 → 本网关仍返回 API_KEY_REQUIRED
curl -sS -i https://monkeytheme.com/v1/models \
  -H "Authorization: Basic dGVzdA==" | sed -n '1,20p'

# 3) 有值但假 Key → INVALID_API_KEY
curl -sS -i https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer sk-invalid-test-key-not-real" | sed -n '1,20p'

# 4) 备选 Key 头同样可承载（无效值仍 401）
curl -sS https://monkeytheme.com/v1/models -H "x-api-key: sk-invalid-test"
curl -sS https://monkeytheme.com/v1/models -H "x-goog-api-key: sk-invalid-test"

错误文案里写明可接受的 Key 承载方式：Authorization: Bearer …、x-api-key、x-goog-api-key。OpenAI 兼容客户端仍应优先用 Bearer，除非某个客户端只支持其中一种备选头。

生产环境实测案例（2026 年 8 月 8 日）

以下数据来自一次真实的 journalctl -u sub2api --since '24 hours ago' 命令在网关主机上的执行结果。数字均为实测，未做人为调整。这是过去 24 小时内网关唯一发出的 401 响应，按客户端 IP 汇总。

指标	数值（24 小时窗口）
401 响应总数	84
`ingress_reject_reason: api_key_required`	60（71%）
`ingress_reject_reason: invalid_api_key`	24（29%）
`latency_ms` 范围	0 到 5 ms（平均 0.24 ms）
被命中的路径	`/v1/models`（48）、`/v1/responses`（15）、`/v1/chat/completions`（9）、`/v1/messages`（8）、`/v1/embeddings`（4）
客户端 IP 数量	3（65.49.150.250、65.49.151.65、2a02:4780:10:6b04::1）
GET 与 POST 分布	58 次 GET / 26 次 POST

同一窗口内的三类日志形态。前两类来自外部真实流量；第三类是窗口内唯一的内部 401，列出以便读者识别。

# (1) api_key_required — 请求头完全缺失，latency_ms 0
"path": "/v1/models", "method": "GET", "status_code": 401,
"latency_ms": 0, "client_ip": "65.49.150.250",
"ingress_reject_reason": "api_key_required"

# (2) invalid_api_key — 请求头存在但值无效，latency_ms 0 到 5
"path": "/v1/models", "method": "GET", "status_code": 401,
"latency_ms": 2, "client_ip": "65.49.150.250",
"ingress_reject_reason": "invalid_api_key"

# (3) upstream_failover_switching — 内部日志，并非客户端 401
#     表示上游返回 401，网关正在切换账号
"path": "/v1/chat/completions", "method": "POST",
"model": "gpt-5.6-sol", "account_id": 16,
"upstream_status": 401, "switch_count": 1, "max_switches": 10

如何读 latency。这 84 条客户端 401 的 latency_ms 都在 0 到 5 之间，说明网关在调用上游之前就已拒绝。如果你的 401 日志 latency_ms 是几百到几千毫秒，请求实际上到达了上游，应参考上面第 (3) 条 upstream_failover_switching 形态，或 504 文档中 latency_ms 大于 100 的形态。

本证据未覆盖的情形。过去 24 小时窗口内没有来自已认证流量的 401。以上每一条要么是请求头从未送达，要么是令牌从未有效。如果你的有效 Key 突然开始 401，请到「鉴权通过之后」一节检查：Key 是否被轮换、是否被吊销，或者请求是否被路由到了不识别该 Key 的上游。

按顺序处理

确认 Base URL 是 https://monkeytheme.com/v1（包含 /v1）。
确认请求头字面量是 Authorization: Bearer <key>：一个空格，Key 两侧不要加引号。
若 JSON code 是 API_KEY_REQUIRED，先查环境变量名、是否 export、客户端字段映射，再考虑新建 Key。
若 code 是 INVALID_API_KEY，从 MonkeyAI 后台重新复制，检查尾部空格/换行，并确认 Key 属于本站。
复测 GET /v1/models。只有返回模型列表后，再重启 Codex、Cline、Hermes 或其他 agent 客户端。
模型名必须精确。Key 对了但模型昵称不对，会掉进另一类错误。

客户端里最容易弄丢 Key 的位置

Shell / curl

环境变量没 export、变量名写错，或把头写成 Bearer: sk-... 而不是 Authorization: Bearer sk-...。

OpenAI SDK

api_key 为空，常见原因是进程启动早于 .env 加载。导出 Key 后要重启进程。

Codex CLI / 编程 agent

profile 指到别的 provider，或 env_key 指向当前 shell 里不存在的变量。

图形客户端

Base URL 漏了 /v1、把 Key 贴进模型框，或沿用了旧工作区缓存的 Key。

先不要动这些

不要因为 401 去改定价、模型目录或上游账号。
不要靠加长超时“修好” 401。超时只会盖住鉴权信号。
排查 MonkeyAI Key 时不要换成其他 hostname。
不要把完整 Key 贴进工单、截图或群聊。

鉴权通过之后

curl -sS https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer ***" | head -c 400

成功时应看到 JSON 模型列表，而不是空的 200 HTML。然后再发一条短 chat，最后才重连长运行 agent。

常见问题

HTTP 401 是不是说明 MonkeyAI 挂了？

通常不是。2026-08-04 在 https://monkeytheme.com/v1/models 上，缺 Key 或 Key 无效都会返回结构化 JSON 401，这是鉴权响应，不是整站宕机页。

API_KEY_REQUIRED 和 INVALID_API_KEY 有什么区别？

API_KEY_REQUIRED 表示网关没读到可用 Key（Authorization Bearer、x-api-key 或 x-goog-api-key）。INVALID_API_KEY 表示已经收到 Key 值，但校验失败。先修缺失头，再考虑重拷或轮换 Key。

别的产品或域名的 Key 会导致 401 吗？

会。MonkeyAI Key 对应 https://monkeytheme.com/v1。其他中转站、其他品牌后台，或不同 hostname 下的 Key，即使字符串长得很像，也可能直接 401。

工单或聊天里要不要贴完整 API Key？

不要。只提供末 4 位、完整 endpoint、UTC 时间、HTTP 状态码和 JSON 里的 code/message。如果 Key 已经泄露，先在后台作废再发新 Key。

Key 看起来修好后先测什么？

先打 GET /v1/models。返回模型列表后，再跑一次短 chat completion 或客户端请求。鉴权还没确认前，不要直接开长 agent 会话。