Claude Provider 切换脚本使用指南#
本文档对应三个可直接运行的脚本，全部放在 scripts/windows/。
脚本作用说明#
| 脚本 | 作用 | 典型使用时机 |
|---|---|---|
claude-provider-check.ps1 | 快速检测配置、环境变量覆盖、连通性、关键错误链 | 切换后 30 秒确认是否生效 |
claude-provider-recover.ps1 | 导出 .handoff 交接包，并修复当前终端覆盖变量 | 报错后需要保留现场并继续任务 |
claude-provider-oneclick-direct.ps1 | 一次执行 检测 → 恢复 → 复检 | 想要最少操作路径时 |
运行前准备#
Set-ExecutionPolicy -Scope Process Bypass
Set-Location <你的仓库根目录>1. 检测脚本#
./scripts/windows/claude-provider-check.ps1可选参数：
# 自定义日志尾行数
./scripts/windows/claude-provider-check.ps1 -Tail 220
# 自定义 settings.json 路径
./scripts/windows/claude-provider-check.ps1 -SettingsPath "$HOME/.claude/settings.json"输出重点：
settings.json中的BASE_URL / MODEL / TOKEN_SET- 当前终端
ENV_*是否覆盖 - 目标端口是否连通
- 最新 debug 与 cc-switch 关键日志
- 诊断建议（是否处于失败重试链）
2. 修复脚本#
./scripts/windows/claude-provider-recover.ps1 -ProjectRoot D:/Documents/IDE/202602常用参数：
# 保留当前终端环境变量（默认是清理）
./scripts/windows/claude-provider-recover.ps1 -ProjectRoot D:/Documents/IDE/202602 -KeepEnvOverride
# 不导出 git 状态
./scripts/windows/claude-provider-recover.ps1 -ProjectRoot D:/Documents/IDE/202602 -SkipGit执行结果 — 在 <ProjectRoot>/.handoff/<timestamp>/ 下生成交接包：
| 文件 | 说明 |
|---|---|
session_project.jsonl | 项目会话数据 |
session_transcript.jsonl | 全局会话记录 |
debug_latest.txt | 最新调试日志 |
error_chain.txt | 错误链摘要 |
git_status.txt | Git 状态快照 |
git_diff.patch | 未提交的代码变更 |
resume_prompt.txt | 会话恢复提示词模板 |
3. 一键脚本#
./scripts/windows/claude-provider-oneclick-direct.ps1 -ProjectRoot D:/Documents/IDE/202602可选参数：
./scripts/windows/claude-provider-oneclick-direct.ps1 -ProjectRoot D:/Documents/IDE/202602 -Tail 220
./scripts/windows/claude-provider-oneclick-direct.ps1 -ProjectRoot D:/Documents/IDE/202602 -SkipGit
./scripts/windows/claude-provider-oneclick-direct.ps1 -ProjectRoot D:/Documents/IDE/202602 -KeepEnvOverride该脚本执行顺序固定：
- 前置检测
- 交接导出与修复
- 修复后复检
推荐工作流#
- 报错出现时，先中断当前请求。
- 运行一键脚本。
- 关闭当前 Claude Code CLI 窗口并重新打开。
- 新会话先发短探针消息（例如
ping）。 - 探针通过后继续长任务。
常见问题#
Q1：脚本提示找不到会话文件#
先确认项目路径编码目录是否存在：
Get-ChildItem "$HOME/.claude/projects" | Select-Object Name | Format-Table -AutoSizeQ2：切换后仍报 Improperly formed request#
优先看两处：
error_chain.txt是否仍是同一条失败重试链。provider_config_snapshot.json与provider_env_snapshot.json是否一致。
Q3：为什么要先短探针再长任务#
短探针是为了确认"当前新进程 + 新供应商路由"确实生效，避免直接把长任务再次送进失败链。