CCSwitch-operations

---
name: CCSwitch-operations
description: "Operate CC Switch (CCS): safely modify and sync its managed configuration — global prompts, skills, MCP servers, providers, and the Codex model catalog — across Codex, Claude Code, Claude Desktop, and other managed apps via cc-switch.db and the managed config files. Use when the user asks to 同步/修改 CCS 或 CC Switch 配置、全局提示词、skill 同步/安装、MCP 配置、供应商配置、修复 CCS 乱码, or whenever CCS-managed files must be edited without being overwritten on the next sync."
---

# CC Switch Operations

Methodology for safely operating CC Switch (CCS): backup first, stop the app, edit, validate, restart, and re-check.

> **Version compatibility**: designed and tested with CC Switch **3.20.4** (database schema v19; 3.20.4 migrates v18 → v19 on first start and adds `enabled_mcode` to `mcp_servers`/`skills`). CC Switch 3.20.1–3.20.3 (schema v18) and 3.20.0 (schema v17) remain compatible — after running 3.20.4 older versions refuse to open the database, so keep the pre-upgrade backup. MiniMax Code (`mcode`) commands need 3.20.4+; the helper detects missing `enabled_mcode` columns and keeps working against v18 databases. Run `scripts/ccs_db.py doctor` to verify the installed schema; other versions may behave differently — see `references/migration.md` for official version behavior changes.

> **Iron rule**: when unsure, first carefully read this skill (SKILL.md and its references) — do not improvise or guess. If the request is genuinely outside this skill's scope, tell the user and propose concrete recommended actions instead.

## 1. Safety workflow (mandatory for any write)

1. Backup: config files become `*.bak-<yyyyMMdd>-<slug>`; the database is copied to `<cc-home>/backups/db_backup_<stamp>.db`.
2. Stop CCS (the `cc-switch` process) before editing its database; a running CCS can overwrite your edits from memory.
3. Edit (see the sections below; use `scripts/ccs_db.py` for database writes).
4. Validate: TOML with `tomllib`, JSON with `json.load`, database with `python scripts/ccs_db.py check`; inspect Chinese text with `repr()`/`ascii()`.
5. Restart CCS, wait 3–5 seconds.
6. Re-parse the config files and confirm CCS did not rewrite them.
7. Remind the user to restart target apps (config is loaded at startup).

## 2. Encoding safety

- Never pipe Chinese text into Python through a shell that can mangle encoding (Windows PowerShell 5.1 uses the console code page; Chinese can become `?` and corrupt the DB permanently).
- Use `scripts/ccs_db.py` for Chinese-containing DB writes; pass Chinese inline (wide argv) or via UTF-8 files (`--*-file`).
- On Windows PowerShell, save `.ps1` files as UTF-8 with BOM.
- After any write, run `scripts/ccs_db.py check`; it covers user-facing text and JSON/TOML blobs and reports `?` only when it looks like mojibake (not legitimate URL query strings).

## 3. Architecture (details: references/architecture.md)

- Database: `<cc-home>/cc-switch.db` (schema v19 on CCS 3.20.4 — `mcp_servers`/`skills` carry `enabled_mcode`; v18 on 3.20.1–3.20.3; v17 on 3.20.0). Hand-maintained tables: `providers`, `prompts`, `skills`, `mcp_servers`, `settings`. CCS-managed tables (`model_pricing`, `profiles`, `proxy_*`, `session_log_sync`, `session_usage_dedup`, `usage_daily_rollups`, `skill_repos`, ...) must not be edited by hand.
- `cc-home` discovery: `CC_SWITCH_HOME` env var, else `~/.cc-switch`. `scripts/ccs_db.py` resolves this automatically; `doctor` prints the resolved paths.
- Managed apps (10): codex, claude, claude-desktop, gemini, grokbuild, opencode, openclaw, hermes, pi, mcode. Switch-mode apps (claude/codex/gemini) write only the current provider; additive-mode apps (opencode/openclaw/hermes/pi/mcode) let providers coexist. Pi has no MCP registry and its skills are exists-equals-enabled; Claude Desktop is not synced by CCS. MiniMax Code (`mcode`) keeps its providers in `~/.minimax/config.yaml` (`custom_provider` YAML — the provider-* commands refuse it on purpose), gets MCP/skills/prompts only after `enabled_mcode=1`, writes prompts to `~/.minimax/AGENTS.md` (32 KiB per prompt), and has no proxy takeover, failover, tray, common-config or Profiles; its data dir is `MINIMAX_DATA_DIR` → `MAVIS_DATA_DIR` → `~/.minimax`.
- Official/bundled MCP servers (for example `openaiDeveloperDocs`) are intentionally absent from the `mcp_servers` table; do not add them.

## 4. Global prompts (prompts table)

- `prompts` stores `app_type` (9 values) and `name='全局'` content with `enabled=1`.
- Update via `scripts/ccs_db.py prompt-set --app-type codex|claude|... --content-file <utf8.txt>`.
- Keep codex and claude contents consistent unless the user explicitly asks otherwise.

## 5. Skills

- Source of truth: `<cc-home>/skills/<name>/SKILL.md`; `skills.enabled_*` flags control per-app enablement.
- Install to an app = copy/symlink/junction the skill folder into the app's skills directory (see references/apps.md for per-app paths). The exact link style is controlled by CCS `skillSyncMethod` (auto/symlink/copy).
- After editing a local SKILL.md, refresh its `content_hash` with `skill-upsert`.

## 6. MCP

- Three places must stay consistent for user-managed MCP servers: `~/.codex/config.toml` (live), the `mcp_servers` table (panel), and the current codex provider's `settings_config.config` text. Use `mcp-upsert` + `provider-block`.
- Claude Desktop MCP configs are separate JSON files (see references/operations.md).
- Codex does not support SSE transport; bridge via `npx -y mcp-remote <url> --transport sse-only` where needed.

## 7. Verification checklist

- `python scripts/ccs_db.py check` passes.
- `python scripts/ccs_db.py check --strict` and `doctor --audit` pass (structural safety + three-way consistency).
- `codex mcp list` shows the expected command/args/env; official/bundled servers may appear without `mcp_servers` rows.
- `settings.json` `currentProvider*` matches `providers.is_current`.
- After CCS restart, config files are unchanged.
- Target apps are fully restarted before judging visibility.
- After any write, confirm the config text did not change beyond the intended edit (byte-level re-check).

## 8. Proactive preflight and known upstream defect (3.20.0–3.20.4)

- **Proactive preflight**: every mutating command (`provider-block` / `provider-env` / `mcp-upsert` / `prompt-set` / `skill-upsert` / `set-flags` / `common-config set|set-key|remove-key|extract` / `repair --apply`) runs a read-only structural audit first. If it finds empty-command stdio MCP servers, unpaired markers, misplaced/out-of-place table headers, or live-only sections, the write is refused with repair hints (`--force` overrides).
- **Known upstream defect**: CC Switch 3.20.0's provider edit page — even when saved without any changes — can reorder `config.toml`, strip common-config blocks, misplace markers, and serialize a url-only remote MCP as `type="stdio"` + `command=""` (frontend smol-toml round-trip plus backend toml_edit strip/merge). **Still not fixed as of 3.20.4**: upstream #6719 is open, and neither the 3.20.4 release notes nor its commits contain an edit-page fix — the warning covers 3.20.0–3.20.4. **Do not use the edit page to save or extract Codex provider config**; use this skill's commands instead.
- **Proxy-managed OAuth cards (3.20.2)**: for providers whose token is injected per request by the local proxy — `providers.meta.provider_type` = `xai_oauth` or `github_copilot` — the active `[model_providers.*]` table must carry `requires_openai_auth = false`; CCS 3.20.2 enforces this (presets emit `false`, existing cards self-heal on the next switch). Codex OAuth is deliberately excluded, because the official login *is* its credential. `check --strict` reports the wrong flag value for these cards instead of "no own credentials", and `repair --mode codex-0149 --apply` flips it to `false`.
- **Takeover derives the flag from the login state (3.20.2)**: when proxy takeover writes the active table, it resolves Codex's auth mode (explicit `auth_mode` > personal access token > Bedrock API key > Bedrock access key > `OPENAI_API_KEY` > ChatGPT) and then the credential store — `file` follows whether `auth.json` holds an official login, `ephemeral` is treated as logged out (`false`), and `keyring`/`auto` keep the stored value. A missing, unreadable or corrupt `auth.json` now counts as logged out instead of failing the takeover write.
  - Common symptoms: top-level `notify = [...]` displaced, `[plugins]` / `[marketplaces]` blocks stripped, `[mcp_servers]` / `[mcp_servers.node_repl(.env)]` blocks or keys rewritten or reordered.
- **Codex 0.149 config-only compatibility (routing rules aligned with 3.20.3)**: since CC Switch 3.20.1, third-party switching is config-only (key in `[model_providers.*]` as `experimental_bearer_token`, `auth.json` = official login only). `check --strict` detects 0.149-rejected or mis-routed shapes: legacy reserved tables `[model_providers.openai|ollama|lmstudio]`, missing `name`, a top-level `openai_base_url` reroute that actually targets the built-in `openai` provider (selector absent or exactly `openai`), a custom selector whose `[model_providers.<id>]` table is missing, empty/keyless third-party cards, and inline `model_providers = { ... }` declarations (recognized as real tables instead of being misreported as empty). `repair --mode codex-0149` renames reserved tables (and follows the rename with `model_provider` when that table carries the route's own key), backfills `name`, and migrates the `openai_base_url` reroute into the same shape CCS 3.20.3 writes — `[model_providers.cc-switch(-N)]` with `model_provider` pointing at it, `wire_api = "responses"`, `base_url` and the bearer token. A user-authored `cc-switch` table is never overwritten; keyless shapes are reported, not fabricated.
- **Codex cards without `model_provider` (3.20.3)**: takeover now treats a missing selector as the built-in `openai` provider, writes the proxy address to `openai_base_url`, and the shared normalization step rewrites it into `[model_providers.cc-switch(-N)]` with a `PROXY_MANAGED` bearer — previously the address was written to a top-level `base_url` Codex never reads, so the request silently went to `api.openai.com`. Direct (non-takeover) switches still follow the card as-is; that difference is what `check --strict` reports.
- **3.20.3 upgrade checklist**: no database migration (schema stays v18). Universal-provider sync now preserves child settings, but children whose `meta` was wiped by an earlier sync (usage script, common-config opt-out, endpoint auto-select, sort order) must be re-entered — re-check `common-config status`. The Claude → Codex/Gemini/Grok cross-write of proxy retry/timeout values is stopped, but values already copied are not restored — review each app's proxy settings. Kimi's two Codex presets moved to native Responses and DeepSeek's `deepseek-flash` catalog entry gained vision: existing cards keep their snapshot, so change the upstream format / re-import the preset, and switch away and back for catalog changes.
- **Stored Codex API keys (3.20.4)**: CCS 3.20.4 fixed the bug that wiped a saved Codex API key when editing or switching a provider (#7434), but keys already lost are not restored. Cards damaged by it keep the bearer token in the provider text while `settings_config.auth.OPENAI_API_KEY` is empty — `check --strict` / `doctor --audit` report that shape, and `repair --target provider --mode codex-key --apply` restores the key from the provider table (dry-run first; official and proxy-managed OAuth cards are skipped because they are keyless by design). If neither place holds a token, re-enter the key in CCS.
- **MiniMax Code (3.20.4)**: the 10th managed app. Additive providers in `~/.minimax/config.yaml` (`custom_provider`), MCP ↔ `~/.minimax/mcp.json`, skills → `~/.minimax/skills` (Pi-style ownership check), prompts → `~/.minimax/AGENTS.md` (≤32 KiB per prompt). Default model, login, cloud features and session deletion stay with MiniMax Code; CCS adds no proxy takeover/failover/tray/common-config/Profiles. Existing MCP servers and skills are disabled for mcode until you pass `--enable-mcode` / `set-flags --mcode 1`.
- **3.20.4 upgrade checklist**: database migration v18 → v19 (back up before upgrading; older CCS versions then refuse the DB). Cards bound to a deleted ChatGPT account must be re-bound manually before takeover can be enabled again; the "hide AI attribution" toggle must be re-checked (it now also requires `attribution.sessionUrl = false`); AICodeWith Codex cards need their endpoint changed to `/v1`; DeepSeek V4 Pro pricing went back to the peak tier and `Ling-2.6-1T` is treated as text-only; Chat-upstream requests take one prefix-cache miss after upgrade (#7454 / #7319) and then stabilise.
- **Codex desktop app still needs `~/.codex/auth.json`**: some Codex builds (especially the desktop app / patched CLI) decide "logged in" by the *presence* of `auth.json`. Deleting it — the 3.20.1 config-only ideal — can drop Codex back to the default login screen even when `experimental_bearer_token` is correctly written into `config.toml` (a commented-out token means the file is present but inactive). CCS 3.20.2 fixed only the **takeover** variant of this trap; a **direct** third-party switch with "preserve official login" off still deletes `auth.json`. Keep `auth.json` (with `OPENAI_API_KEY`) and set `preserveCodexOfficialAuthOnSwitch = true` in `~/.cc-switch/settings.json` so CCS never deletes it during a third-party switch; the provider-table `experimental_bearer_token` remains the stored 3.20.1+ shape in the DB.
- **Common-config maintenance**: `common-config` only modifies the snippet when explicitly invoked; `enable` requires an idempotence check (stripping the snippet and re-merging must stay semantically equivalent); `extract` auto-enables after success; `set*` asks whether to sync the current config and enable (non-interactive defaults to no sync unless `--sync-and-enable`).
- **Canonical "update both provider and common config" flow**: use `common-config set-key|set --apply --sync-and-enable` — it updates the snippet, strips duplicate snippet keys from the current provider config, and enables the flag in one step. Never hand-write temporary scripts to edit the CCS DB directly; DB writes go through `ccs_db.py`. Canonical state: the snippet owns the keys, the provider config does not duplicate them.
- **Scope disambiguation**: identify the sync object (configuration / skill files / template) yourself from context and pending changes — do not ask the user unless it is genuinely unresolvable. If the identified scope includes configuration, fall into the config-change iron rules below (provider-first, then ask about extracting to the template; preflight, backup/stop/validate/restart). Only touch the `common-config` snippet directly when the user explicitly says "common config" / "通用配置" / "模板"; never treat a sync of one object as a sync of a different object (e.g., skill files vs configuration, or vice versa).
- **Provider-first sync**: a config "sync" without an explicit scope updates the provider config via `provider-set-key`; after that, ask whether to `common-config extract` to the template.
- **Uncertainty handling**: when unsure, first re-read this skill (SKILL.md and its references) — do not improvise. If the request is outside this skill's scope, tell the user and propose recommended actions.

## References

- references/architecture.md — paths, tables, effect chain
- references/apps.md — the 9 managed apps matrix
- references/operations.md — copy-paste command templates (PowerShell + bash)
- references/pitfalls.md — known pitfalls
- references/migration.md — official CCS version behavior changes
- references/examples/ — sample TOML/JSON/prompt files

## Helper script

- scripts/ccs_db.py — portable CCS DB operations (UTF-8 safe). Subcommands: `mcp-upsert`, `prompt-set`, `skill-upsert`, `provider-block`, `provider-env`, `provider-set-key`, `set-flags`, `check` (`--strict`), `doctor` (`--audit` / `--compare-backup`), `snapshot`, `diff`, `repair` (header-order / live-only / codex-0149 / codex-key), `common-config`.