问题现象

在 Hermes CLI 中配置 Azure OpenAI 模型（gpt-5.5）后，启动对话时提示连接错误：

🧾 Request debug dump written to: .../request_dump_*.json

错误 dump 内容：

{
  "reason": "max_retries_exhausted",
  "error": {
    "type": "APIConnectionError",
    "message": "Connection error."
  }
}

排查过程

1. DNS 解析异常

首先检查 Azure 端点的 DNS 解析：

nslookup ***-aibot.cognitiveservices.azure.com
# 返回 198.18.8.143

198.18.x.x 是 Clash 虚拟网卡（TUN 模式）的 Fake IP 地址。这表示 Clash 拦截了 DNS 请求并返回了虚拟 IP，该 IP 仅在 Clash 运行时有效。

进一步排查发现，即使用 Google DNS（8.8.8.8）查询，该域名也返回 NXDOMAIN（域名不存在）。

2. Clash TUN 模式残留路由规则

Clash 关闭后，系统路由表中残留了大量 TUN 模式的路由规则：

netstat -rn -f inet | grep utun1500
# 1       198.18.0.1   UGSc   utun1500
# 128.0/1 198.18.0.1   UGSc   utun1500
# ...

这些规则将所有流量通过虚拟网卡 utun1500 发往 198.18.0.1。Clash 停止运行后，这个网关成为死点，所有网络请求都无法到达目的地。

这也是为什么关闭 Clash TUN 模式后，Claude Code 也一度无法使用网络。

3. API 端点路径不匹配

请求 dump 显示 Hermes 发送请求到 /openai/v1/responses（OpenAI Responses API），但 Azure OpenAI 只支持 Chat Completions API。

正确的 Azure Chat Completions 端点格式为：

https://{资源名}.openai.azure.com/openai/deployments/{部署名}/chat/completions?api-version=2024-12-01-preview

4. Azure 端点域名格式错误

最关键的问题：Azure 控制台提供的示例代码使用的是 https://***-aibot.cognitiveservices.azure.com/，但该域名的 DNS 记录实际上不存在。

通过查询 ***-aibot.openai.azure.com 发现该域名正常解析：

dig +short ***-aibot.openai.azure.com @8.8.8.8
# swedencentral.api.cognitive.microsoft.com.
# ...
# 51.12.73.214  ← 瑞典中部区域

Azure OpenAI 应使用 openai.azure.com 而非 cognitiveservices.azure.com 作为端点域名。

最终解决方案

第一步：清理 Clash TUN 残留路由

在终端执行（需 sudo 密码）：

# 删除 Clash TUN 路由规则
sudo route delete -net 1 -interface utun1500
sudo route delete -net 128.0/1 -interface utun1500
# ... 其他规则

# 删除虚拟网卡
sudo ifconfig utun1500 destroy

# 刷新 DNS 缓存
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

也可以通过 Clash Party 的 UI 界面直接关闭虚拟网卡模式。

第二步：修改 Hermes Provider 配置

将主 provider 从 azure-foundry（内置的 Responses API 模式）改为自定义 provider：

# ~/.hermes/config.yaml
model:
  default: gpt-5.5
  provider: custom:azure-gpt      # 改用自定义 provider

自定义 provider 配置正确的端点：

custom_providers:
- name: azure-gpt
  base_url: https://***-aibot.openai.azure.com/openai/deployments/gpt-5.5?api-version=2025-04-01-preview
  api_key: <your-api-key>
  api_mode: chat_completions    # 使用 Chat Completions 模式

第三步：保持 Clash HTTP 代理运行

由于 Azure OpenAI 部署在海外（瑞典中部），需要代理才能连接。Clash 的 HTTP 代理（127.0.0.1:7890）正常运行时即可，不需要开启 TUN 模式。

第四步：修复标题生成 temperature 错误（可选）

如果遇到标题生成报错：

Unsupported value: 'temperature' does not support 0.3 with this model

在 Hermes 配置中添加：

auxiliary:
  title_generation:
    extra_body:
      temperature: 1

经验总结

  1. Azure OpenAI 端点域名：优先使用 {name}.openai.azure.com 而不是 {name}.cognitiveservices.azure.com
  2. Clash TUN 模式：关闭 TUN 模式后务必检查并清理残留的路由规则，否则整个系统网络都会受影响
  3. Hermes Provider 类型：azure-foundry 内置 provider 使用的是 OpenAI Responses API，Azure 暂不支持，应改用 custom:azure-gpt 并配合 chat_completions 模式