Claude Provider 故障切换与会话恢复#

这是完整实操指南，解决以下问题：

  • 报 Improperly formed request 后对话无法恢复
  • 自动切换供应商后仍持续报错
  • 需要把当前失败现场保存下来，换新会话继续
  • API 代理频繁返回 502/500 错误
  • Stream 中断导致响应不完整

核心原理#

1. 故障切换机制#

Claude Code 的 Provider 切换机制：

触发条件行为日志标识
API 返回错误自动切换到备用 ProviderFO-001
手动执行 cc-switch立即切换 ProviderFWD-001
切换失败回退到原 ProviderFWD-002

重要：

  • 切换对下一次请求生效，不会修复当前正在失败的请求
  • 单次请求会执行重试链（attempt 1/11 ... 11/11）
  • 重试期间不会触发 Provider 切换

2. 常见错误类型#

错误原因解决方案
Improperly formed requestAPI 请求格式错误切换 Provider 或检查配置
502 Bad Gateway代理服务器故障更换代理或直连
500 Internal Server Error上游服务错误等待恢复或切换 Provider
Stream completed without message_start流式响应中断重试或切换 Provider
Connection error网络连接失败检查网络或代理

快速诊断（5 步检查）#

步骤 1：检查配置文件中的 Provider 设置#

$cfgPath = Join-Path $HOME '.claude/settings.json'
$cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json
$e = $cfg.env
[pscustomobject]@{
  BASE_URL  = $e.ANTHROPIC_BASE_URL
  MODEL     = $e.ANTHROPIC_MODEL
  TOKEN_SET = [bool]($e.ANTHROPIC_AUTH_TOKEN -and $e.ANTHROPIC_AUTH_TOKEN.Length -gt 0)
} | Format-Table -AutoSize

预期输出：

BASE_URL                          MODEL                    TOKEN_SET
--------                          -----                    ---------
https://api.example.com/v1        claude-opus-4-6          True

步骤 2：检查环境变量（可能覆盖配置）#

[pscustomobject]@{
  ENV_BASE_URL  = $env:ANTHROPIC_BASE_URL
  ENV_MODEL     = $env:ANTHROPIC_MODEL
  ENV_TOKEN_SET = [bool]($env:ANTHROPIC_AUTH_TOKEN)
} | Format-Table -AutoSize

注意：环境变量优先级高于配置文件，如果设置了环境变量会覆盖配置。

步骤 3：测试 Provider 连通性#

$u = [uri]$e.ANTHROPIC_BASE_URL
Test-NetConnection -ComputerName $u.Host -Port $u.Port |
  Select-Object ComputerName, RemotePort, TcpTestSucceeded |
  Format-Table -AutoSize

预期输出：

ComputerName       RemotePort TcpTestSucceeded
------------       ---------- ----------------
api.example.com    443        True

步骤 4：定位最新日志文件#

$log = Get-ChildItem "$HOME/.claude/debug/*.txt" -ErrorAction SilentlyContinue |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1
$log.FullName

步骤 5：分析错误日志#

Get-Content $log.FullName -Tail 160 |
  Select-String 'API error|Improperly formed request|request id|non-streaming fallback|Connection error|attempt [0-9]+/11|FO-001|FWD-001|FWD-002|502|500'

关键日志标识：

  • FO-001: 自动故障切换
  • FWD-001: 手动切换成功
  • FWD-002: 切换失败回退
  • attempt 11/11: 重试耗尽
  • 502 Bad Gateway: 代理故障
  • Stream completed without message_start: 流式响应中断

故障恢复流程#

场景 1：切换后仍然报错#

症状：执行 cc-switch 后，下一次请求仍然失败。

原因：

  1. 环境变量覆盖了配置文件
  2. 新 Provider 也存在问题
  3. 当前终端会话缓存了旧配置

解决步骤：

  1. 立即中断当前请求（不要等 11/11 跑完）

    Ctrl+C

  2. 清理环境变量

    Remove-Item Env:ANTHROPIC_BASE_URL -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_MODEL -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_AUTH_TOKEN -ErrorAction SilentlyContinue

  3. 重启 Claude Code CLI

    exit  # 退出当前会话
claude  # 重新启动

  4. 发送探针测试

    ping

    等待响应成功后再继续长任务。

场景 2：频繁出现 502 错误#

症状：日志中大量 502 Bad Gateway 错误。

原因：API 代理服务不稳定。

解决方案：

  1. 更换代理服务

    # 编辑配置文件
$cfgPath = Join-Path $HOME '.claude/settings.json'
$cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json

# 更新 BASE_URL
$cfg.env.ANTHROPIC_BASE_URL = "https://new-proxy.example.com/v1"

# 保存配置
$cfg | ConvertTo-Json -Depth 10 | Set-Content $cfgPath

  2. 或使用直连（如果有官方 API Key）

    $cfg.env.ANTHROPIC_BASE_URL = "https://api.anthropic.com"
$cfg.env.ANTHROPIC_AUTH_TOKEN = "sk-ant-your-api-key"
$cfg | ConvertTo-Json -Depth 10 | Set-Content $cfgPath

场景 3：Stream 中断#

症状：Stream completed without receiving message_start event

原因：网络不稳定或代理超时。

解决方案：

  1. 检查网络稳定性

    # 测试延迟
Test-Connection -ComputerName api.anthropic.com -Count 10

  2. 切换到更稳定的网络

    • 更换 VPN 节点
    • 使用有线网络代替 WiFi

  3. 增加超时时间（如果使用自定义代理）

会话现场保存#

当会话无法恢复时，保存现场以便在新会话中继续。

1. 导出会话记录#

# 查找当前项目的会话文件
$projectPath = (Get-Location).Path -replace '\\', '-' -replace ':', '--'
$sessionDir = Join-Path $HOME ".claude/projects/$projectPath"

# 复制到桌面
$backupDir = Join-Path ([Environment]::GetFolderPath('Desktop')) "claude-backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
New-Item -ItemType Directory -Path $backupDir -Force
Copy-Item "$sessionDir/*.jsonl" $backupDir -ErrorAction SilentlyContinue

2. 导出 Transcript#

# 查找最近的 transcript
$transcript = Get-ChildItem "$HOME/.claude/transcripts/ses_*.jsonl" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1

Copy-Item $transcript.FullName $backupDir

3. 导出 Debug 日志#

# 复制最新的 debug 日志
$debugLog = Get-ChildItem "$HOME/.claude/debug/*.txt" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1

Copy-Item $debugLog.FullName $backupDir

4. 保存代码状态#

# 导出 git 状态
git status > "$backupDir/git-status.txt"
git diff > "$backupDir/git-diff.txt"
git log --oneline -10 > "$backupDir/git-log.txt"

5. 生成交接文档#

@"
# Claude Code 会话恢复信息

**时间**: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')
**项目**: $(Split-Path -Leaf (Get-Location))
**Provider**: $($cfg.env.ANTHROPIC_BASE_URL)

## 问题描述

[在此描述遇到的问题]

## 已完成的工作

[列出已完成的任务]

## 待继续的工作

[列出需要继续的任务]

## 附件

- 会话记录: *.jsonl
- Transcript: ses_*.jsonl
- Debug 日志: *.txt
- Git 状态: git-*.txt

"@ | Out-File "$backupDir/README.md" -Encoding UTF8

6. 在新会话中恢复#

# 1. 启动新的 Claude Code 会话
claude

# 2. 提供上下文
# 将 README.md 和相关文件内容粘贴给 Claude
# 或使用文件路径让 Claude 读取

自动化脚本#

仓库提供了 3 个 PowerShell 脚本简化操作：

1. claude-provider-check.ps1#

快速检查 Provider 状态和连通性。

.\scripts\windows\claude-provider-check.ps1

输出示例：

✓ 配置文件: BASE_URL=https://api.example.com/v1
✓ 连通性测试: 成功
✓ 最新日志: 无错误

2. claude-provider-recover.ps1#

自动执行恢复流程（清理环境变量、重启会话）。

.\scripts\windows\claude-provider-recover.ps1

3. claude-provider-oneclick-direct.ps1#

一键切换到官方 API（需要 API Key）。

.\scripts\windows\claude-provider-oneclick-direct.ps1 -ApiKey "sk-ant-your-key"

详细说明见：claude-provider-switch-scripts.md

预防措施#

1. 配置多个备用 Provider#

在 settings.json 中配置备用 Provider：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://primary.example.com/v1",
    "ANTHROPIC_AUTH_TOKEN": "token1"
  },
  "backup_providers": [
    {
      "base_url": "https://backup1.example.com/v1",
      "auth_token": "token2"
    },
    {
      "base_url": "https://backup2.example.com/v1",
      "auth_token": "token3"
    }
  ]
}

2. 定期清理日志#

避免日志文件过大影响性能：

# 清理 7 天前的日志
Get-ChildItem "$HOME/.claude/debug/*.txt" |
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } |
  Remove-Item

3. 监控 Provider 健康状态#

定期检查 Provider 可用性：

# 添加到 Windows 任务计划，每小时执行一次
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Hours 1)
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File C:\path\to\claude-provider-check.ps1"
Register-ScheduledTask -TaskName "Claude Provider Health Check" -Trigger $trigger -Action $action

故障排查清单#

遇到问题时，按此清单逐项检查：

  • 检查配置文件中的 Provider 设置
  • 检查环境变量是否覆盖配置
  • 测试 Provider 连通性
  • 查看最新 debug 日志
  • 清理环境变量
  • 重启 Claude Code CLI
  • 发送探针测试
  • 如仍失败，保存现场并切换 Provider
  • 在新会话中恢复工作

相关文档#

最后更新: 2026-02-18

Backward 常见问题与踩坑记录 实用脚本集合 Forward