在 Windows 上敲下 claude回车后看到 API 连接失败很多人第一反应是 PowerShell 版本不对。先停一下打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 创建一把 Key把 Claude Code 的 Base URL 填成 https://taotoken.net/api再回头折腾 PowerShell 7 的 pwsh.exe 规则。TaoToken 在这里做的是统一 API 通道给你 Key 和 Base URLGit Bash、PowerShell 7、Windows Terminal 各自怎么启动 Claude Code是另一层问题。原文里讲得很清楚只要装了 Git for WindowsClaude Code 在 Windows 上会锁定 Git BashPowerShell 7 和 5.1 大多处于闲置状态。所以连不上 API 时先查通道再查终端。下面按排障顺序拆开每一步都对应到具体文件或命令。1. Windows 上 Claude Code 报 API 失败先看报错在哪一层1.1 401、404、connection error 分别指向什么先把报错归类比盲目重装终端有用。401 一般表示 Key 没有被服务端认出来常见原因是复制时少了一段、前后带了空格、Key 已经失效或者把别的平台的 Key 填进了 ANTHROPIC_AUTH_TOKEN。404 多半是 Base URL 路径不对最常见写法错误是末尾多了 /v1或者把模型对话页的地址误当成接口地址填进了 ANTHROPIC_BASE_URL。connection error、timeout 则更杂可能来自本机网络、Git Bash 里的环境变量没继承也可能来自 CC Switch 里旧供应商配置把新值覆盖了。还有一类报错不会直接说 401 或 404而是提示找不到模型、模型不可用。这种时候要回到模型 ID 本身确认你在 Claude Code 或 CC Switch 里填的 ID 和模型广场当前列表一致。不要凭记忆写一个带日期后缀的 ID也不要拿别的工具的模型名硬套。先把错误按“认证问题、地址问题、模型问题、环境变量问题”四类分开后面每一步才有方向。1.2 为什么先别改 PowerShell 版本原文那段补充值得反复看用 CMD、PowerShell 5.1 还是 PowerShell 7 输入 claude 命令效果一样。claude 本质是可执行程序或脚本系统只通过 PATH 环境变量去找它。无论你在哪个壳里敲命令启动的都是同一个 claude.exe 进程所以启动界面和初始化过程不会因为壳不同而变化。装了 Git for Windows 后Claude Code 内部更倾向于使用 Git Bash 执行命令PowerShell 7 和 5.1 基本不会被它主动调用。也就是说API 连不上时反复换终端通常打不中根因。PowerShell 7 唯一可能被触发的情况是你在 Claude Code 里手动写了一个脚本强制指定用 PowerShell 解释器去运行比如执行 .ps1 文件。日常让 Claude Code 发 API 请求走的是 Git Bash 那套进程链。先把 Key 和 Base URL 对清楚再去动 PowerShell 7 的配置顺序反了会多花很多时间。1.3 准备材料Key 从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 创建打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 注册登录进控制台创建 API Key。创建时给 Key 起一个能认出来的名字比如 windows-claude-code方便后面在控制台看用量时对账。Key 复制出来后不要贴到聊天窗口、不要提交到 Git 仓库本文后续统一用 YOUR_API_KEY 代替。TaoToken 这层只负责提供 Key 和 Base URL不替你去改 Git Bash 的启动脚本也不负责替你修 Windows 注册表。同一个页面里可以顺手看模型广场。模型 ID 后面要填进 ~/.claude/settings.json 或 CC Switch 的自定义供应商不要在没确认的情况下写一个不存在的 ID。准备材料就三样一把 Key、一个 Base URL、一个当前可用的模型 ID。Base URL 填 https://taotoken.net/api末尾不要加 /v1。把这三样放在手边再进入下一段。2. PowerShell 7 的 pwsh.exe 规则Claude Code 为什么还是走 Git Bash2.1 Claude Code 在 Windows 的进程启动链在 Windows 上Claude Code 的启动链可以粗分成三层。第一层是你敲命令的终端可能是 CMD、PowerShell 5.1、PowerShell 7也可能是 Windows Terminal 里的某个 profile。第二层是系统按 PATH 找到 claude 可执行文件这一层不关心你用的是哪个壳。第三层是 Claude Code 内部执行命令时调用的解释器装了 Git for Windows 后它更倾向于走 Git Bash。第三层才会影响环境变量继承和脚本执行方式。很多人把 API 失败归因到第一层于是反复切换终端甚至重装 PowerShell 7。实际上第一层只决定你在哪里输入命令不决定 Claude Code 用哪套环境变量发请求。如果你在 PowerShell 7 里设置了 ANTHROPIC_BASE_URL但 Claude Code 实际从 Git Bash 那侧取环境设置可能根本没生效。排查时先确认请求从哪一层出去再决定改哪个文件。2.2 pwsh.exe -NoLogo -NoProfile -Command 的调用规则原文给 AI agent 的 Windows Shell 规则可以直接拿来用当前系统已经装好 PowerShell 7 时所有 PowerShell 命令走 pwsh.exe不用旧版 powershell.exe。执行形式统一写成下面这样-NoLogo 跳过启动横幅-NoProfile 不加载个人 profile-Command 后面跟具体命令。第一次执行前先确认版本拿不到 PowerShell 7 就停下不要自动退回 Windows PowerShell 5.1。pwsh.exe -NoLogo -NoProfile -Command $PSVersionTable.PSVersion pwsh.exe -NoLogo -NoProfile -Command (Get-Process -Id $PID).Path这两条命令一条看版本一条看当前进程的可执行文件路径。如果第一条返回 7.x第二条返回指向 pwsh.exe 的路径说明 PowerShell 7 本身没问题。但注意这一步只证明 PowerShell 7 可用不证明 Claude Code 会用它。Claude Code 连 API 失败时不要把这两条命令当成修复手段它们只是环境确认。2.3 什么时候才需要强制 PowerShell 解释器只有一种常见情况需要强制你在 Claude Code 里手动写了一个脚本明确要求用 PowerShell 解释器运行 .ps1 文件。比如让 Claude Code 生成一段 .ps1 脚本再让你本地执行这时才需要关心 pwsh.exe 的调用规则。日常的 API 请求、模型对话、代码解释不经过这条路径。所以排障时看到 API 报错先回到 Key 和 Base URL别把精力花在强制 PowerShell 上。如果确实要跑 .ps1建议在本地 PowerShell 7 窗口里自己执行把输出贴回对话。AI 编程工具默认不能直连你的生产机器去执行脚本也不能替你在本地跑编译或诊断命令。Claude Code 可以生成脚本、解释脚本、对照报错实际执行要在你本地完成。这条边界在排障时尤其重要别让工具直接去碰生产环境。3. 把 Base URL 填回 Claude Codesettings.json 与 CC Switch3.1 ~/.claude/settings.json 的 env 写法Claude Code 的配置文件通常位于用户目录下的 .claude/settings.json。Windows 上路径类似 C:\Users\你的用户名.claude\settings.json。如果文件不存在就新建注意是 JSON 格式不要写注释。下面这份配置把三个关键值放进 envANTHROPIC_BASE_URL 指向 TaoToken 的接口地址ANTHROPIC_AUTH_TOKEN 放你的 KeyANTHROPIC_MODEL 放模型 ID。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }ANTHROPIC_BASE_URL 填 https://taotoken.net/api末尾不要多写 /v1。ANTHROPIC_AUTH_TOKEN 用 YOUR_API_KEY 占位实际 Key 从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 创建。ANTHROPIC_MODEL 不要凭记忆写去模型广场看当前列表再填。保存后完全退出 Claude Code再重新启动让新环境变量生效。3.2 CC Switch 自定义供应商三件套如果你用 CC Switch 管理多个供应商思路是添加一个自定义供应商然后填三件套Base URL、Key、模型 ID。Base URL 填 https://taotoken.net/apiKey 填 YOUR_API_KEY模型 ID 填模型广场里当前可用的 ID。保存后把当前供应商切到这一个再启动 Claude Code。CC Switch 的好处是切换方便坏处是旧配置容易残留切换后要确认当前生效的是新供应商不是之前那个。常见问题是 CC Switch 里改了但 ~/.claude/settings.json 里还有旧值两边打架。排查时先看 CC Switch 当前选中的供应商再看 settings.json 的 env确认 ANTHROPIC_BASE_URL 没有被旧地址覆盖。如果两边都写了以实际启动时读取到的为准最稳的办法是只保留一处配置减少变量。3.3 模型 ID 不要凭记忆写模型 ID 是排障里最容易被忽略的一项。你把 Base URL 和 Key 都填对了但模型 ID 写错接口可能返回 404 或模型不可用。正确做法是打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 模型广场看当时列表里可用的 ID复制粘贴到配置里。不要写 gpt-5 这类未经确认的 ID也不要随手加日期后缀。模型广场显示什么就填什么。如果模型广场里同一个模型有多个版本选一个你实际要用的。填完后在 Claude Code 里发一条最简单的测试消息比如“用一句话说明当前配置的模型 ID”看返回是否正常。如果返回模型不可用先回到模型广场核对 ID再检查 Base URL 有没有多写路径。4. 回到 PowerShell 7 或 Windows Terminal 验证 API 是否通了4.1 用 $PSVersionTable 确认当前 shell配置保存后打开 PowerShell 7 或 Windows Terminal先确认当前解释器。运行下面这条命令看输出是不是 7.x。如果不是说明你打开的是 Windows PowerShell 5.1换 pwsh.exe 启动 PowerShell 7 再继续。$PSVersionTable.PSVersion (Get-Process -Id $PID).Path这两条不解决 API 问题只是确认你在哪个壳里操作。后面检查环境变量时不同壳读到的值可能不同。如果你在 PowerShell 7 里看到 ANTHROPIC_BASE_URL 正确但 Claude Code 走 Git Bash 时读不到那就要去 Git Bash 里再查一次。不要把“PowerShell 7 里显示正确”直接当成“Claude Code 一定读到”。4.2 启动 Claude Code 发一条测试消息在 PowerShell 7 或 Windows Terminal 里先看环境变量。下面两条分别输出 Base URL 和 Key 的当前值注意不要把 Key 截图发出去。$env:ANTHROPIC_BASE_URL $env:ANTHROPIC_AUTH_TOKEN确认 ANTHROPIC_BASE_URL 显示为 https://taotoken.net/api末尾没有 /v1。然后启动 claude发一条测试消息。如果之前报 401测试通过说明 Key 已生效如果之前报 404测试通过说明 Base URL 路径对了。如果仍然报错先不要换终端回到第 6 节按顺序排查。若你装了 TaoToken 的 CLI也可以用下面这条快速发一条测试-u 后面填接口地址不要加 /v1。npm install -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID4.3 去控制台看这次调用是否记上账测试消息发出后回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 控制台看这次调用有没有记上用量。如果控制台里有记录说明请求已经走到通道Claude Code 侧的 Key 和 Base URL 基本正确。如果控制台里没有记录说明请求根本没发出去或者发到了旧地址继续检查环境变量和 CC Switch 当前供应商。控制台还能帮你区分“请求失败”和“请求成功但本地报错”。有时 Claude Code 提示连接失败但控制台已经记了一次调用那问题可能在返回解析或本地显示层。反过来控制台完全没记录就回到 Base URL 和 Key 这两项。用控制台对账比反复猜终端版本有效得多。5. Windows Terminal 右键与 coreutils减少命令层的干扰5.1 Windows Terminal 安装后补右键Windows Terminal 装完后建议重启一次资源管理器有些系统会自动添加右键菜单有些不会。没有的话可以手动写一个注册表文件把“终端”加到文件夹背景和文件夹图标的右键菜单。下面是一份简化后的 .reg 内容保存时编码选 ANSI/GBK避免中文乱码。Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\Directory\Background\shell\OpenTerminal] 终端 Iconcmd.exe,0 [HKEY_CLASSES_ROOT\Directory\Background\shell\OpenTerminal\command] wt.exe -d . [HKEY_CLASSES_ROOT\Directory\shell\OpenTerminal] 终端 Iconcmd.exe,0 [HKEY_CLASSES_ROOT\Directory\shell\OpenTerminal\command] wt.exe -d \%V\双击导入后右键菜单里会出现“终端”。想删掉时打开注册表编辑器分别定位到 HKEY_CLASSES_ROOT\Directory\Background\shell\OpenTerminal 和 HKEY_CLASSES_ROOT\Directory\shell\OpenTerminal删除这两个项右键菜单立即消失不需要重启电脑。这一段属于终端便利性配置和 API 排障没有直接关系配不配都不影响 Key 和 Base URL 是否生效。5.2 coreutils for Windows 解决 ls/grep 差异Git Bash 自带一套 Linux 风格命令但 PowerShell 7 里没有 ls -la 这种用法grep 也不是默认命令。Coreutils for Windows 把 ls、cp、mv、rm、cat、grep、find、wc、sort、echo、tee 这些常用命令做成 Windows 可执行文件参数和行为尽量贴近 Linux。AI 给你的命令行指令里出现 ls -la 或 grep -r error . 时Windows 上可以直接跑不用每次翻译成 PowerShell 的 Get-ChildItem。这一步减少的是“命令语言差异”不是 API 通道问题。但如果你经常在 Claude Code 和本地终端之间复制命令装上 coreutils 会少很多来回改命令的时间。注意它只补命令不改变 Claude Code 实际使用 Git Bash 还是 PowerShell 的进程链。API 连不上时仍然先查 Key 和 Base URL。5.3 powershell-safe-invocation 对 agent 调用 PowerShell 的约束原文提到一个 skill专门针对 Windows 上 AI agent 调用 PowerShell 时的各种坑做规约。它的价值在于把“用 pwsh.exe、不退回 5.1、执行前先确认版本、命令用 -NoLogo -NoProfile -Command”这些规则固定下来减少 agent 在 Windows 上乱换解释器。注意这个 skill 只做调用规约不替你连接生产库也不替你执行诊断脚本。Claude Code 可以生成或解释 PowerShell 命令实际执行要在你本地窗口完成再把输出贴回对话。如果你把这段规则写进项目内的 agent 说明记得不要和 API 配置混在一起。PowerShell 调用规则解决的是本地命令怎么跑API 配置解决的是请求发到哪里。两者混在一起排查容易把 401 误判成 PowerShell 版本问题。6. 仍然连不上时的排查顺序6.1 检查 Base URL 是否多写 /v1这是出现频率最高的错误。正确写法是 https://taotoken.net/api末尾不要加 /v1。错误写法是 https://taotoken.net/api/v1或者把模型对话页的地址填进 ANTHROPIC_BASE_URL。打开 ~/.claude/settings.json 和 CC Switch 的自定义供应商两处都看一遍。改完保存完全退出 Claude Code 再启动。6.2 检查环境变量是否被 Git Bash 继承Claude Code 在 Windows 上更倾向 Git Bash。你在 PowerShell 7 里设置的 $env:ANTHROPIC_BASE_URL不一定自动出现在 Git Bash 的环境里。打开 Git Bash运行下面两条看值是否和 settings.json 一致。如果不一致就在 Git Bash 的启动文件里补上或者确认 settings.json 里的 env 是否被 Claude Code 正确读取。echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN6.3 检查 Key 是否复制完整、是否带空格Key 复制时最怕多一个空格或少一段。把 YOUR_API_KEY 替换成实际 Key 后检查前后有没有换行、空格、引号。在 settings.json 里 Key 是字符串不要写错引号。在 CC Switch 里粘贴后也看一眼输入框末尾有没有多余字符。如果 Key 本身已经失效去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_win_pwsh7 重新创建一把再替换。6.4 检查 CC Switch 是否覆盖了 settings.jsonCC Switch 切换供应商时可能把旧配置写回 settings.json或者启动时注入一套环境变量覆盖文件里的值。排查时先把 CC Switch 切到你刚建的自定义供应商再看 settings.json 的 env 是否还是 https://taotoken.net/api。如果两边不一致保留一处可信配置避免 CC Switch 和手动配置互相覆盖。确认后再启动 Claude Code看报错是否消失。7. 配好之后下一步去哪里看用量和文档7.1 模型对话里先发一条测试配置保存后先在 TaoToken 模型对话 里用同一把 Key 发一条测试消息确认模型 ID 和 Base URL 没填错。模型对话页适合做最小验证不经过 Claude Code 的终端链路直接确认 Key 能用、模型能返回。测试通过后再回到 PowerShell 7 或 Windows Terminal 启动 Claude Code这样能把通道问题和终端问题分开。7.2 长期写代码看 Coding Plan如果你准备长期用 Claude Code 写代码可以打开 Coding Plan 看套餐是否够用。先确认日常调用量再决定是否需要调整。不要一次性把配置改得很复杂保持 Base URL 和 Key 单一来源后面换机器或重装系统时也容易迁移。7.3 创建 Key 与 Claude Code 接入文档需要新 Key 时去 控制台 API Keys 创建旧 Key 及时停用。环境变量名和 settings.json 的字段对照可以看 Claude Code 接入文档。文档里把 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 对应的位置写清楚了照着核对一遍比在终端里反复试更快。