DeepAI Paper Hermes Agent 教程 hermes doctor 说 DashScope key 无效，但接口明明 200：一次区域端点误判复盘

hermes doctor 说 DashScope key 无效，但接口明明 200：一次区域端点误判复盘

2026年5月15日2026年5月15日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 上午2:25
Categories:

hermes doctor 的价值，是帮你快速判断环境能不能跑。

但健康检查也可能误判。

NousResearch/hermes-agent issue #18904 记录了一个典型案例：用户配置了中国区 Alibaba DashScope / Bailian API Key，实际请求中国区接口能返回 HTTP 200，WebSearch MCP 也能初始化成功；但 hermes doctor 仍然输出：

Checking Alibaba/DashScope API...
✗ Alibaba/DashScope    (invalid API key)

这类问题最容易把人带偏：看到 invalid API key，就开始反复换 key、重置环境变量、怀疑账号权限。

但这个 issue 的关键不在 key。

而在：

doctor 探测的 DashScope endpoint 和实际可用的区域 endpoint 不一致。

现象：doctor 报 invalid，直接请求却成功

issue 里给出的验证结果很直接。

同一个 DASHSCOPE_API_KEY，直接访问中国区 DashScope / Bailian endpoint 可以成功：

GET  https://dashscope.aliyuncs.com/compatible-mode/v1/models  -> HTTP 200
GET  https://dashscope.aliyuncs.com/api/v1/models              -> HTTP 200
POST https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp  -> HTTP 200

MCP initialize response 也返回了正常的：

BaiLianMcpServer

这说明 key 至少不是“完全无效”。

但 hermes doctor 却仍然显示：

Alibaba/DashScope (invalid API key)

这就不是简单的密钥错误了。

根因方向：国际站 endpoint 和中国区 endpoint 混用

issue 怀疑点在 hermes_cli/doctor.py 的 Alibaba / DashScope API key 检查。

健康检查可能默认探测：

https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models

但中国区 DashScope / Bailian key 的工作 endpoint 是：

https://dashscope.aliyuncs.com/compatible-mode/v1/models

如果你的 key、账号、网络环境都属于中国区，那么国际站 endpoint 失败并不代表 key 无效。

它只能说明：

这个 key 在当前 doctor 选用的 endpoint 上不可用。

这和：

API key invalid

不是一回事。

评论里的二次复现：v0.13.0 仍可能误判

issue 评论中还有一个后续复现：在 Hermes Agent v0.13.0、WSL 环境下，DashScope 中国区 endpoint 实际可用：

  • base URL：
  https://dashscope.aliyuncs.com/compatible-mode/v1
  • 直接 GET /models 返回 HTTP 200
  • 直接 POST /chat/completions 返回 HTTP 200

但 hermes doctor 仍然探测：

https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models

并因为 SSL EOF / 区域访问问题失败。

所以评论里的判断是：

这更像 endpoint selection / region mismatch false negative，不是 bad API key。

这句话很关键。

如果你看到 doctor 报 invalid，不要立刻认定 key 错了；要先确认 doctor 到底请求了哪个 endpoint。

为什么健康检查容易误导？

健康检查通常会把复杂失败简化成一个状态。

例如：

valid
invalid
missing

但真实 API 调用失败可能有很多原因：

  • key 真的错；
  • key 属于另一个区域；
  • base URL 配错；
  • 默认 endpoint 不适合当前账号；
  • 网络到国际站不可达；
  • TLS / proxy / WSL 环境问题；
  • provider 的 OpenAI-compatible endpoint 和原生 endpoint 不同。

如果 doctor 把这些都归类为：

invalid API key

用户就会走错排查方向。

#18904 的价值就在这里：它把“密钥无效”和“区域 endpoint 不匹配”拆开了。

正确排查顺序

如果你遇到：

✗ Alibaba/DashScope (invalid API key)

不要先重置 key。

先按下面顺序查。

1. 确认环境变量是否存在

printenv DASHSCOPE_API_KEY | wc -c

不要把 key 打到终端或截图里。

只确认长度不为 0。

2. 直接请求中国区 models endpoint

curl -sS \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  https://dashscope.aliyuncs.com/compatible-mode/v1/models \
  -o /tmp/dashscope-models.json \
  -w "HTTP %{http_code}\n"

如果返回：

HTTP 200

说明 key 在中国区 compatible-mode endpoint 上可用。

3. 再测国际站 endpoint

curl -sS \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models \
  -o /tmp/dashscope-intl-models.json \
  -w "HTTP %{http_code}\n"

如果中国区成功、国际站失败，就不要再把问题叫作“key invalid”。

更准确的描述是：

DashScope region / endpoint mismatch

4. 检查 Hermes 是否尊重自定义 base URL

如果你配置了：

DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

但 doctor 仍然去探测 dashscope-intl.aliyuncs.com，那就是健康检查路径没有正确使用你的区域配置。

更好的 doctor 输出应该怎么写？

issue 里给了几个修复方向，比较合理：

方案一：尊重 DASHSCOPE_BASE_URL

如果用户已经显式配置：

DASHSCOPE_BASE_URL

doctor 应优先探测这个 base URL，而不是固定默认国际站。

方案二：两个区域都试一下

在宣布 key invalid 前，先分别尝试：

https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models
https://dashscope.aliyuncs.com/compatible-mode/v1/models

只要其中一个成功，就不要报 invalid key。

方案三：把错误文案改准

如果中国区成功、国际站失败，输出应该类似：

DashScope key works on China endpoint, but intl endpoint failed. Check DASHSCOPE_BASE_URL / region.

而不是：

invalid API key

方案四：MCP 和模型推理分开测

issue 里还提到 WebSearch MCP。

MCP 可用不一定代表所有模型推理 endpoint 都可用；反过来也一样。

如果 key 用于 MCP 服务，doctor 最好把 MCP health check 和 model inference health check 分开。

和 DeepAI API 中转站有什么关系？

这篇不是 DeepAI 的故障，但对使用 DeepAI API 中转站的人有一个很重要的启发：

健康检查失败，不一定等于 key 错；也可能是 base URL / region / provider mode 错。

DeepAI API 中转站通常使用 OpenAI-compatible 入口，例如：

https://api.deepai.wang/v1

如果客户端或健康检查没有尊重你配置的 base URL，而是硬编码去探测某个官方 endpoint，就可能出现类似误判：

  • 实际聊天接口可用；
  • 手动 curl 可用；
  • 但 doctor / validator 报 invalid；
  • 根因是健康检查走了另一条 URL。

所以对 DeepAI 用户来说，排查重点也是：

1. 实际请求打到哪里； 2. health check 打到哪里； 3. 两者是否一致； 4. OpenAI-compatible base URL 有没有被验证链路正确继承。

但边界也要说清楚：DeepAI 不能修复 Hermes 的 DashScope doctor 逻辑。这里借 DeepAI 说明的是同类排查方法，不是说 DeepAI 参与了 DashScope 的修复。

FAQ

hermes doctor 报 invalid API key，一定是 key 错了吗？

不一定。#18904 里的 key 对中国区 endpoint 可用，但 doctor 探测国际站 endpoint 后误报 invalid。

DashScope 中国区 endpoint 是哪个？

issue 中验证可用的是：

https://dashscope.aliyuncs.com/compatible-mode/v1/models

国际站 endpoint 是哪个？

issue 中怀疑 doctor 默认探测的是：

https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models

如果中国区 200、国际站失败，应该怎么判断？

更像 region / endpoint mismatch，不应该直接叫 invalid API key。

这个问题和 DeepAI 有关系吗？

不是 DeepAI 故障。但它提醒所有 OpenAI-compatible API 用户：health check 必须和实际 base URL 一致，否则会误判。

总结

#18904 的核心教训是：

不要把 endpoint mismatch 简化成 invalid API key。

当 hermes doctor 报 DashScope key 无效，但你手动请求中国区 endpoint 返回 HTTP 200 时，应该优先检查：

  • doctor 是否固定探测了 dashscope-intl.aliyuncs.com；
  • 你的 key 是否属于中国区 DashScope / Bailian；
  • DASHSCOPE_BASE_URL 是否被 doctor 尊重；
  • 模型推理和 MCP 检查是否被混在一起。

健康检查应该帮用户缩小问题，而不是把区域不匹配伪装成密钥错误。

Related Post

Matrix/Telegram 突然报 cannot import cfg_get？Hermes Gateway 升级后旧代码未重启排查Matrix/Telegram 突然报 cannot import cfg_get？Hermes Gateway 升级后旧代码未重启排查

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午7:21

Hermes 升级后 Matrix、Telegram、飞书突然报 cannot import name cfg_get？这通常不是平台配置或模型 API 问题，而是 Gateway 仍在运行旧代码/旧 import 状态。本文解释为什么 /reset 无效、gateway restart 有效，以及多 profile/system service 排查方法。

Read MoreRead More

Hermes Agent 辅助任务报 401？provider:auto、base_url 与空 api_key 排错指南Hermes Agent 辅助任务报 401？provider:auto、base_url 与空 api_key 排错指南

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午5:22

Hermes Agent 主模型能用，但 auxiliary title_generation 报 401 Missing Authentication header？可能是 provider:auto/openrouter 搭配 base_url 和空 api_key 被误判成 custom provider，跳过 OPENROUTER_API_KEY 环境变量读取。本文给出配置排查、workaround 和修复方向。

Read MoreRead More

Hermes 安装卡在 [sudo] password：非 sudo 用户遇到 Playwright –with-deps 的半安装问题Hermes 安装卡在 [sudo] password：非 sudo 用户遇到 Playwright –with-deps 的半安装问题

2026年5月15日2026年5月15日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 上午3:23

在 Debian 上用非 sudo 服务用户安装 Hermes 时，安装器可能卡在 Playwright Chromium 的 `npx playwright install --with-deps chromium` sudo 密码提示，且发生在 setup_path 之前，导致没有 hermes 命令和 hermes doctor。本文客观复盘 #25816 的触发条件、安装顺序和降级处理。

Read MoreRead More