安装与启动问题
装不上、打不开、更新完出问题，都在这里。
213 个主题页，汇总自 731 个真实 issue口径说明
终端与环境变量136
我windows11打开cc，为什么只有进程没有界面 cc-switchWindows 11 可在 exe 属性中尝试兼容 Windows 7；无效则改用 cc-switch-cli 绕过 Tauri 2 GUI 白屏。'claude' 不是内部或外部命令在 CC Switch 设置中正确配置 claude.exe 的完整路径，或确保 claude 在系统 PATH 中。cc-switch 本地代理常见问题：502 Bad Gateway、超时、无法删除配置代理相关问题多由官方供应商不被支持、配置未生效或 UI 状态不同步引起；需按场景检查代理模式、供应商类型与接管状态。'claude' 不是内部或外部命令，也不是可运行的程序升级至 v3.16.2+ 以修复 WSL/Windows 路径检测问题，或手动配置安装目录覆盖。The `content[].thinking` in the thinking该问题部分变体仍未修复：可将 CC Switch 升级到已包含 thinking 历史归一化修复的版本；Codex 经 DeepSeek 转发时需使用包含对应转换修复的版本。上游 Chat Completions 流式响应异常，Claude Code确认该问题是否由本地代理转换或上游端点导致；按已验证的对应场景调整端点或关闭本地代理。切换供应商会重置claude settings.json - Claude Code切换前先在“通用配置”中从当前供应商提取配置，并在新供应商中勾选“写入通用配置”。MCP stdio 连接失败，cmd /c 包装导致 Claude Code 无法连接Windows 上编辑 MCP 配置后若出现 cmd /c 包装并导致连接失败，请检查生成的 command 和 args，并升级到已修复该问题的版本。EGL_BAD_PARAMETER：CC Switch Linux 白屏在受影响的 Linux AppImage 环境中，先预加载宿主机的 libwayland-client；若仍白屏，可改用使用系统组件的 .deb 包。Not logged in · Run /login - Claude Code开启 CC Switch 本地代理接管，检查 API 地址是否包含 /v1，或通过 CC Switch 启动终端以注入环境变量。Claude Code 报错 Auth conflict删除 ~/.claude.json 中的 primaryApiKey，或在配置中加入 "auth_mode": "bearer_only" 以解决认证冲突；如遇配置被覆盖，请从 default 供应商恢复或使用通用配置功能。env: node: No such file or directory从 Dock/Finder 启动 CC Switch 时 GUI PATH 缺少 Homebrew 目录，升级到 v3.18.0+ 已修复。Unexpected status 502 Bad Gateway：Codex在 `~/.codex/.env` 设置 `NO_PROXY=127.0.0.1,localhost,::1`，让 Codex 直连 CC Switch 本地端口。原子替换失败 不支持该请求 os error 50 cc-switch升级 cc-switch 至 v3.20.0 或更高版本，以修复 WSL 路径下配置文件原子替换失败的回归问题。供应商 API Key 被覆盖：Codex 重启或切换后升级到 cc-switch v4.0.0 或更高版本；该版本重写了切换逻辑，避免供应商密钥互相覆盖并恢复官方登录态。model does not support thinking在 cc-switch 高级设置里关掉整流器（Proxy Rectifier），或升到修复版本；Qwen 工具调用死循环、空 thinking block 等变体仍未解决。auto mode cannot determine the safety先升级 CC Switch；若仍报错，再按上游能力检查思考参数、模型映射、stop 支持及省略 stream 时的响应格式。卡巴斯基病毒检测将ccswitch删除 — Gemini CLI在 Windows 安全软件中将 CC Switch 加入安全许可后，再使用 Gemini CLI。Codex/OpenCode 显示未安装将 npm prefix 或 fnm 别名目录添加到用户 PATH 环境变量后重启 CC Switch。either event handler is re-entrantWindows 上出现该崩溃时，企业安全软件冲突场景可尝试设置 WebView2 参数；原帖未提供通用已验证修复。提示INVALID_API_KEY，Codex 切换供应商后认证不匹配升级至 v3.20.1 或更高版本；维护者称第三方切换不再写入 auth.json，避免供应商密钥与认证配置错配。重启终端，执行gemini，提示需要输入api-key - Gemini CLI更新 cc-switch 修复保存清空 bug；若仍无效则是 Gemini CLI 官方读取 bug，需将环境变量写入 bash_profile。没开梯子中转站的链接测速失败目前没有已确认的统一修复；请提供可复现配置、请求目标和启动日志以区分网络、转发与统计问题。配置WSL路径但技能读不到 cc-switch在 Windows 版 cc-switch 中无法直接读取或安装 WSL 的 ~/.agents/skills，需直接在 WSL 内安装并运行 Linux 版 cc-switch。API Error: 404 Claude Code 路径拼接或未注册路由检查 API 地址是否被错误拼接，或升级 cc-switch 以修复 OpenAI 兼容模式及本地路由缺失导致的 404 问题。未安装 / not installed or not executable升级 CC Switch 至 v3.20.0+ 以修复自定义 npm prefix 及 macOS 检测失败，Windows 误报多处安装需升级至 v3.16.5+。每次点击都会先弹出系统文件夹选择器 cc-switch修改 src/App.tsx 移除 handleOpenTerminal 中的 pickDirectory() 调用，即可解决点击打开终端时强制弹出文件夹选择器的问题。zsh:1: command not found: claude升级 cc-switch 至 v3.16.4 或更高版本以修复终端启动时未加载 PATH 的问题，或临时切换至系统默认终端。切换渠道后auth.json没变Codex 认证机制重构导致切换无效，需按官方认证保留指南检查 auth.json 路径与配置。env: node: No such file or directory将 cc-switch 升级至 v3.18.0 或更高版本即可自动修复 GUI 环境下 PATH 缺失导致的环境变量解析失败问题。Invalid type for 'messages'升级 cc-switch 至最新版修复转换 Bug，或降级 Codex CLI 至 0.80.0 并改用 wire_api="chat" 绕过。tools.function.parameters is not a valid升级到包含 #6863 修复的后续版本；它会将带同级关键字的 `$ref` 转为 Moonshot 可接受的 `allOf`。无法导入供应商，无法进行会话管理 cc-switch升级 cc-switch 以支持 jsonc 配置；WSL2 环境需定时克隆数据库至 Windows 本地路径以绕过 SQLite 锁定。not installed or not executable - OpenCode升级 CC Switch 至 v3.11.0+ 修复路径检测，或手动将 opencode 软链接至 ~/.local/bin。skills同步到了未选择的应用上 OpenCode升级 cc-switch 到 v3.12.3 修复隐式推断 bug，并在 OpenCode 设置中关闭默认读取 .claude 目录下 skills 的选项。missing field `call_id`：Codex 自动化 HTTP 400原帖尚无已发布的可验证修复；需在代理转发时规范化无 `call_id` 的孤立输出，并保留跨任务消息内容。Unkonw coding plan provider cc-switch 火山引擎升级 cc-switch 至 v3.20.0 及以上版本，并重建或修改火山引擎 Agent Plan 供应商的 Base URL。Failed to authenticate退出 Claude Desktop 中残留的官方账号登录态并重启应用；若仍报错，按 issue 中确认有效的切换默认供应商再切回步骤操作。Select Model 菜单仍然显示切换前模型列表 - Codex关闭现有 Codex 会话后运行 `codex app-server daemon restart`；升级 CC Switch 至 v4.0.7 以上可获得旧目录检测与重启提示。codex中只有258k上下文 - Codexcc-switch 将 minimax 模型映射为 gpt-5.5 后，会触发 Codex 和 Claude Code 的硬编码上下文限制，导致 1M 上下文失效。codex从来不显示ds的模型 - CodexCodex 桌面端需官方登录态才显示第三方模型，请在 cc-switch 开启「切换第三方时保留官方登录」并重启。cc-switch overrides DNS cache and resolves禁用受影响应用的代理接管功能以恢复正常网络连接，cc-switch 不会修改系统 DNS 记录。到claude 里面提示 401 - Claude Code开启 cc-switch 的本地代理功能以转换 API 格式，并确保 `ANTHROPIC_BASE_URL` 环境变量正确注入到 Claude Code 进程中。Error running remote compact task 报错 - Codex升级 cc-switch 至 v3.12.0 或更高版本，该版本在本地代理中新增了对 Codex `/responses/compact` 路由的转发支持，可解决 404 或 502 报错。Function call is missing使用社区补丁 cc-switch-gemini-fixer 或在历史消息中注入 skip_thought_signature_validator 以绕过 Gemini 工具调用的签名验证。`GLIBC_2.35' not foundv3.10.1–v3.16.1 未有已确认兼容版本；按维护者建议试用 v4，仍报错则附版本和复现步骤重新提交。Gtk-CRITICAL: gtk_widget_get_scale_factor 失败在 Linux 或 WSL2 中运行 cc-switch 遇到 GTK 断言失败时，请修改 settings.json 关闭静默启动，或清理残留配置重装。Not found (404)升级 cc-switch 至 v3.16.3 以修复智谱 GLM 等 Base URL 被错误拼接 /v1/ 导致的 404 报错，并开启媒体回退防止图片请求触发全局熔断。InputValidationError长工具参数经流式 SSE 截断时，可暂时关闭 Tool Search、最大强度思考和 1M 声明后重启并重试。Missing API key · Run /login - Claude Code清除冲突的 ANTHROPIC_BASE_URL 环境变量，或升级 CC Switch 使用内置的环境变量冲突检测功能。protocol handler not registered在 Linux 的 CC Switch.desktop 文件中将 Exec 修改为 cc-switch %U，解决 Chromium 浏览器无法识别导入协议的问题；WSL 同步需检查管理员权限。<tool_use_error>InputValidationError 报错cc-switch 转换层存在 SSE 解析 bug 导致 tool call 丢失，目前建议直连 API 或更换官方节点。Error 2503：Windows 11 上 CC Switch MSI 安装失败以管理员身份打开命令提示符，运行 msiexec /i 并指定 MSI 文件路径。本地有claude cli但是关于设置里显示未安装升级 CC Switch 至 v3.16.5 或更高版本，以修复 Windows 下 npm 全局包多入口导致的误报冲突及路径乱码问题。Symlink target not foundAppImage 安装失败，需手动修复 .DirIcon 符号链接为相对路径。ccstatusline 显示的模型名不正确 - Claude Code在 ccstatusline 中配置 Custom Command 脚本，读取 cc-switch 数据库中的环境变量以正确显示实际模型。打开终端未使用完整配置通过「通用配置」面板提取并勾选写入，避免全量覆盖导致插件等共享配置丢失。session isn't eligible使用非 Anthropic 上游或格式转换时，在 provider 的 env 中设置 CLAUDE_CODE_AUTO_MODE_SERVER=0，以关闭提示并继续使用本地分类器。为什么单独在终端使用claude命令使用的模型与在cc-switch中使用的模型不一样呢把真实要用的 MiniMax 设为主模型，并在 cc-switch 打开的终端运行 claude；未开启接管时终端里显示的映射名不代表请求被替换。No such file or directory (os error 2)将 config.toml 中的 model_catalog_json 绝对路径修改为相对路径 cc-switch-model-catalog.json，或升级 cc-switch。会话过期了 Codex OAuth 会话已过期升级到 cc-switch v4.0.0 或更高版本，避免旧的 OAuth 数据覆盖新登录凭据。"Expecting property name enclosed in double升级 CC Switch 至 v3.16.4 或更高版本，以修复大请求体未正确解压导致的 JSON 解析错误。Function call is missing a thought_signature先升级到 CC Switch 4.0 最新版本重试；若仍报错，请携带版本、系统、完整复现步骤和日志重新提交。Gemini CLI 读取项目 .env 导致 cc-switch 失效在 PowerShell 中封装 gemini 命令，手动加载 ~/.gemini/.env 环境变量。does not run on macOS versions other than先执行 `brew update` 后重试安装；若 cask 仍锁定 Monterey，需将 macOS 条件改为 `>= :monterey`。invalid_request_error Kimi For Coding在 cc-switch 的 Kimi 配置中设置 ENABLE_TOOL_SEARCH=false。KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: 权限不够在 Linux 运行 cc-switch 遇 DRM 权限报错白屏时，可通过设置环境变量禁用 WebKit 硬件加速、指定 NVIDIA 渲染或改用 CLI 版解决。No endpoints available that support升级 Claude Code 至 v2.1.92 及以上版本，并更新 cc-switch 以修复 OpenRouter 参数传递错误，或尝试关闭本地代理。not found(404) 添加Claude code桌面版模型api失败升级至 v3.16.3+ 以修复连通性检测误报，或忽略 404 直接测试实际调用。Windows Explorer opens to the "Documents"Windows 上 Open Terminal 会打开 Documents 而非终端；原帖仅提供了疑似原因和建议修复，尚无已验证解法。打开了选择文件夹 Claude Code这是用于选择 Claude Code 终端工作目录的设计；选择对应项目文件夹后再打开 CLI。thinking enabled but reasoning_content关闭 Claude Code 的 Thinking 模式，或升级 cc-switch 解决 Kimi/Moonshot 工具调用报错。Unsupported parameter: 'max_tokens'报错来自路由转发时携带了模型不支持的 max_tokens 参数；issue 中未给出已确认的修复步骤，请核对模型参数支持或等待 cc-switch 修复。'/d' 不是内部或外部命令：Claude Code在 Windows 上先避免选择中文工作目录；该问题尚未确认已修复，启动后请核对实际目录。API Error: Connection refused在 Windows 的 WSL2 NAT 模式中，用 socat 将 WSL 的 127.0.0.1:15721 转发到宿主机 CC Switch 路由端口。上次自动同步失败：Fetch is aborted（cc-switch 代理环境）cc-switch 内部请求（会话刷新、定价同步）不走供应商 env 代理，需在软件里配置出站代理或系统代理；WebView 的 models.dev 同步只认系统代理，修复待发布。ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY执行 `claude daemon stop --any` 停止残留的 Claude 后台进程，再重新启动并恢复会话。输出ANTHROPIC_BASE_URL的值为什么是空的？ Claude Code这是正常现象：CC Switch 不会向 shell 注入变量，请直接查看 `~/.claude/settings.json` 中的当前配置。<thinking> 标签作为正文输出 Claude Code将 provider 的 apiFormat 从 openai_chat 改为 anthropic（若上游支持），可绕过内联 <thinking> 泄露。正文被丢弃：Anthropic 协议转换 Claude Code升级到 v3.20.3 或包含该修复的 v4 版本，转换器会忽略空的尾随 reasoning_content。设置的代理没有生效, 输入问题后,一致reconnect; Codexcc-switch 的“配置单独代理”功能已删除；请在 PowerShell 用 $env:http_proxy 设置代理后再运行 Codex。模型显示错误 Claude Code为 ccstatusline 配置 Custom Command，从当前 cc-switch 供应商配置读取模型名。“ANTHROPIC_API_KEY or another auth source将 CC Switch 从 3.16.4 升级到经过相关功能重构的 4.0 或更新版本后重新测试。把分类器请求整体路由到另一个供应商 Claude Code这是尚未解决的功能请求；原帖未提供可验证的用户侧配置解法。The auto mode classifier is temporarily先关闭 CC Switch 的 Anthropic Base URL 代理并重启 Claude Code；issue 中有用户称更新 CLIProxyAPI 后问题得到解决。模型就自动切换到了haiku上 cc-switch这是 Claude Code 自带特性：haiku 用于读文件，cc-switch 只管理环境变量，不会改变模型选择。/branch 会话在 Session Manager 中难以找回父会话可尝试原帖提出的临时绕过：用 claude --resume 或 claude -r <sessionId> 恢复会话；Session Manager 原帖尚未提供可验证的解法。配置本地代理后，claude cli 中调用工具会断流 Claude Code原帖尚未提供可验证解法；有用户反馈改用 claude-code-router 作为替代方案。Bash(...) Waiting... Claude Code降级 Claude Code 至 v2.1.104 或 v2.0.64（需管理员权限），或切换至阿里云百炼等兼容 provider，因 Nvidia 模型无法正确解析 tool use 格式。切换供应商后 Claude Code 不再热加载 settings.json 的切换后重启 Claude Code 使其重新读取 settings.json；原帖还确认 clash-for-ai 可避开此限制。开着的会话继续使用第三方的 ANTHROPIC_BASE_URL在官方供应商配置的 env 中将遗留的 ANTHROPIC_* 键设为空串，然后切回官方供应商。无法应用反向代理到 Claude Code VS Code 插件开启“应用到Claude Code插件”；若仍使用旧供应商，检查并删除 VS Code settings.json 中此前配置的智谱中转设置。Claude 供应商不存在，无法接管 Live 配置：Claude Code升级到 v4.0 或更新版本；路由逻辑已重写，Claude Desktop 使用模型映射模式，无需手动修改 settings.json。请求转发失败: 上游请求失败: client error (Connect)临时绕过 CC Switch 本地代理可恢复请求；也可更换网络排查 DeepSeek 是否被当前网络屏蔽，但尚无已确认的最终修复。窗口尺寸只要发生变化就退出 Claude Code更新相关上游组件后可恢复窗口缩放；报告者已确认上游更新解决该问题。格式转换错误: No choices in response - CC SwitchClinePass 把响应套了一层 data 信封导致解析失败，可升级含修复的 CC Switch 版本，或临时用本地代理解包 response.data 再转发。切换后打开 codex 继续用旧账号。— Codex切换 OAuth 账号后彻底重启 Codex 后台服务；CLI 可执行 `codex app-server daemon stop` 后重新打开 Codex。auth.json污染 Codex在 Codex 3.16.0 中，官方登录态留在 auth.json，BYOK 的 provider、endpoint 和 token 请检查 config.toml。missing field `call_id`DeepSeek Responses 拒绝了 Codex 委派任务注入的缺少 `call_id` 的条目；issue 未确认可用的用户侧修复。missing field `call_id`为代理启用请求时清理孤立的心跳输出条目；该 issue 未确认 CC Switch 已有修复。No API key configured for provider: custom将 Codex CLI 和 CC Switch 升级到最新版；CC Switch 支持读取 config.toml 的 Codex CLI 版本。禁用的 MCP 会再次生效 Codex目前该 issue 未提供已确认的修复方法；若问题仍存在，请重新打开 issue 继续跟进。工具调用必假死：Codex 的 function_call 丢失 call_id评论者确认：流式累积时仅用非空 id/name 更新状态可恢复工具调用；原帖另提供绕过 CC Switch Responses 翻译、直连官方 OpenAI 的临时方案。不应该有如此巨量的unknown模型用量 — Codex升级到 CC Switch 4.0.13 后重新测试；若仍出现大量 unknown 请求，请携带版本、系统、复现步骤和相关日志重开 issue。Copilot订阅模型映射不生效，仍调用Claude模型这是 cc-switch v3.14.1 的已知 bug，升级到 v3.15.0 即可修复 Copilot 订阅的模型映射不生效问题。点击“添加”并无什么反馈，Codex添加时先在 `auth.json (JSON)` 填入非空 `OPENAI_API_KEY`，添加后可改回 `{}`；维护者表示将移除该校验。会话有概率停止响应（JSONL 不再写入）— Claude Code将 CC Switch 更新到最新 4.0 版本后重试；若仍卡死，可暂时绕过 CC Switch，并提交完整复现信息。“Bash 工具一直在被搜索但无法正常加载调用” - Claude Code绕过 CC Switch，直接在 Claude Code 中配置 GLM；或升级至 CC Switch 4.0.13 后重新测试。如何调整 GPT 的 reasoning effort？Claude Code原帖未提供可验证的调整方法；请关注该 issue 的后续讨论。实际检测不到：Hermes原帖尚未提供可验证的解法；维护者将该报告归并到 #4162 跟踪。“关于”页面卡死：Linux cc-switch 工具检测升级到 cc-switch 4.0；维护者表示该版本对配置切换和界面进行了大改，许多相关问题已不存在。无法设定终端进程组：ioctl 操作原帖尚未提供可验证的解法；请跟进 Issue #5635 获取后续处理。不同 CLI 下 MCP 配置不一致，Codex原帖报告同一 MCP 服务在 Codex 与 Claude 的配置格式和参数不同，尚未提供可验证的解法。failed to parse function arguments暂无可验证的修复；检查 Codex 会话日志确认 arguments JSON 是否被上游模型截断，并向上游 provider 反馈或更换 provider。Effort is silently dropped for all原帖仅提出将 muse-spark 加入白名单的补丁，尚未提供可验证的解法。experimental_bearer_token = "PROXY_MANAGED"升级到 CC-Switch v3.16.2 或更高版本；若仍出现问题，重新执行 Codex OAuth 登录并按维护者要求重新打开报告。[DISCUSS] 支持 pi coding agent这是功能请求，维护者已将其合并至统一追踪 issue #1855，原帖未提供可验证的解法。模型无反应，Claude Code删除所有 provider 后，为同一 provider 设置相同模型，即可恢复 Claude Code 对话。PROXY_MANAGED 导致 401 Unauthorized升级到 4.0 或最新版本；路由转发应使用供应商配置中的真实 API key。unsupported call: — Codex 工具调用失败目前没有已确认修复；CC Switch 需在流式事件中保留 function_call 的 name 和 call_id。No tool output found for tool call此问题尚无已确认的官方修复；原帖提供了重排工具调用与输出的本地兼容层绕行方案，官方进展需关注主 issue。无法正常启动，窗口无响应，被系统要求force quit将 CC Switch 更新到经过相关功能重构的 4.0 或最新版本后重试；若仍复现，提交完整版本、步骤、日志和截图。环境变量没有写进去：VS Code Claude 插件检查 VS Code 的 settings.json 是否已配置 Claude 环境变量；若有，先注释掉相关配置再重新打开 Claude。vscode 中claude code插件无法立刻切换配置 - Claude CodeVS Code 的 Claude Code 插件无法代理或热切换；在终端 CLI 中启动 cc 才会立即生效。400 模型提供方错误 Claude Code 插件将当前 provider 所需的环境变量写入 VS Code 的 claudeCode.environmentVariables 配置，让插件能读取它们。切换标签时白色闪烁，CC Switch该问题被认为与 WebView2 153.x 更新有关；升级 CC Switch v4.0 后若仍闪烁，请补充版本和复现步骤。出现错误 2147942402 (0x80070002) — Claude Code在 Windows 上升级至 CC Switch v3.16.1 或更新版本后复验；临时可将首选终端改为 PowerShell。检测本地codex时候会无限开检测窗口：cc-switchWindows 下检测本地 CLI 时出现窗口和进程持续堆积，原帖尚未提供可验证的解法；设置超时仅是用户提出的修复诉求。cmd.exe console window flashes先更新到 4.0 或最新版本重试；若仍闪窗，请提交版本、系统、完整复现步骤及日志或截图。尺寸溢出至 65535×53251，CC Switch 主窗口不可见完全退出 CC Switch，删除窗口状态文件后重新启动，以清除持久化的异常窗口尺寸。配置未生效，Claude Code WSL 路由配置未更新在 CC Switch 设置-高级中将配置文件目录改为 WSL 内的文件路径；该问题在 4.0 发布时关闭，升级后仍有问题请提供复现步骤。打开pi后显示没有模型 - pi将 CC Switch 的 Pi 配置目录指向 WSL 中的 `~/.pi/agent` 路径后，报告者确认模型恢复显示。进入Claude需要验证 Claude Code在 Windows 的 WSL 中，需将跳过 Claude Code 初次确认的规则写入对应 JSON；该问题已获维护者确认修复。无法启动cc-switch，cc-switch --version也没有输出维护者建议先重装；若仍无法启动可尝试 CLI 版，原帖未确认恢复。检测不到对话历史and使用统计啊？Claude Code将 Claude 配置目录指向 WSL 路径；使用统计则让 WSL 中的 Claude Code 经 cc-switch gateway 路由。3.15.0 在 WSLg 下启动会卡死：CC Switch回退到 3.14.1 可恢复正常启动；也可在最新版复现并提交 WSL、图形环境和启动输出信息。
更新与升级52
cc-switch 配置用量查询失败 / 用量查询一直显示失败 / undefined升级到 v3.16.2+；仍失败时按 NewAPI 格式填写 base_url 和访问令牌，或关闭自动刷新/用量查询。cc-switch 检查更新失败 / 更新安装失败更新失败多因权限不足或 GitHub 网络异常；请用管理员/绿色版安装，或到 GitHub Releases 手动下载。macOS cc-switch检测版本错误/卡死修改.zshrc中fastfetch调用，添加[[ -t 1 ]]限制非交互式输出。settings.json 被重置 - Claude Code将插件、hooks 等共享字段写入「通用配置」并在切换时勾选写入；接管模式异常时先关闭后切换供应商再开启。开启 CC Switch 代理后无法使用或请求被系统代理拦截在 CC Switch 设置中配置全局出站代理指向你的代理软件地址，或在系统代理软件中配置分流避免拦截本地请求，然后重启 CC Switch。"Failed to upload "image.png"" 截图上传失败这不是 cc-switch 的报错，而是 GitHub 截图没传上去留下的占位符；重新上传截图或直接粘贴文字版报错，否则维护者看不到任何信息。Codex接入第三方模型，对话经常自动中断根因是 cc-switch 把 Codex 的 Responses API 工具调用转成上游 Chat Completions 时丢失了 function call 的 name/call_id；可让 DeepSeek 直连 Codex 绕过代理，或升级 cc-switch 后复测。Unexpected status 502 Bad Gateway：Codex在 `~/.codex/.env` 设置 `NO_PROXY=127.0.0.1,localhost,::1`，让 Codex 直连 CC Switch 本地端口。供应商 API Key 被覆盖：Codex 重启或切换后升级到 cc-switch v4.0.0 或更高版本；该版本重写了切换逻辑，避免供应商密钥互相覆盖并恢复官方登录态。结果显示用了16亿，用量统计飙升 Codex升级 cc-switch 至 v3.18.0 修复子代理历史重放双计 bug，系统会自动重建被污染的 Codex 用量数据。"Not logged in · Please run /login" Claude升级 cc-switch 至 v3.19.2+，或手动将 settings.json 中的 ANTHROPIC_API_KEY 改为 ANTHROPIC_AUTH_TOKEN 以跳过审批弹窗。cc-switch 升级失败、卡死或花屏问题排查升级 cc-switch 到最新版本（v3.16.3+ 修复了更新卡死问题，v3.20.0+ 支持 winget 安装的 Claude Code，v4.0 重构了升级流程）；winget 安装的 Claude Code 需用 winget 命令手动升级。升级 cc-switch 后常见问题汇总升级到 v4.0 或更高版本，多数旧版同步、切换和显示问题已修复。Codex Desktop 项目列表消失或推理档位减少 - CC Switch 配置问题多数相关 issue 仍未解决；升级 CC Switch 或切换供应商后，Codex 的 model_provider 字段变化导致项目历史消失；升级至 v3.19.1+ 统一为 custom 可解决。若推理档位减少，需在 Codex 设置中手动启用完整档位。env: node: No such file or directory将 cc-switch 升级至 v3.18.0 或更高版本即可自动修复 GUI 环境下 PATH 缺失导致的环境变量解析失败问题。502 Bad GatewayCodex/Claude Desktop 报 502 多因 CLI proxy 冲突或 app-server 架构绕过代理，删掉 proxy 配置或降级版本可修复。用户在 GUI 中的配置修改完全无效OMO v4.19.3 将配置迁移至 ~/.omo/omo.jsonc，导致 cc-switch 写入旧路径失效。需手动编辑新配置文件或升级 cc-switch。查询用量必须同源请求 cc-switch在 cc-switch 中改用通用模板或自定义模板，并在请求地址中直接填写查询用量的 URL，即可绕过同源限制。"deepseek-v4-flash" is not a model多数相关 issue 仍未解决；升级到 CC Switch v4 后，为第三方模型填写其真实上下文窗口；仅在模型确实支持 1M 时使用 [1m]。官方账号突然不显示余量信息 Codex升级到包含 4.0 额度显示重做的最新版复测；若仍不显示，请提供版本、登录方式、套餐类型和日志。配置界面闪烁升级 cc-switch 修复表单异步加载导致的闪烁，并通过读取 SQLite 数据库解决 env 变量不随供应商更新的问题。IO 错误: 当文件已存在时，无法创建该文件 (os error 183)配置目录（如 .claude/.codex）被设成了 Junction/硬链接导致报错；去掉链接属性改用普通目录即可临时规避，等待 cc-switch 修复。ZIP 文件中未找到技能（需包含 SKILL.md 文件）升级 cc-switch 至 v3.16.2 或更高版本，并在导入同名 Skill 前手动删除旧目录，以解决路径解析与冲突提示错误。codex cli 失败：CC Switch将 cc-switch 升级至 v3.16.3 或更高版本即可修复本地环境检测与升级链路的阻塞问题。[proxy::response_processor] [Claude] 流错误当 cc-switch 代理 Claude Code 发生流解码错误或超时时，会导致日志遗漏或 token 统计为 0。可通过修改源码中的模型提取回退逻辑来修复模型名显示异常。自动升级不行，删除后重装还是老版本 Codex原帖尚无可验证的解法；#3156 有评论建议删除卸载后重装，#7080 的版本识别问题仍待确认。Automatic approval review failedCC Switch 本地代理在处理 Codex /responses 端点时上游返回 403，导致自动审核失败；问题暂无官方修复方案。X-OpenAI-Internal-Codex-Responses-Lite注释掉 custom provider 的 model_provider 配置并回到内建 openai provider；也可临时切换 gpt-5.4。会话过期了 Codex OAuth 会话已过期升级到 cc-switch v4.0.0 或更高版本，避免旧的 OAuth 数据覆盖新登录凭据。KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: 权限不够在 Linux 运行 cc-switch 遇 DRM 权限报错白屏时，可通过设置环境变量禁用 WebKit 硬件加速、指定 NVIDIA 渲染或改用 CLI 版解决。error code is 2503：CC Switch 安装失败遇到 error code 2503 时，改用 NSIS 的 -setup.exe 安装包；该问题线程没有确认此方法有效。点击任意按钮会闪烁一次 CC Switch在 Windows 上将 CC Switch 单独改用 WebView2 152.0.4191.62 Fixed Version，可避免 WebView2 153.0.4234.32 的点击闪烁。请求模型仍是旧会话模型，Codex在故障转移队列涉及的供应商配置中统一设置为所需模型；继续旧会话时请在 Codex 模型选择器中选择目标模型。unexpected status 403 Forbidden在 CC Switch 设置中关闭“保持官方登录”并重启，可阻止 Codex 自动发送生图请求导致中转站 403 报错。total_cost_usd = 0：Claude Code在 model_pricing 种子数据中补充 claude-opus-5-5 定价，避免导入的请求费用记为 $0。Not logged in · Please run /login将 ~/.claude.json 中的 PROXY_MANAGED 从拒绝审批名单移到同意名单，然后重新使用路由。auth.json 会被强制替换导致 Codex 无法使用升级到包含修复的后续版本；升级前先关闭 Codex 接管、登录官方 ChatGPT，再重新开启接管。使用统计失效 CodexCodex 更新到 26.917.51856 后，GPT-6 Sol 用量统计可能一直显示为 0；该 issue 未提供已确认的修复方法。[CODEX-SYNC] deferred 4 个 Codex将 cc-switch 升级至 v3.20.3，以修复 Windows 上会话文件因 mtime 不变而永久 deferred 的问题。本地 Codex 已是最新版本，但 CC Switch 检测为低版本升级到最新版 CC Switch，再到“应用”页核对 Codex 显示的版本、安装位置和来源。无法设定终端进程组：ioctl 操作原帖尚未提供可验证的解法；请跟进 Issue #5635 获取后续处理。无法获取模型升级到 v3.16.4 后重新获取模型；若仍失败，请在原帖补充供应商、报错文案或日志。OpenCode V2 用量采集停止更新将 CC Switch 升级到包含 PR #7541 修复的版本，使采集器读取 OpenCode V2 数据表。非官方供应商请填写 API Key - Claude Code升级到 cc-switch 4.0 或更新版本；若仍缺少 API Key 输入框，提供版本号、供应商类型和界面截图。配置了中转，但是一直请求不了 — Claude Code在上方栏目点击“路由”，开启路由后再应用到 Claude；“开启完整URL”并不等于开启路由，发帖者确认这样操作后解决。可选 isolation 被强制输出 Claude Code将 Responses 转换中的普通 function tool 显式设为 `strict: false`，保留 `required` 中原有的必填字段。Skill 更新会静默覆盖本地修改更新前先备份本地修改；当前拟议修复会将本地已改动的 Skill 排除在“全部更新”之外。Skills 自动导入后仍保留副本，CC Switch自动导入会将 Skills 复制到 `~/.cc-switch/skills/`，不会删除 `~/.agents/skills/` 中的源目录。一旦设置好key，打开codex过一两分钟就开始盗刷了 Codex原帖仅报告疑似异常调用，尚未提供可验证的解法或病毒文件位置。自身检查更新显示失败，本地环境检查中模型最新版本均显示未知 - Claude Code将 CC Switch 更新到最新版本后重试；4.0 已重构相关功能，但原帖未确认问题是否解决。编辑时表单内容会被最后一个覆盖，cc-switch这是已修复的 cc-switch 前端问题；原帖未说明包含修复的具体版本。闪退 Claude Code原帖尚未提供可验证的解法；请关注 Issue #2923 中的后续处理。
启动闪退 / 白屏30
cc-switch 启动闪退 / 白屏 / 黑屏 / 后台崩溃升级到最新版；Windows 白屏安装 WebView2，代理崩溃改端口并升级 v3.9.1+，旧 macOS/Linux 用 CLI 或对应发行版包。EGL_BAD_PARAMETER：CC Switch Linux 白屏在受影响的 Linux AppImage 环境中，先预加载宿主机的 libwayland-client；若仍白屏，可改用使用系统组件的 .deb 包。either event handler is re-entrantWindows 上出现该崩溃时，企业安全软件冲突场景可尝试设置 WebView2 参数；原帖未提供通用已验证修复。zsh:1: command not found: claude升级 cc-switch 至 v3.16.4 或更高版本以修复终端启动时未加载 PATH 的问题，或临时切换至系统默认终端。Codex 启动失败：缺少 supports_reasoning_summaries把 cc-switch 升级到 v3.18.0 及以上，重新切换 DeepSeek 供应商重新生成模型目录，即可自动补齐该字段并正常启动 Codex。unknown variant `image_url`, expected `text`不要向不支持图片输入的模型发送图片；可改用纯文本，或等待/使用已合入的移除图片后自动重试机制。assertion failed升级 cc-switch 至最新版本以修复底层 GUI 框架崩溃，或尝试关闭代理软件并重置网络。Linux 点击输入框卡死、界面不刷新升级到 cc-switch v3.13.0 及以上版本（启动时自动设置 WEBKIT_DISABLE_COMPOSITING_MODE=1 并做窗口焦点修复）即可解决。Could not create default EGL displayLinux 下 cc-switch 强制 WEBKIT_DISABLE_DMABUF_RENDERER=1 导致白屏，预设该变量为 0 再启动即可恢复；点击失效/卡死另有对应变体解法。ASProxy64.dll 访问违规导致闪退在 Astrill 的 Help → Hard excluded apps 中添加 cc-switch.exe，然后重新登录 Astrill。No such file or directory (os error 2)将 config.toml 中的 model_catalog_json 绝对路径修改为相对路径 cc-switch-model-catalog.json，或升级 cc-switch。Failed to initialize gtk backend cc-switch在无图形化环境（如服务器或容器）中运行 cc-switch 会因缺少 GTK 报错，请改用 cc-switch-cli 命令行版本。AbsolutePathBuf deserialized without a basemacOS Codex Desktop 用户可将 config.toml 中的 model_catalog_json 改为模型目录文件的绝对路径。KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: 权限不够在 Linux 运行 cc-switch 遇 DRM 权限报错白屏时，可通过设置环境变量禁用 WebKit 硬件加速、指定 NVIDIA 渲染或改用 CLI 版解决。显示为【白色屏幕】 Claude Code旧系统上 cc-switch 可能无法启动；Windows 可更新至 24H2，macOS 可尝试维护者建议的 CC Switch CLI。http://127.0.0.1:15721 代理配置卡死升级到 CC Switch v3.16.2 修复备份损坏导致的代理卡死，或改用“替换配置”模式手动写入环境变量。主窗口始终不显示，Windows 下 CC Switch 启动异常先检查 Windows 更新、WebView2 参数等环境因素；现有 issue 没有确认适用于所有情况的通用修复。Request exceeds the context window原帖未提供可验证的解法；该问题已作为与 catalog 配置及自动压缩相关的重复项关闭。打开后就闪退：CC Switch Windows 启动闪退在最新版复现时，提供 CC Switch、Windows 和 WebView2 版本，以及最新日志和事件查看器错误信息以便定位。settings.json 被全量重写将需保留的 Claude Code 项目设置放入 `.claude/settings.local.json`，避免 cc-switch 覆盖用户级 `settings.json` 时丢失。仍包含 `disable_response_storage = true`原帖尚未提供可验证的解法；已有 PR 提议清理 disable_response_storage 的生成路径，但未确认合并或发布。在deepin23系统下，deb安装后打不开 Codex、Claude Code原帖尚未提供可验证的解法；该报告已被归并到 #3133，请在主讨论跟进修复进展。输入框无法获得焦点/无法输入 OpenCode当前没有已确认的修复方案；该问题在 Linux Wayland 与 NVIDIA 环境下进入编辑页后会卡死。添加供应商时出现白屏先升级到 CC Switch 4.0.13；若仍能复现，请携带版本、系统环境、复现步骤和日志重新反馈。invalid function arguments json string：Codex将 cc-switch 升级到 3.16.4 或更高版本后，用 MiniMax-M3 重新测试。Loading后无法打开应用，cc-switch 便携版原帖尚未提供可验证的解法；请查看该问题的后续讨论。可选 isolation 被强制输出 Claude Code将 Responses 转换中的普通 function tool 显式设为 `strict: false`，保留 `required` 中原有的必填字段。闪退 Claude Code原帖尚未提供可验证的解法；请关注 Issue #2923 中的后续处理。打开黑屏，几秒后闪退 CC Switch Windows请等待包含 Windows 平台禁用 Overlay 的后续版本；原帖未提供可验证的当前解法。无法启动cc-switch，cc-switch --version也没有输出维护者建议先重装；若仍无法启动可尝试 CLI 版，原帖未确认恢复。
安装与安装包21
macOS cc-switch检测版本错误/卡死修改.zshrc中fastfetch调用，添加[[ -t 1 ]]限制非交互式输出。cc-switch 安装失败：依赖冲突、权限不足与杀软误报根据报错类型分别处理：旧版 Linux 缺依赖换用社区编译版，Windows 权限不足改装至 AppData，杀软误报可自行编译。"Failed to upload "image.png"" 截图上传失败这不是 cc-switch 的报错，而是 GitHub 截图没传上去留下的占位符；重新上传截图或直接粘贴文字版报错，否则维护者看不到任何信息。skills 安装路径不对 cc-switch旧版 cc-switch 会把 skills 装到 ~/.claude/skills/skills，Claude Code 不识别；升级到修复版本，或临时把内容上移到 ~/.claude/skills/。安装提示缺少libwebkit2gtk-4.1.so.0 cc-switch在 Rocky 9 安装 rpm 包会因缺少 webkit 依赖失败，升级系统至 Rocky 10.1 即可解决。cc-switch 升级失败、卡死或花屏问题排查升级 cc-switch 到最新版本（v3.16.3+ 修复了更新卡死问题，v3.20.0+ 支持 winget 安装的 Claude Code，v4.0 重构了升级流程）；winget 安装的 Claude Code 需用 winget 命令手动升级。Skill 源目录缺少 SKILL.md，Claude Code 技能安装失败如果安装时提示源目录缺少 SKILL.md，检查技能仓库的实际目录结构，并确认 SKILL.md 位于被解析的技能目录中。`GLIBC_2.35' not foundv3.10.1–v3.16.1 未有已确认兼容版本；按维护者建议试用 v4，仍报错则附版本和复现步骤重新提交。openclaw.json is not valid JSON - OpenClaw手动为 ~/.openclaw/openclaw.json 中的 models 键添加双引号，以修复严格 JSON 解析失败的问题。Error 2503：Windows 11 上 CC Switch MSI 安装失败以管理员身份打开命令提示符，运行 msiexec /i 并指定 MSI 文件路径。本地有claude cli但是关于设置里显示未安装升级 CC Switch 至 v3.16.5 或更高版本，以修复 Windows 下 npm 全局包多入口导致的误报冲突及路径乱码问题。Symlink target not foundAppImage 安装失败，需手动修复 .DirIcon 符号链接为相对路径。本地代理开关 UI 组件被截断，无法完全显示升级 cc-switch 至最新版本以修复窗口缩放导致的 UI 截断及托盘菜单溢出问题。does not run on macOS versions other than先执行 `brew update` 后重试安装；若 cask 仍锁定 Monterey，需将 macOS 条件改为 `>= :monterey`。error code is 2503：CC Switch 安装失败遇到 error code 2503 时，改用 NSIS 的 -setup.exe 安装包；该问题线程没有确认此方法有效。点击任意按钮会闪烁一次 CC Switch在 Windows 上将 CC Switch 单独改用 WebView2 152.0.4191.62 Fixed Version，可避免 WebView2 153.0.4234.32 的点击闪烁。安装失败: 技能目录不存在 cc-switch升级到 cc-switch v3.14.0 或改用本地 ZIP 安装，以修复根目录包含 SKILL.md 的仓库 URL 安装失败问题。主窗口始终不显示，Windows 下 CC Switch 启动异常先检查 Windows 更新、WebView2 参数等环境因素；现有 issue 没有确认适用于所有情况的通用修复。1M上下文配置不生效 Claude Code将 cc-switch 数据库中 Opus 路由从 claude-opus-4-8 回退为 claude-opus-4-6 后重启 Claude Desktop。在deepin23系统下，deb安装后打不开 Codex、Claude Code原帖尚未提供可验证的解法；该报告已被归并到 #3133，请在主讨论跟进修复进展。Input should be a valid string多数相关 issue 仍未解决；升级到 cc-switch v3.20.4 后重试；若仍报 422，请新开会话或回退到图片出现前。
这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。