安装与启动问题
装不上、打不开、更新完出问题，都在这里。
129 个主题页，汇总自 618 个真实 issue口径说明
终端与环境变量78
cc-switch 本地代理常见问题：502 Bad Gateway、超时、无法删除配置代理相关问题多由官方供应商不被支持、配置未生效或 UI 状态不同步引起；需按场景检查代理模式、供应商类型与接管状态。Codex 用量统计被双倍放大或虚增升级到 v3.19.2 并在用量页执行「重建 Codex 用量」以修正历史虚增数据。'claude' 不是内部或外部命令，也不是可运行的程序升级至 v3.16.2+ 以修复 WSL/Windows 路径检测问题，或手动配置安装目录覆盖。cc-switch 启动白屏 / 黑屏 / 闪退 / 无界面（launch crash）先区分是窗口状态损坏、WebView2/系统兼容问题，还是安全软件拦截；按日志和现象分别处理，必要时改用 CLI 版。cc-switch 导致 Claude Code / Codex 的 MCP 配置丢失升级 cc-switch 到最新修复版，关闭或谨慎使用统一接管 MCP，逐个排查无效 MCP，并手动修正被改写的 command/type/path 字段。content[].thinking must be passed back升级 cc-switch 到 v3.16.0 或更高版本；临时可回退 Claude Code 到 2.1.150 或关闭 thinking。ANTHROPIC_BASE_URL 被改成 127.0.0.1开启本地路由时 ANTHROPIC_BASE_URL 指向 http://127.0.0.1:15721 是预期；把插件等公共字段移进「通用配置」，切换后重启 Claude Code 生效。claude mcp list 显示 ✘ Failed to connectWindows 下 cc-switch 会把 MCP 的 npx 命令自动包装成 cmd /c，破坏 stdio 管道导致连接失败；手动改回 ~/.claude.json 或用 claude mcp add 重写可临时解决。settings.json被全量重写导致插件失效多数相关 issue 仍未解决；升级至v3.20.1+，该版本已修复切换配置时清空enabledPlugins等字段的Bug。Not logged in · Run /login - Claude Code开启 CC Switch 本地代理接管，检查 API 地址是否包含 /v1，或通过 CC Switch 启动终端以注入环境变量。unexpected status 502 Bad Gateway Codex在代理软件中将 127.0.0.1 设为直连，或在 Codex 环境变量中配置 NO_PROXY 以绕过本地代理拦截。原子替换失败 不支持该请求 os error 50 cc-switch升级 cc-switch 至 v3.20.0 或更高版本，以修复 WSL 路径下配置文件原子替换失败的回归问题。我windows11打开cc，为什么只有进程没有界面 cc-switchWindows 11 可在 exe 属性中尝试兼容 Windows 7；无效则改用 cc-switch-cli 绕过 Tauri 2 GUI 白屏。x-anthropic-billing-header 导致缓存失效 CC Switch升级 CC Switch 至 v3.15.0+，修复 openai_responses 模式下动态 billing header 破坏前缀缓存的问题。Auth conflict删除 claude.json 中的 primaryApiKey，或将环境变量改为 ANTHROPIC_API_KEY 以解决认证冲突。bash: 无法设定终端进程组 cc-switch这是 3.18.0 在 Linux 下检查本地代理环境的已知 Bug，降级到 3.18.0 之前的版本，并直接在终端手动配置代理。env: node: No such file or directory升级 cc-switch 至 v3.18.0+，修复 macOS GUI 启动时 PATH 缺失导致更新 Codex 找不到 node 的问题。model does not support thinking在 cc-switch 高级设置里关掉整流器（Proxy Rectifier），或升到修复版本；Qwen 工具调用死循环、空 thinking block 等变体仍未解决。Your access token could not be refreshed升级 cc-switch 至 v3.17.0+，修复接管时写入 PROXY_MANAGED 占位符污染 OAuth 凭证或导致 401 的问题。选择了代理转发到远程，但还是给本地进行转发彻底删除 .cc-switch 配置目录以清除缓存，并升级至 v3.17.0 修复代理限制与统计 Bug。temporarily unavailable, so auto mode cannot升级 cc-switch 至 v3.15.0+ 以修复模型映射与 thinking 转换，或在通用配置中手动覆盖默认模型环境变量以匹配第三方后端。未安装 / not installed or not executable升级 CC Switch 至 v3.20.0+ 以修复自定义 npm prefix 及 macOS 检测失败，Windows 误报多处安装需升级至 v3.16.5+。'claude' 不是内部或外部命令在 CC Switch 设置中手动指定 claude 可执行文件的完整路径，或确保该路径已加入系统 PATH。Invalid type for 'messages'升级 cc-switch 至最新版修复转换 Bug，或降级 Codex CLI 至 0.80.0 并改用 wire_api="chat" 绕过。无法导入供应商，无法进行会话管理 cc-switch升级 cc-switch 以支持 jsonc 配置；WSL2 环境需定时克隆数据库至 Windows 本地路径以绕过 SQLite 锁定。not installed or not executable - OpenCode升级 CC Switch 至 v3.11.0+ 修复路径检测，或手动将 opencode 软链接至 ~/.local/bin。Unkonw coding plan provider cc-switch 火山引擎升级 cc-switch 至 v3.20.0 及以上版本，并重建或修改火山引擎 Agent Plan 供应商的 Base URL。检测到多处安装或显示为未安装 - Codex/OpenCode升级 CC Switch 至 v3.17.0 及以上版本，修复 Windows 下 npm 路径解析及包装脚本误判问题。每次点击都会先弹出系统文件夹选择器 cc-switch修改 src/App.tsx 移除 handleOpenTerminal 中的 pickDirectory() 调用，即可解决点击打开终端时强制弹出文件夹选择器的问题。zsh:1: command not found: claude升级 cc-switch 至 v3.16.4 或更高版本以修复终端启动时未加载 PATH 的问题，或临时切换至系统默认终端。401 认证失败: Claude Desktop gateway token 无效清除 Claude Desktop 的官方 OAuth 登录态，或修改 .claude.json 配置文件以解决 401 网关 token 无效问题。切换渠道后auth.json完全没变 - CodexCodex 切换渠道后 auth.json 未更新，需手动修改 auth.json 或等待 cc-switch 修复。重启电脑后禁用的 MCP 重新生效 - Codex官方尚未修复此配置覆盖问题，需手动清理配置文件中的冲突 MCP 节点，并谨慎使用 deeplink 导入以防自定义设置丢失。codex中只有258k上下文 - Codexcc-switch 将 minimax 模型映射为 gpt-5.5 后，会触发 Codex 和 Claude Code 的硬编码上下文限制，导致 1M 上下文失效。codex从来不显示ds的模型 - CodexCodex 桌面端需官方登录态才显示第三方模型，请在 cc-switch 开启「切换第三方时保留官方登录」并重启。到claude 里面提示 401 - Claude Code开启 cc-switch 的本地代理功能以转换 API 格式，并确保 `ANTHROPIC_BASE_URL` 环境变量正确注入到 Claude Code 进程中。cc-switch老是自动删除我的环境变量冲突弹窗直接关闭不会删除环境变量；想彻底消除需删除 shell 配置或 Hermes config.yaml 中的对应项；v3.17.0 弹窗无法关闭是已知问题。Error running remote compact task 报错 - Codex升级 cc-switch 至 v3.12.0 或更高版本，该版本在本地代理中新增了对 Codex `/responses/compact` 路由的转发支持，可解决 404 或 502 报错。重启终端，执行gemini，提示需要输入api-key - Gemini CLI更新 cc-switch 修复保存清空 bug；若仍无效则是 Gemini CLI 官方读取 bug，需将环境变量写入 bash_profile。Function call is missing使用社区补丁 cc-switch-gemini-fixer 或在历史消息中注入 skip_thought_signature_validator 以绕过 Gemini 工具调用的签名验证。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: Write failed在 cc-switch 中关闭 Tool Search、最大强度思考及 1M 上下文声明以降低长文本截断概率，或回退至 3.13.0 版本。skills同步到了未选择的应用上 OpenCode升级 cc-switch 到 v3.12.3 修复隐式推断 bug，并在 OpenCode 设置中关闭默认读取 .claude 目录下 skills 的选项。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 cc-switch MSI 安装权限被拒绝通过管理员权限的命令提示符运行 msiexec 命令，或直接下载 Portable 免安装版来绕过 Windows 11 的 MSI 权限限制。本地有claude cli但是关于设置里显示未安装升级 CC Switch 至 v3.16.5 或更高版本，以修复 Windows 下 npm 全局包多入口导致的误报冲突及路径乱码问题。配置WSL路径但技能读不到 cc-switch在 Windows 版 cc-switch 中无法直接读取或安装 WSL 的 ~/.agents/skills，需直接在 WSL 内安装并运行 Linux 版 cc-switch。API Error: 404 Claude Code 路径拼接或未注册路由检查 API 地址是否被错误拼接，或升级 cc-switch 以修复 OpenAI 兼容模式及本地路由缺失导致的 404 问题。Symlink target not foundAppImage 安装失败，需手动修复 .DirIcon 符号链接为相对路径。ccstatusline 显示的模型名不正确 - Claude Code在 ccstatusline 中配置 Custom Command 脚本，读取 cc-switch 数据库中的环境变量以正确显示实际模型。打开终端未使用完整配置通过「通用配置」面板提取并勾选写入，避免全量覆盖导致插件等共享配置丢失。为什么单独在终端使用claude命令使用的模型与在cc-switch中使用的模型不一样呢把真实要用的 MiniMax 设为主模型，并在 cc-switch 打开的终端运行 claude；未开启接管时终端里显示的映射名不代表请求被替换。在codex桌面端中接入gpt5.5无法图片输入和切换推理强度 - Codex删除 Codex 下的 cc-switch 配置文件并重建，或手动修改 cc-switch-model-catalog.json 补充缺失的推理档位和图片模态。No such file or directory (os error 2)将 config.toml 中的 model_catalog_json 绝对路径修改为相对路径 cc-switch-model-catalog.json，或升级 cc-switch。Copied订阅接入时模型映射不生效升级至 v3.15.0 或更高版本以修复 Copilot 订阅模型映射失效问题。"Expecting property name enclosed in double升级 CC Switch 至 v3.16.4 或更高版本，以修复大请求体未正确解压导致的 JSON 解析错误。Function call is missing a thought_signature在 Claude Desktop 代理模式下使用 Gemini Native 触发工具调用时，因会话 ID 不匹配导致 thought_signature 丢失，需等待官方修复。version `GLIBC_2.35' not found官方 AppImage 依赖高版本 GLIBC，RHEL/Rocky Linux 用户可改用社区编译的 Flatpak 版本或旧基础镜像构建版。该模型始终思考，不支持关闭思考；请使用 low、high 或 max。在 cc-switch 配置中将 glm-5.3 设为强制思考模式，禁用 thinking.type: disabled。env: node: No such file or directory将 cc-switch 升级至 v3.18.0 或更高版本即可自动修复 GUI 环境下 PATH 缺失导致的环境变量解析失败问题。This software does not run on macOS执行 `brew update` 后重试安装，或手动从 GitHub Releases 下载 DMG 安装。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 版解决。Missing API key · Run /login - Claude Code清除冲突的 ANTHROPIC_BASE_URL 环境变量，或升级 CC Switch 使用内置的环境变量冲突检测功能。No endpoints available that support升级 Claude Code 至 v2.1.92 及以上版本，并更新 cc-switch 以修复 OpenRouter 参数传递错误，或尝试关闭本地代理。not found(404) 添加Claude code桌面版模型api失败升级至 v3.16.3+ 以修复连通性检测误报，或忽略 404 直接测试实际调用。thinking enabled but reasoning_content关闭 Claude Code 的 Thinking 模式，或升级 cc-switch 解决 Kimi/Moonshot 工具调用报错。'/d' 不是内部或外部命令 CC Switch点“打开终端”选中中文工作目录后报 '/d' 时，先改用英文目录或用 mklink /J 建立英文 junction 绕过；彻底修复需让 .bat 全部使用 CRLF 并加 chcp 65001。claude.ai connectors are disabled取消设置 `ANTHROPIC_API_KEY` 环境变量，以恢复 claude.ai 登录和组织连接器的加载。模型就自动切换到了haiku上 cc-switch这是 Claude Code 自带特性：haiku 用于读文件，cc-switch 只管理环境变量，不会改变模型选择。Bash(...) Waiting... Claude Code降级 Claude Code 至 v2.1.104 或 v2.0.64（需管理员权限），或切换至阿里云百炼等兼容 provider，因 Nvidia 模型无法正确解析 tool use 格式。无法应用于claude code for VS Code - Claude Code删除 VS Code 中关于 claude code 的旧代理设置，并在 cc-switch 中重新开关“应用到Claude Code插件”选项即可解决。原子替换失败 os error 50将 Claude Code 配置目录从 WSL 路径改回 Windows 本地路径，或回退至 v3.19.0。正文内容频繁出现在 thinking（思考）块内，visible text 块几乎为空升级 cc-switch 至包含 PR #4210 的版本，将预注入 thinking 占位符改为反应式处理即可解决长上下文会话冻结与正文折叠问题。Unsupported parameter: 'max_tokens'报错来自路由转发时携带了模型不支持的 max_tokens 参数；issue 中未给出已确认的修复步骤，请核对模型参数支持或等待 cc-switch 修复。已安装，但无法在当前环境中运行，请检查 CC Switch升级到 CC Switch v3.16.1 或更新版本，修复 Windows 上 cmd /C 引号处理导致本地环境检查把已安装 CLI 误报为“无法运行”的问题。
更新与升级36
Codex API key被自动修改导致model xxx not found升级至v3.19.2+，修复了多供应商共用地址时API Key因读取auth.json而错误收敛的问题。CC Switch 开启代理后 Claude Code 报错或模型映射失败先升级到 v3.15.0 以上，再在 cc-switch 中显式配置全局出站代理，避免系统代理被旧进程缓存。获取模型列表失败先升级 cc-switch 并先添加模型行再获取列表；若仍失败，用 curl 验证 /v1/models 权限。cc-switch 配置用量查询失败 / 用量查询一直显示失败 / undefined升级到 v3.16.2+；仍失败时按 NewAPI 格式填写 base_url 和访问令牌，或关闭自动刷新/用量查询。cc-switch 检查更新失败 / 更新安装失败更新失败多因权限不足或 GitHub 网络异常；请用管理员/绿色版安装，或到 GitHub Releases 手动下载。<!-- Failed to upload "image.png" -->截图上传失败不影响问题本身，请直接用文字描述报错信息。在Codex界面，官方订阅无法查询用量 - Codex开启本地路由映射以统计特定模型用量，第三方API需适配查询脚本，Claude官方及Free账号暂不支持查询。unexpected status 502 Bad Gateway Codex在代理软件中将 127.0.0.1 设为直连，或在 Codex 环境变量中配置 NO_PROXY 以绕过本地代理拦截。自动升级不行，重新下载新版本安装之后还是老版本彻底卸载旧版本并清理残留后重新安装，即可解决自动升级失败或版本未更新的问题。重启后.claude下的auth.json会被强制替换 - Codex升级 cc-switch 至最新版，或在登录官方账号前先关闭代理接管，避免旧快照覆盖官方凭据。bash: 无法设定终端进程组 cc-switch这是 3.18.0 在 Linux 下检查本地代理环境的已知 Bug，降级到 3.18.0 之前的版本，并直接在终端手动配置代理。codex升级为ChatGPT后不适配了吗 cc-switch升级到 cc-switch v3.17.0，该版本已适配 Codex 合并到 ChatGPT Desktop 后的供应商切换，避免旧配置被覆盖。codex 会话已过期 - Codex备份配置后运行脚本同步 auth.json 的 token 至 cc-switch 数据库与本地文件，或关闭用量刷新防止旧数据覆盖。结果显示用了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 以跳过审批弹窗。还没有添加任何供应商升级或云同步后 UI 状态与底层数据库不同步，完全重启应用或重新导入备份即可恢复供应商列表。Codex Desktop UI 的项目列表完全为空 - Codex升级 CC Switch 后 model_provider 键名变更，统一改回 custom 或升到修复版本；官方登录态丢失、推理档位变少等情形仍未解决。用cc-switch切换, 发现无效 - CodexCodex 不支持热切换，必须在 cc-switch 切换中转站后彻底重启 Codex 应用，会话丢失可通过迁移工具恢复。获取模型失败 cc-switch升级 cc-switch 至 v3.16.4+ 修复 404 探测问题；若为 Coding Plan 需手动更改 API 地址并手动填入模型。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，即可绕过同源限制。is not a model this version of Claude Code设置环境变量 CLAUDE_CODE_MAX_CONTEXT_TOKENS 或在模型名后追加 [1m] 以指定正确的上下文窗口大小。点击更新后卡住强制退出并重新打开软件，或手动更新至 v3.16.3 及以上版本以修复更新死锁问题。os error 183 当文件已存在时，无法创建该文件 Claude CodeWindows 下配置目录为 Junction 时 cc-switch 会报 os error 183，需暂时移除目录链接或等待官方修复。ZIP 文件中未找到技能（需包含 SKILL.md 文件）升级 cc-switch 至 v3.16.2 或更高版本，并在导入同名 Skill 前手动删除旧目录，以解决路径解析与冲突提示错误。macOS cc-switch检测版本错误/卡死修改.zshrc中fastfetch调用，添加[[ -t 1 ]]限制非交互式输出。codex cli 失败：CC Switch将 cc-switch 升级至 v3.16.3 或更高版本即可修复本地环境检测与升级链路的阻塞问题。[proxy::response_processor] [Claude] 流错误当 cc-switch 代理 Claude Code 发生流解码错误或超时时，会导致日志遗漏或 token 统计为 0。可通过修改源码中的模型提取回退逻辑来修复模型名显示异常。This model is not supported when using注释掉 config.yaml 中的 model_provider = custom，恢复使用官方 OpenAI provider。env: node: No such file or directory将 cc-switch 升级至 v3.18.0 或更高版本即可自动修复 GUI 环境下 PATH 缺失导致的环境变量解析失败问题。KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: 权限不够在 Linux 运行 cc-switch 遇 DRM 权限报错白屏时，可通过设置环境变量禁用 WebKit 硬件加速、指定 NVIDIA 渲染或改用 CLI 版解决。error code is 2503 或升级后图标变白修改 per-user-main.wxs 移除快捷方式 Icon="ProductIcon" 属性即可解决安装失败与升级后图标丢失问题；旧版用户需取消固定后重新固定。配置界面闪烁升级 cc-switch 修复表单异步加载导致的闪烁，并通过读取 SQLite 数据库解决 env 变量不随供应商更新的问题。unexpected status 403 Forbidden在 CC Switch 设置中关闭“保持官方登录”并重启，可阻止 Codex 自动发送生图请求导致中转站 403 报错。unexpected status 403 Forbidden关闭 cc-switch 本地代理或检查上游 API 对 codex-auto-review 模型的访问权限。
启动闪退 / 白屏16
cc-switch 启动闪退 / 白屏 / 黑屏 / 后台崩溃升级到最新版；Windows 白屏安装 WebView2，代理崩溃改端口并升级 v3.9.1+，旧 macOS/Linux 用 CLI 或对应发行版包。cc-switch 启动白屏 / 黑屏 / 闪退 / 无界面（launch crash）先区分是窗口状态损坏、WebView2/系统兼容问题，还是安全软件拦截；按日志和现象分别处理，必要时改用 CLI 版。EGL_BAD_PARAMETER 白屏报错 cc-switch改用 .deb 或 AUR 原生包安装，或通过 LD_PRELOAD 预加载系统库运行 AppImage 以解决 ABI 冲突。缺少 supports_reasoning_summaries 字段 Codex升级 cc-switch 至 v3.18.0 及以上版本，修复生成模型目录时缺失必需字段导致 Codex 启动失败的问题。assertion failed升级 cc-switch 至最新版本以修复底层 GUI 框架崩溃，或尝试关闭代理软件并重置网络。zsh:1: command not found: claude升级 cc-switch 至 v3.16.4 或更高版本以修复终端启动时未加载 PATH 的问题，或临时切换至系统默认终端。HTTP 400 unknown model 'ark-code-latest'在 CC Switch 中将 MiniMax 供应商的模型 ID 从火山方舟专用的 ark-code-latest 更改为 MiniMax-M3 即可解决此 400 报错。界面不会自动刷新，只有手动拖动窗口才会触发 UI 重绘升级至 v3.13.0+ 修复 Linux 界面卡死；Windows 内置管理员需修改注册表以正常显示主界面。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 base在 macOS 版 Codex 中，CC Switch 写入的相对路径会导致此报错。请手动将 `~/.codex/config.toml` 中的 `model_catalog_json` 修改为绝对路径即可修复。KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: 权限不够在 Linux 运行 cc-switch 遇 DRM 权限报错白屏时，可通过设置环境变量禁用 WebKit 硬件加速、指定 NVIDIA 渲染或改用 CLI 版解决。http://127.0.0.1:15721 代理配置卡死升级到 CC Switch v3.16.2 修复备份损坏导致的代理卡死，或改用“替换配置”模式手动写入环境变量。主窗口完全空白(纯白)设置环境变量 WEBKIT_DISABLE_DMABUF_RENDERER=0 以恢复 WebKitGTK 2.52 + Mesa 下的正常渲染。“event handler is re-entrant” 报错或启动闪退卸载 Windows 更新 KB5081263 或等待 cc-switch 升级以规避 TAO EventLoop 重入导致的崩溃与界面不渲染问题。打开后就闪退 cc-switch目前没有已确认修复：卸载重装也无效，先收集 debug 日志并保留现场，等待官方修复。
安装与安装包15
<!-- Failed to upload "image.png" -->截图上传失败不影响问题本身，请直接用文字描述报错信息。安装提示缺少libwebkit2gtk-4.1.so.0 cc-switch在 Rocky 9 安装 rpm 包会因缺少 webkit 依赖失败，升级系统至 Rocky 10.1 即可解决。skills 安装路径不对 cc-switch旧版 cc-switch 会把 skills 装到 ~/.claude/skills/skills，Claude Code 不识别；升级到修复版本，或临时把内容上移到 ~/.claude/skills/。openclaw.json is not valid JSON - OpenClaw手动为 ~/.openclaw/openclaw.json 中的 models 键添加双引号，以修复严格 JSON 解析失败的问题。Skill 源目录缺少 SKILL.md，拒绝同步以避免覆盖目标目录当技能仓库目录结构与 skillId 不匹配或存在嵌套时 CC Switch 会安装失败，可改用 `npx skills add` 命令行手动安装。Error 2503 cc-switch MSI 安装权限被拒绝通过管理员权限的命令提示符运行 msiexec 命令，或直接下载 Portable 免安装版来绕过 Windows 11 的 MSI 权限限制。本地有claude cli但是关于设置里显示未安装升级 CC Switch 至 v3.16.5 或更高版本，以修复 Windows 下 npm 全局包多入口导致的误报冲突及路径乱码问题。Symlink target not foundAppImage 安装失败，需手动修复 .DirIcon 符号链接为相对路径。无法安装和更新 Codex CC Switch升级到 v3.16.3+ 后从「设置 → 关于」重新安装/更新 Codex；若 v3.16.5 仍失败请带日志反馈。version `GLIBC_2.35' not found官方 AppImage 依赖高版本 GLIBC，RHEL/Rocky Linux 用户可改用社区编译的 Flatpak 版本或旧基础镜像构建版。This software does not run on macOS执行 `brew update` 后重试安装，或手动从 GitHub Releases 下载 DMG 安装。error code is 2503 或升级后图标变白修改 per-user-main.wxs 移除快捷方式 Icon="ProductIcon" 属性即可解决安装失败与升级后图标丢失问题；旧版用户需取消固定后重新固定。安装失败: 技能目录不存在 cc-switch升级到 cc-switch v3.14.0 或改用本地 ZIP 安装，以修复根目录包含 SKILL.md 的仓库 URL 安装失败问题。“event handler is re-entrant” 报错或启动闪退卸载 Windows 更新 KB5081263 或等待 cc-switch 升级以规避 TAO EventLoop 重入导致的崩溃与界面不渲染问题。本地代理开关 UI 组件被截断，无法完全显示升级 cc-switch 至最新版本以修复窗口缩放导致的 UI 截断及托盘菜单溢出问题。
这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。