# API Connection Troubleshooting

> Diagnose slow or failing API calls after Hermes upgrades.

- Skill: `crimsonblazezero/api-connection-troubleshooting` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add crimsonblazezero/api-connection-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crimsonblazezero/api-connection-troubleshooting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: crimsonblazezero (https://skillmd.com/u/crimsonblazezero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/crimsonblazezero/api-connection-troubleshooting

---


# API 连接故障排查指南

当 Hermes Agent 出现 API 调用缓慢、超时或连接失败时，使用本 Skill 进行系统性诊断。

## 核心原则

**不要假设是客户端配置问题**。大多数"升级后变慢"的案例实际上是服务端延迟，而非客户端配置错误。

## 诊断流程

### 1. 验证配置是否正确

```bash
# 检查当前模型配置
hermes config get model

# 确认 api_mode 已显式设置（不应依赖默认值）
hermes config get model.api_mode
```

**关键检查点**：
- `api_mode` 应为 `chat_completions`（除非明确需要 Responses API）
- `base_url` 指向正确的网关
- `skip_provider_detection: true` 防止自动切换

### 2. 测试基础连通性

```bash
# 直接测试 API 端点（绕过 Hermes）
python3 -c "
import urllib.request, json
key = '<YOUR_API_KEY>'
req = urllib.request.Request('https://api.example.com/v1/models')
req.add_header('Authorization', f'Bearer {key}')
import time
start = time.time()
r = urllib.request.urlopen(req, timeout=10)
print(f'连通时间: {time.time()-start:.2f}s')
print(json.loads(r.read()))
"
```

**判断标准**：
- < 1s：服务端正常
- 1-5s：轻微延迟，可能正常
- > 5s：服务端有问题

### 3. 检查 Hermes 日志

```bash
# 查看最近 API 调用延迟
hermes logs | grep "latency="

# 查看超时错误
hermes logs | grep -i "timeout\|timed out"
```

**日志模式识别**：
- `latency=15s cache=...` → 服务端响应慢
- `APITimeoutError` → 请求超时（服务端无响应）
- `HTTP Error 400` → 客户端请求格式问题
- `HTTP Error 401` → 认证问题

### 4. Ping 测试（Windows）

```bash
ping apihub.agnes-ai.com
```

**注意**：ICMP 被拦截不代表 API 不通，但 100% 丢包值得记录。

## 常见误判案例

### 误判 1：认为 api_mode 自动切换

**症状**：升级后 API 调用变慢或失败
**错误归因**：认为客户端自动切换到 `codex_responses` 模式
**实际情况**：
- `api_mode` 已在 config.yaml 显式设置为 `chat_completions`
- OpenAI SDK 2.x 的 `client.beta.responses` 可能不存在
- 检查实际配置而非假设

### 误判 2：认为是 Session 脏数据

**症状**：第二句消息失败，第一句正常
**错误归因**：认为历史消息格式不兼容
**实际情况**：
- 检查 session 数据格式，确认是否有 `output_text` 类型
- 多数情况是服务端间歇性延迟

### 误判 3：忽略服务端延迟

**症状**：API 调用耗时 15-30s
**错误归因**：尝试各种客户端配置调整
**实际情况**：
- 直接测试 API 端点，测量实际延迟
- 检查服务端状态或联系服务商

## 快速诊断脚本

```python
import urllib.request, json, time, os

# 读取 API key
key = ''
with open(r'C:/Users/Administrator/AppData/Local/hermes/.env') as f:
    for line in f:
        if line.startswith('OPENAI_API_KEY='):
            key = line.strip().split('=',1)[1].strip('"').strip("'")
            break

# 测试连通性
url = 'https://apihub.agnes-ai.com/v1/models'
results = []
for i in range(3):
    start = time.time()
    try:
        req = urllib.request.Request(url)
        req.add_header('Authorization', f'Bearer {key}')
        r = urllib.request.urlopen(req, timeout=30)
        elapsed = time.time() - start
        data = json.loads(r.read())
        results.append(elapsed)
        print(f"Attempt {i+1}: {elapsed:.2f}s - OK ({len(data.get('data', []))} models)")
    except Exception as e:
        elapsed = time.time() - start
        results.append(elapsed)
        print(f"Attempt {i+1}: {elapsed:.2f}s - FAILED: {e}")

if results:
    print(f"\nMin: {min(results):.2f}s, Avg: {sum(results)/len(results):.2f}s, Max: {max(results):.2f}s")
```

## 参考资源

- `references/api-latency-patterns.md` — 常见 API 延迟模式与解决方案
- `references/hermes-config-checklist.md` — Hermes 配置检查清单