claude-switch-models-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Profiles and Local Skill Activation

Claude Code Profile 与本地 Skill 激活

Overview

概述

This skill creates an isolated-but-shared profile system for Claude Code CLI. Each profile gets its own

.claude.json

state file (credentials and session history) while sharing skills, projects, hook scripts, agents, and installed plugin state across all profiles — and converging each profile's

settings.json

(hook registration, marketplaces, env feature flags, permissions, preferences) plus the behavior slice of its
.claude.json
(e.g.

workflowSizeGuideline

) from the default profile, so the only intended difference between profiles is the model/provider.

The result: you can open one terminal with Kimi, another with DeepSeek, another with Anthropic — each running as a fully independent Claude Code process, without configuration bleed.

此Skill为Claude Code CLI创建了一套「隔离但共享」的Profile系统。每个Profile都有独立的

.claude.json

状态文件（存储凭证和会话历史），同时所有Profile共享Skill、项目、Hook脚本、Agent以及已安装的Plugin状态——并且每个Profile的

settings.json

（Hook注册、市场、环境特性开关、权限、偏好设置）以及

.claude.json

的行为配置片段（例如

workflowSizeGuideline

）都会从默认Profile同步收敛，因此各Profile之间唯一的预期差异就是模型/提供商。

这样一来，你可以在一个终端打开Kimi，另一个打开DeepSeek，再一个打开Anthropic——每个都作为完全独立的Claude Code进程运行，不会出现配置串扰。

How It Works

工作原理

```
CLAUDE_CONFIG_DIR
```
tells Claude Code CLI which directory to use as its config root.
Each profile lives in
```
~/.claude-profiles/<name>/
```
with an isolated
```
.claude.json
```
.
Content directories (
```
skills/
```
,
```
projects/
```
,
```
hooks/
```
,
```
agents/
```
,
```
settings/
```
) are symlinked back to the main
```
~/.claude/
```
directory so you only maintain one copy. Note this shares hook scripts, not hook registration — registration lives in each profile's own
```
settings.json
```
(next bullet).
Config layer —
settings.json
: each profile has its own
```
settings.json
```
(Claude Code treats it as config-dir-local), so everything stored there — hook registration,
```
extraKnownMarketplaces
```
,
```
enabledPlugins
```
,
```
env
```
feature flags,
```
permissions
```
, behavior preferences — silently drifts the moment it changes in the default profile (measured 2026-07-18: 9/9 real profiles had zero hook registrations).
```
sync-profile-settings.py
```
is the converger: registered as a SessionStart hook, it copies every key from the default profile's
```
settings.json
```
into the active profile's, except identity keys (top-level
```
model
```
and
```
advisorModel
```
— the latter is Anthropic-model routing a third-party endpoint can't serve; and env vars that carry provider routing or Anthropic-native isolation —
```
ANTHROPIC_*
```
,
```
CLAUDE_CODE_SUBAGENT_MODEL
```
,
```
ENABLE_TOOL_SEARCH
```
,
```
DISABLE_GROWTHBOOK/TELEMETRY/AUTOUPDATER
```
— which the provider settings file deliberately sets differently). Profile-only top-level keys are preserved; nested collections inside a key main also has (e.g.
```
permissions.allow
```
,
```
enabledPlugins
```
) converge wholesale to main's value, and any profile-only nested entries dropped that way are listed (count on write, detail under
```
--check
```
) so the loss is visible rather than silent. This is what makes "everything except the model works in every profile" actually hold.
State layer —
.claude.json
behavior keys:
```
settings.json
```
is not the only per-profile config file. Claude Code also keeps a per-profile state file (the main profile's is
```
~/.claude.json
```
; each third-party profile's is
```
<profile>/.claude.json
```
— asymmetric paths, verified on disk), and a few behavior settings live only there (
```
workflowSizeGuideline
```
, notification/UI preferences). On 2026-08-17
```
workflowSizeGuideline: small
```
existed only on the main profile and 10/11 third-party profiles had no copy — a Kimi session fanned one Dynamic Workflow out to 30+ agents with no size guidance in its system prompt. The same converger therefore also syncs an allowlist of behavior keys into each profile's
```
.claude.json
```
. The safety mechanism is a three-way classifier in the script, not a hand-maintained key list: allowlisted behavior keys sync; state/cache/counter/migration/credential keys (matched by name patterns) are never touched; anything unknown-and-different is reported — one line per drifted key per run, until a human classifies it (the tripwire that surfaces the next behavior key the day it appears). Writes are backup + atomic-replace; measured safe against a live harness rewriting the file (a marker key survived 30+ minutes of an active session). Applies next session — the harness reads this file at startup.
Exception —
plugins/
: marketplace content and install state are shared, but each profile keeps its own
```
known_marketplaces.json
```
. Claude validates a marketplace's
```
installLocation
```
with
```
path.resolve()
```
(which does NOT resolve symlinks), so a single shared file would make every non-writing profile report "corrupted installLocation".
```
claude-plugins-sync.py
```
builds and maintains this per-profile structure.
```
claude-plugins-sync.py
```
also mirrors
```
enabledPlugins
```
from the default
```
~/.claude/settings.json
```
into each profile's
```
settings.json
```
(sharing cache files is not enough; Claude Code treats "enabled" state as config-dir-local). It runs at profile launch and reactively — the LaunchAgent in the next bullet re-runs it on every write to the default profile's
```
settings.json
```
, so
```
claude plugin enable
```
/
```
disable --scope user
```
typically propagates to every profile within seconds without a relaunch (verified 2026-08-22). The mirror adopts first: enabledPlugins keys that exist only in some profile's settings.json (the way
```
claude plugin install
```
writes them) are written back into the default profile before mirroring — consistent values only; cross-profile conflicts stay per-profile behind a standing warning instead of being silently overwritten (added 2026-09-03, after adopt-less mirroring was confirmed as the mechanical root cause of recurring skill-visibility losses). The SessionStart converger above covers the same key as part of its whole-settings sync;
```
claude-plugins-sync.py
```
remains the owner of the per-profile
```
known_marketplaces.json
```
structure.
```
skill-install-audit.py
```
reconciles the registry / installed / enabled / Codex-manifest /
```
~/.agents/skills
```
layers read-only, plus the daemon's pinned runtime version and whether the checkouts it judged everything against are themselves behind.
```
prune-source-sync-backups.py
```
removes only the
```
.source-sync-backups/
```
buckets git can reproduce; a bucket holding even one blob no repository has is reported and left alone.
Local source sync keeps approved source-backed routes aligned for each host. Before selecting or repairing entries, read the host-specific activation contract. It owns the manifest fields, marketplace expansion, Claude plugin/direct-link distinction, unresolved-name handling, collision safety, and legacy compatibility. Source registration alone does not choose activation policy; do not hand-create links or repurpose the manifest to manage third-party inventory.
Sync scripts use a shared cross-process lock. This is required because users often open several provider windows from tmux or multiple terminals at once; concurrent launches must serialize marketplace/cache rewrites while still allowing all profiles to start.
For the full local-source architecture, read
```
references/local-source-sync-architecture.md
```
before changing these scripts.

Provider routing is done via

~/.claude/settings/<name>.json

, which sets

ANTHROPIC_MODEL

ANTHROPIC_BASE_URL

, and

ANTHROPIC_AUTH_TOKEN

for that window.

```
CLAUDE_CONFIG_DIR
```
用于指定Claude Code CLI的配置根目录。
每个Profile存放在
```
~/.claude-profiles/<name>/
```
目录下，拥有独立的
```
.claude.json
```
。
内容目录（
```
skills/
```
、
```
projects/
```
、
```
hooks/
```
、
```
agents/
```
、
```
settings/
```
）通过符号链接（symlink）指向主
```
~/.claude/
```
目录，因此只需维护一份副本。注意，这里共享的是Hook脚本，而非Hook注册——注册信息存放在每个Profile自己的
```
settings.json
```
中（见下一条）。
配置层 —
settings.json
：每个Profile都有自己的
```
settings.json
```
（Claude Code将其视为配置目录本地文件），因此其中存储的所有内容——Hook注册、
```
extraKnownMarketplaces
```
、
```
enabledPlugins
```
、
```
env
```
特性开关、
```
permissions
```
、行为偏好——都会在默认Profile发生变更时悄然漂移（2026-07-18实测：9个真实Profile的Hook注册数均为0）。
```
sync-profile-settings.py
```
是收敛工具：它被注册为SessionStart Hook，会将默认Profile
```
settings.json
```
中的所有键复制到当前活动Profile中，但身份类键除外（顶层的
```
model
```
和
```
advisorModel
```
——后者是Anthropic模型路由，第三方端点无法提供；以及承载提供商路由或Anthropic原生隔离功能的环境变量——
```
ANTHROPIC_*
```
、
```
CLAUDE_CODE_SUBAGENT_MODEL
```
、
```
ENABLE_TOOL_SEARCH
```
、
```
DISABLE_GROWTHBOOK/TELEMETRY/AUTOUPDATER
```
——这些是提供商设置文件特意设置为不同的）。仅属于单个Profile的顶层键会被保留；默认Profile中也存在的键下的嵌套集合（例如
```
permissions.allow
```
、
```
enabledPlugins
```
）会完全同步为默认值，因此被移除的仅属于单个Profile的嵌套条目会被列出（写入时统计数量，
```
--check
```
参数下显示详情），确保配置丢失是可见的而非静默发生的。这就是「除了模型之外的所有功能在每个Profile中都可用」的实现基础。
状态层 —
.claude.json
行为键：
```
settings.json
```
不是唯一的按Profile配置的文件。Claude Code还会为每个Profile维护一个状态文件（主Profile的状态文件是
```
~/.claude.json
```
；每个第三方Profile的是
```
<profile>/.claude.json
```
——路径不对称，已在磁盘上验证），并且有一些行为设置仅存放在这里（
```
workflowSizeGuideline
```
、通知/UI偏好）。2026-08-17发现，
```
workflowSizeGuideline: small
```
仅存在于主Profile中，10/11的第三方Profile都没有该配置——导致一个Kimi会话将一个动态工作流（Dynamic Workflow）拆分为30多个Agent，而系统提示中没有大小限制指导。因此，同一个收敛工具还会将行为键白名单同步到每个Profile的
```
.claude.json
```
中。安全机制是脚本中的三元分类器，而非人工维护的键列表：白名单内的行为键会同步；状态/缓存/计数器/迁移/凭证类键（通过名称模式匹配）则完全不会触碰；任何未知且存在差异的键会被报告——每次运行每个漂移键输出一行，直到人工分类（这是一个触发机制，能在新的行为键出现的当天就发现它）。写入操作采用备份+原子替换的方式；经实测，在运行中的进程持续改写文件的情况下也是安全的（一个标记键在活跃会话中存活了30多分钟）。配置会在下一次会话生效——进程会在启动时读取该文件。
例外 —
plugins/
目录：市场内容和安装状态是共享的，但每个Profile保留自己的
```
known_marketplaces.json
```
。Claude使用
```
path.resolve()
```
验证市场的
```
installLocation
```
（该函数不会解析符号链接），因此如果使用单个共享文件，所有非写入Profile都会报告「installLocation损坏」。
```
claude-plugins-sync.py
```
负责构建和维护这种按Profile划分的结构。
```
claude-plugins-sync.py
```
还会将默认
```
~/.claude/settings.json
```
中的
```
enabledPlugins
```
镜像到每个Profile的
```
settings.json
```
中（仅共享缓存文件是不够的；Claude Code将「启用」状态视为配置目录本地属性）。它会在Profile启动时运行，并且支持响应式更新——下一条中的LaunchAgent会在默认Profile的
```
settings.json
```
每次被写入时重新运行该脚本，因此
```
claude plugin enable
```
/
```
disable --scope user
```
通常会在几秒钟内传播到所有Profile，无需重启（2026-08-22验证）。镜像采用先采纳再同步的策略：仅存在于某个Profile的settings.json中的enabledPlugins键（
```
claude plugin install
```
的写入方式）会先被写回默认Profile，然后再进行镜像——仅同步一致的值；跨Profile冲突会保留各Profile的设置并给出持续警告，而非静默覆盖（2026-09-03新增，此前已确认无采纳的镜像是导致Skill可见性反复丢失的直接根本原因）。上文提到的SessionStart收敛工具作为全设置同步的一部分也会处理同一个键；但
```
claude-plugins-sync.py
```
仍然是按Profile划分的
```
known_marketplaces.json
```
结构的负责模块。
```
skill-install-audit.py
```
以只读方式核对注册表/已安装/已启用/Codex清单/
```
~/.agents/skills
```
各层的一致性，同时检查守护进程的固定运行时版本，以及它用来做判断的代码检出版本本身是否落后。
```
prune-source-sync-backups.py
```
仅删除Git可以重新生成的
```
.source-sync-backups/
```
存储桶；如果某个存储桶中哪怕只有一个blob是任何仓库都没有的，就会报告并保留该存储桶。
本地源码同步会为每台主机保持已批准的源码支撑路由的一致性。在选择或修复条目之前，请阅读主机特定激活契约。该文档负责清单字段、市场扩展、Claude Plugin/直接链接的区分、未解析名称处理、冲突安全机制以及旧版兼容性。仅源码注册并不会选择激活策略；请勿手动创建链接或将清单挪作管理第三方库存之用。
同步脚本使用共享的跨进程锁。这是必要的，因为用户经常从tmux或多个终端同时打开多个提供商窗口；并发启动时必须串行化市场/缓存的重写操作，同时还要保证所有Profile都能启动。
如需了解完整的本地源码架构，请在修改这些脚本之前阅读
```
references/local-source-sync-architecture.md
```
。

提供商设置通过

~/.claude/settings/<name>.json

配置，该文件会为对应窗口设置

ANTHROPIC_MODEL

、

ANTHROPIC_BASE_URL

和

ANTHROPIC_AUTH_TOKEN

。

One-Click Setup Workflow

一键设置工作流

When the user says something like "set up Claude Code profiles" or "I want to use Kimi and DeepSeek in different windows":

Check prerequisites
- ```
claude
```
  CLI is installed:
```
which claude
```
- Shell is zsh or bash: detect via
```
$SHELL
```
- ```
python3
```
  is available
Install the profile manager scripts — symlink them, do not copy

On a machine that has this repo checked out (the maintainer case), run the bundled installer:
bash
```
<absolute-path-to-this-repo>/daymade-claude-code/claude-switch-models-setup/scripts/setup.sh
```
```
scripts/setup.sh
```
is the single source for the exact deployment set. It links each helper into
```
~/.config/claude-switch-models-setup/
```
and seeds the activation manifest only when it does not already exist. Do not maintain another helper list here. No
```
chmod
```
step is needed: the deployment is by symlink, and the source files retain their committed modes.
Why symlinks and not
cp
:
```
~/.config/…
```
is what actually runs — the LaunchAgent and
```
claude-profile
```
invoke scripts by that path — while this repo holds their source. Copies drift, and nothing about a deployed copy looks different from its source, so "am I editing the SSOT?" is not a judgement anyone reliably makes. Measured on one machine before the switch: a lock-placement fix sat in the repo for 26 days while the deployed copy kept running the bug it fixed, and two cleanup routines written straight into the deployed copy never reached version control at all — drift in both directions, silently. A link removes both, for as long as it stays a link — an atomic-save editor, an
```
rsync
```
or a stray
```
cp
```
turns one back into a real file without saying so, which is why this is worth re-checking rather than declaring solved. It also lets
```
sync-local-skill-sources.py
```
locate its own source repo by resolving its own path, instead of falling back to guessing.
Worth re-checking how? Any periodic check works; there is none bundled with this skill. One line, run wherever you keep such things:
bash
```
for f in ~/.config/claude-switch-models-setup/*.py ~/.config/claude-switch-models-setup/*.sh; do
  [ -L "$f" ] && [ -e "$f" ] || echo "not a live link: $f"
done
```
If one has become a real file, move it aside before re-linking — it may hold edits that exist nowhere else, which is the whole problem being described:
```
mv "$f" "$f.local-edits" && ln -sf <source> "$f"
```
, then diff.
On a machine without the repo, copy the scripts listed by the installer out of this skill bundle instead — and accept that repo fixes will not reach it until you copy again.
On a machine whose LaunchAgent runs the pinned plugin copy (the maintainer layout described in local-source-sync-architecture.md), these same links point at that copy's version directory under
```
.../plugins/cache/...
```
, not at the checkout, and move only when the pin is advanced (troubleshooting.md, "advance the pin"). The installer refuses to relink such a machine to the checkout (
```
CSMS_SETUP_RELINK_TO_CHECKOUT=1
```
overrides), because the daemon and
```
claude-profile
```
would then follow whatever branch the checkout sits on. The live-link check above applies to both layouts.
Add shell integration
- Source the profile manager in
```
~/.zshrc
```
  or
```
~/.bashrc
```
- Add aliases:
```
csk
```
  ,
```
csks
```
  ,
```
csd
```
  ,
```
csg
```
  ,
```
css
```
- Add any further per-account/per-plan variant alias by hand if needed —
```
claude-profiles.sh
```
  only defines the aliases listed above
- Tell the user to run
```
source ~/.zshrc
```
  (or open a new terminal)
Generate provider settings files
- For each provider the user wants, create
```
~/.claude/settings/<provider>.json
```
- Use the templates in
```
assets/templates/
```
  as a starting point
- Prompt the user for their API key and base URL; never hardcode defaults
- Set the context window correctly for this specific provider —
```
[1m]
```
  suffix vs explicit
```
CLAUDE_CODE_MAX_CONTEXT_TOKENS
```
  /
```
CLAUDE_CODE_AUTO_COMPACT_WINDOW
```
  , see "Configuring Context Window Size" below. Do this explicitly for every new profile rather than copying whatever the nearest template happens to already have — the nearest template not needing it is not evidence that this one doesn't either.
- Include the required isolation flags:
  - ```
  CLAUDE_CODE_SUBAGENT_MODEL
```
  (same as
```
  ANTHROPIC_MODEL
```
  )
- ```
ENABLE_TOOL_SEARCH: "false"
```
  - ```
  DISABLE_GROWTHBOOK: "1"
```
- ```
DISABLE_TELEMETRY: "1"
```
  - ```
  DISABLE_AUTOUPDATER: "1"
```
Initialize profile directories
- Run
```
claude-profiles-init
```
- This creates
```
~/.claude-profiles/<provider>/
```
  with isolated
```
.claude.json
```
  and symlinks
- On maintainer machines, this also repairs local source symlinks before syncing plugin metadata
Statusline wiring:
```
claude-profiles-init
```
auto-detects a statusline script from
```
~/.claude/settings.json
```
or
```
~/.claude/statusline.sh
```
and injects it into each new profile. If neither is present, profiles will work but without a status bar. It is the AI's job to decide whether the user needs a statusline, install the
```
statusline-generator
```
skill if appropriate, and run its installer — not the profile setup script. Do not hardcode dependency installs into shell scripts.
Register the settings converger
- Add the converger as a SessionStart hook in the default profile's
```
~/.claude/settings.json
```
```
hooks.SessionStart
```
  list, using an absolute direct-Python command such as
```
'/absolute/path/to/python3' '/absolute/path/to/sync-profile-settings.py'
```
  . Do not register the
```
.py
```
  file by shebang or through a package manager: this hook exists to repair every profile and must not wait on a shared environment/cache lock. It no-ops when the active profile IS the default; its job there is to propagate into every profile's own
```
hooks
```
  key on the first sync.
- Run the initial alignment:
```
python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all
```
- From then on every profile converges its
```
settings.json
```
  and the behavior slice of its
```
.claude.json
```
  from the default profile at each session start (changes apply next session). Audit without writing:
```
--check --all
```
Verify isolation
- Run
```
claude-profiles-doctor
```
- Confirm each profile directory has
```
.claude.json
```
  and valid symlinks
Select local source Skills for Codex and Claude
- Skip this for normal students or users who do not edit the skill source repos
- Read the host-specific activation contract, then edit the machine's activation manifest for the requested hosts. Use its compatibility rules only for consumers that still retain a legacy path.
- Preview with
```
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py
```
  , read every affected path, then apply with
```
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py --apply
```
  .
- On a maintainer macOS machine, run
```
~/.config/claude-switch-models-setup/sync-local-skill-sources-daemon.sh --install
```
- This watches the activation manifest, default Claude install state, and local marketplace manifests, then repairs derived state after selection, install/uninstall, or plugin topology changes
Show the user how to launch
- ```
csk
```
  → Kimi K3 window
- ```
csks
```
  → Kimi K2.7 highspeed window
- ```
csd
```
  → DeepSeek window
- ```
csg
```
  → GLM window
- ```
css
```
  → StepFun window
- ```
claude
```
  (no alias) → default Anthropic profile
- Optional: hand-add a per-account/per-plan variant alias yourself, e.g.
```
alias cssp='claude-profile step-pay --dangerously-skip-permissions'
```
  —
```
claude-profiles.sh
```
  does not generate this; it is a manual pattern on top

当用户说「设置Claude Code Profile」或「我想在不同窗口使用Kimi和DeepSeek」之类的话时：

检查前置条件
- 已安装
```
claude
```
  CLI：执行
```
which claude
```
- Shell为zsh或bash：通过
```
$SHELL
```
  检测
- 可用
```
python3
```
安装Profile管理脚本——使用符号链接，不要复制

在已检出此仓库的机器上（维护者场景），运行捆绑的安装程序：
bash
```
<absolute-path-to-this-repo>/daymade-claude-code/claude-switch-models-setup/scripts/setup.sh
```
```
scripts/setup.sh
```
是确切部署集的唯一来源。它会将每个辅助工具链接到
```
~/.config/claude-switch-models-setup/
```
，并且仅在激活清单不存在时才初始化它。请勿在此处维护其他辅助工具列表。无需
```
chmod
```
步骤：部署通过符号链接完成，源文件保留其提交时的权限模式。
为什么用符号链接而不是
cp
：实际运行的是
```
~/.config/…
```
中的文件——LaunchAgent和
```
claude-profile
```
通过该路径调用脚本——而此仓库是它们的源码。副本会发生漂移，而且已部署副本和源码看起来没有区别，因此「我编辑的是唯一真实来源（SSOT）吗？」这个问题没人能可靠判断。在切换前的一台机器上实测：一个锁位置的修复在仓库中存在了26天，而已部署副本仍在运行它修复的那个bug，另外两个直接写在已部署副本中的清理例程根本没有进入版本控制——双向漂移，悄无声息。 符号链接消除了这两种漂移，只要它还是链接——原子保存的编辑器、
```
rsync
```
或是误操作的
```
cp
```
都可能把它变回真实文件而不给出提示，这就是为什么值得反复检查而不是宣称已经解决。这也让
```
sync-local-skill-sources.py
```
可以通过解析自身路径来定位自己的源码仓库，而不是退而求其次进行猜测。
怎么重新检查？任何定期检查都可以；此Skill没有捆绑检查脚本。一行命令，在你存放这类检查的地方运行即可：
bash
```
for f in ~/.config/claude-switch-models-setup/*.py ~/.config/claude-switch-models-setup/*.sh; do
  [ -L "$f" ] && [ -e "$f" ] || echo "not a live link: $f"
done
```
如果某个文件已经变成了真实文件，重新链接前先把它移到一边——它可能包含其他地方都没有的编辑内容，这正是我们要解决的问题：
```
mv "$f" "$f.local-edits" && ln -sf <source> "$f"
```
，然后进行diff对比。
在没有仓库的机器上，请从此Skill包中复制安装程序列出的脚本——并接受仓库的修复不会自动到达，直到你再次复制。
在LaunchAgent运行固定Plugin副本的机器上（local-source-sync-architecture.md中描述的维护者布局），这些链接指向
```
.../plugins/cache/...
```
下该副本的版本目录，而非检出的代码，并且仅在固定版本升级时才会移动（见troubleshooting.md的「升级固定版本」部分）。安装程序拒绝将此类机器重新链接到检出代码（
```
CSMS_SETUP_RELINK_TO_CHECKOUT=1
```
可覆盖此行为），因为守护进程和
```
claude-profile
```
会随之跟随检出代码所在的任何分支。上述的活动链接检查对两种布局都适用。
添加Shell集成
- 在
```
~/.zshrc
```
  或
```
~/.bashrc
```
  中引入Profile管理器
- 添加别名：
```
csk
```
  、
```
csks
```
  、
```
csd
```
  、
```
csg
```
  、
```
css
```
- 如有需要，可手动添加其他按账户/套餐划分的别名——
```
claude-profiles.sh
```
  仅定义上述别名
- 告知用户运行
```
source ~/.zshrc
```
  （或打开新终端）
生成提供商设置文件
- 为用户需要的每个提供商创建
```
~/.claude/settings/<provider>.json
```
- 以
```
assets/templates/
```
  中的模板为起点
- 向用户询问其API密钥和基础URL；绝对不要硬编码默认值
- 为该特定提供商正确设置上下文窗口——
```
[1m]
```
  后缀还是显式设置
```
CLAUDE_CODE_MAX_CONTEXT_TOKENS
```
  /
```
CLAUDE_CODE_AUTO_COMPACT_WINDOW
```
  ，见下文「配置上下文窗口大小」。请为每个新Profile显式配置，而不是直接复制最近的模板已有内容——最近的模板不需要不代表这个也不需要。
- 包含必需的隔离标志：
  - ```
  CLAUDE_CODE_SUBAGENT_MODEL
```
  （与
```
  ANTHROPIC_MODEL
```
  相同）
- ```
ENABLE_TOOL_SEARCH: "false"
```
  - ```
  DISABLE_GROWTHBOOK: "1"
```
- ```
DISABLE_TELEMETRY: "1"
```
  - ```
  DISABLE_AUTOUPDATER: "1"
```
初始化Profile目录
- 运行
```
claude-profiles-init
```
- 这会创建
```
~/.claude-profiles/<provider>/
```
  ，包含独立的
```
.claude.json
```
  和符号链接
- 在维护者机器上，这一步还会在同步Plugin元数据之前修复本地源码符号链接
状态栏集成：
```
claude-profiles-init
```
会自动从
```
~/.claude/settings.json
```
或
```
~/.claude/statusline.sh
```
检测状态栏脚本，并将其注入每个新Profile。如果两者都不存在，Profile仍可正常工作，但没有状态栏。决定用户是否需要状态栏、在合适时安装
statusline-generator
Skill并运行其安装程序是AI的工作——而非Profile设置脚本的职责。请勿在Shell脚本中硬编码依赖安装。
注册设置收敛工具
- 将收敛工具作为SessionStart Hook添加到默认Profile的
```
~/.claude/settings.json
```
  的
```
hooks.SessionStart
```
  列表中，使用绝对路径的直接Python命令，例如
```
'/absolute/path/to/python3' '/absolute/path/to/sync-profile-settings.py'
```
  。不要通过shebang或包管理器注册
```
.py
```
  文件：此Hook用于修复所有Profile，绝不能等待共享环境/缓存锁。当活动Profile就是默认Profile时，它会执行空操作；它在那里的作用是在第一次同步时将自身传播到每个Profile自己的
```
hooks
```
  键中。
- 运行初始对齐：
```
python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all
```
- 此后，每个Profile都会在每次会话启动时从默认Profile收敛其
```
settings.json
```
  和
```
.claude.json
```
  的行为片段（更改在下一次会话生效）。仅审计不写入：使用
```
--check --all
```
  参数
验证隔离性
- 运行
```
claude-profiles-doctor
```
- 确认每个Profile目录都有
```
.claude.json
```
  和有效的符号链接
为Codex和Claude选择本地源码Skill
- 普通学生或不编辑Skill源码仓库的用户可跳过此步
- 阅读主机特定激活契约，然后为请求的主机编辑机器的激活清单。仅对仍保留旧路径的使用者使用其兼容性规则。
- 使用
```
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py
```
  预览，检查所有受影响的路径，然后使用
```
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py --apply
```
  应用更改。
- 在维护者的macOS机器上，运行
```
~/.config/claude-switch-models-setup/sync-local-skill-sources-daemon.sh --install
```
- 这会监视激活清单、默认Claude安装状态和本地市场清单，然后在选择、安装/卸载或Plugin拓扑变化后修复派生状态
向用户展示如何启动
- ```
csk
```
  → Kimi K3窗口
- ```
csks
```
  → Kimi K2.7高速版窗口
- ```
csd
```
  → DeepSeek窗口
- ```
csg
```
  → GLM窗口
- ```
css
```
  → StepFun窗口
- ```
claude
```
  （无别名）→ 默认Anthropic Profile
- 可选：手动添加按账户/套餐划分的变体别名，例如
```
alias cssp='claude-profile step-pay --dangerously-skip-permissions'
```
  ——
```
claude-profiles.sh
```
  不会生成这个；这是一个上层的手动模式

Commands

命令

After setup, the user can run:

bash

claude-profiles-init          # Re-scan settings/*.json, create missing profiles;
                               # reports symlink drift (real dirs that should be symlinks).
                               # Add --repair to archive drift and replace with symlinks.
claude-profile <name>         # Launch a specific profile
claude-profiles-ls            # List profiles
claude-profiles-doctor        # Check symlink health
claude-profile-rm <name>      # Remove a profile's isolation directory
python3 ~/.config/claude-switch-models-setup/claude-plugins-sync.py
                               # Repair per-profile plugin structure and enabledPlugins
python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all
                               # Converge every profile from the default profile:
                               # settings.json (hooks, marketplaces, env flags,
                               # permissions, preferences) + .claude.json behavior
                               # keys (workflowSizeGuideline etc.); --check --all
                               # audits without writing
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py
                               # Maintainers: preview host selections and affected paths
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py --apply
                               # Apply the inspected Codex, Claude, and explicit
                               # legacy compatibility changes
~/.config/claude-switch-models-setup/sync-local-skill-sources-daemon.sh --install
                               # Maintainers: install automatic macOS watcher

These are not day-to-day commands. Normal source edits are live through symlinks. The one-shot commands are for repair, bootstrap, or non-macOS environments without the LaunchAgent watcher.

设置完成后，用户可以运行：

bash

claude-profiles-init          # 重新扫描settings/*.json，创建缺失的profile；
                               # 报告符号链接漂移（本应是符号链接的实际目录）。
                               # 添加--repair可归档漂移并替换为符号链接。
claude-profile <name>         # 启动指定的profile
claude-profiles-ls            # 列出所有profile
claude-profiles-doctor        # 检查符号链接健康状态
claude-profile-rm <name>      # 删除某个profile的隔离目录
python3 ~/.config/claude-switch-models-setup/claude-plugins-sync.py
                               # 修复按profile划分的plugin结构和enabledPlugins
python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all
                               # 从默认profile收敛所有profile：
                               # settings.json（hooks、市场、环境标志、
                               # 权限、偏好） + .claude.json行为
                               # 键（workflowSizeGuideline等）；--check --all
                               # 仅审计不写入
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py
                               # 维护者：预览主机选择和受影响路径
python3 ~/.config/claude-switch-models-setup/sync-local-skill-sources.py --apply
                               # 应用已检查的Codex、Claude和显式
                               # 旧版兼容性更改
~/.config/claude-switch-models-setup/sync-local-skill-sources-daemon.sh --install
                               # 维护者：安装自动macOS监视程序

这些不是日常使用的命令。常规的源码编辑会通过符号链接实时生效。这些一次性命令用于修复、引导，或是没有LaunchAgent监视程序的非macOS环境。

Provider Templates

提供商模板

Use the provider templates in

assets/templates/

. Read the chosen file for its model, endpoint, context settings, and thinking behavior; do not infer those values from a hand-maintained template summary.

Every template uses the

<API_KEY>

placeholder. Templates for configurable gateways also use

<BASE_URL>

; the MiniMax templates pin the documented regional endpoint. Ask the user for every real placeholder value; do not guess or reuse values from the current machine unless the user explicitly provides them.

请使用

assets/templates/

中的提供商模板。阅读所选文件以了解其模型、端点、上下文设置和思考行为；不要从人工维护的模板摘要中推断这些值。

每个模板都使用

<API_KEY>

占位符。可配置网关的模板还使用

<BASE_URL>

；MiniMax模板固定了文档中记载的区域端点。请向用户询问所有真实的占位符值；除非用户明确提供，否则不要猜测或复用当前机器上的值。

MiniMax model behavior

MiniMax模型行为

Templates	Model	Context configuration	Thinking behavior
`minimax.json` , `minimax-cn.json`	`MiniMax-M3`	Append `[1m]` to every routed model value and set `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to `1000000` .	Supports adaptive or disabled thinking. Keep `ANTHROPIC_REASONING_MODEL` on the same model.
`minimax-m2-7.json` , `minimax-m2-7-cn.json`	`MiniMax-M2.7`	Set `CLAUDE_CODE_MAX_CONTEXT_TOKENS` and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to `204800` ; do not append `[1m]` .	Thinking is always on; do not claim a template-level disable path.

模板	模型	上下文配置	思考行为
`minimax.json` 、 `minimax-cn.json`	`MiniMax-M3`	每个路由的模型值后追加 `[1m]` ，并将 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设置为 `1000000` 。	支持自适应或禁用思考。保持 `ANTHROPIC_REASONING_MODEL` 与该模型一致。
`minimax-m2-7.json` 、 `minimax-m2-7-cn.json`	`MiniMax-M2.7`	将 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 和 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设置为 `204800` ；不要追加 `[1m]` 。	思考始终开启；请勿声称存在模板级别的禁用路径。

Configuring Context Window Size

配置上下文窗口大小

Every provider template sets the model's context window one of two ways — get this wrong and Claude Code doesn't know how much context the model can actually hold. Undershoot and it compacts (summarizes, drops old detail) far earlier than the provider actually requires; overshoot and it won't compact until the real limit is already blown past.

The full client-side mechanism of the

[1m]

marker — what it strips off the model field, what it adds to the

anthropic-beta

header, and why a missing

[1m]

does not mean the provider can't hold a big prompt — is documented in

references/context-window-config.md

. Reach for it when a context number looks wrong, not at template-writing time.

每个提供商模板都通过两种方式之一设置模型的上下文窗口——配置错误的话，Claude Code将不知道模型实际能容纳多少上下文。设置过低，它会比提供商实际要求的早得多就进行压缩（总结、丢弃旧细节）；设置过高，它会直到超过真实限制后才会压缩。

[1m]

标记的完整客户端机制——它从模型字段中剥离什么、向

anthropic-beta

头中添加什么，以及为什么缺少

[1m]

不意味着提供商不能处理大提示——都记录在

references/context-window-config.md

中。当上下文数值看起来不对时再查阅该文档，而不是在编写模板时。

Decision rule

决策规则

When writing a new provider's

settings/<name>.json

, pick based on the provider's real, verified context window — not the model's marketing name, and not by copying whatever the nearest template happens to do:

Provider's real context window	What to set	Example template
~1M tokens, explicitly confirmed (not assumed from the model's tier/name)	`[1m]` suffix on every `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_*_MODEL` / `CLAUDE_CODE_SUBAGENT_MODEL` value. Must be the exact 4 characters `[1m]` — Claude Code matches this literal string, not a made-up marker like `[1million]` or `[max]` .	`kimi.json`
A known, smaller size (e.g. 200K)	Explicit `CLAUDE_CODE_MAX_CONTEXT_TOKENS` and/or `CLAUDE_CODE_AUTO_COMPACT_WINDOW` set to the real number — no `[1m]` .	`kimi-highspeed.json` ( `200000` )
Unknown / not yet verified	Don't guess, and don't copy another provider's number just because a template needs something there. Ask the user to check the provider's own docs/console first. An unverified `[1m]` or an unverified large `CLAUDE_CODE_AUTO_COMPACT_WINDOW` just moves the failure from "compacts too early" to "doesn't compact until well past the real limit" — worse, because it's silent until a request actually fails.

deepseek.json

and

glm.json

set both

[1m]

and an explicit

CLAUDE_CODE_AUTO_COMPACT_WINDOW: "1000000"

. That's belt-and-suspenders, not redundant filler to strip out — the exact precedence between the marker and the explicit override hasn't been independently reverse-engineered, so if you're copying one of those two templates, keep both rather than dropping one.

The MiniMax-M3 templates use the same 1M marker plus an explicit

auto-compact value. The MiniMax-M2.7 templates use explicit

limits with no marker.

The full step-2-16k template-correctness war-story (why an internally-consistent-looking context value is not the same as a currently-correct one — cross-check the model name against the provider's live docs, not just the numbers around it), plus a reusable recipe to verify whether any env var actually changes the bytes sent over the wire (a local

http.server

capture, since

--debug api

only shows internal state), live in

references/context-window-config.md

在编写新提供商的

settings/<name>.json

时，请根据提供商真实的、已验证的上下文窗口来选择——而不是根据模型的营销名称，也不是直接复制最近的模板的做法：

提供商的真实上下文窗口	设置内容	示例模板
约1M tokens，已明确确认（不是从模型的等级/名称推测）	每个 `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_*_MODEL` / `CLAUDE_CODE_SUBAGENT_MODEL` 值后加 `[1m]` 后缀。必须是精确的4个字符 `[1m]` ——Claude Code匹配的是这个字面字符串，而不是 `[1million]` 或 `[max]` 之类的自创标记。	`kimi.json`
已知的较小尺寸（例如200K）	显式设置 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 和/或 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 为真实数值——不加 `[1m]` 。	`kimi-highspeed.json` （ `200000` ）
未知 / 尚未验证	不要猜测，也不要因为模板需要某个值就复制另一个提供商的数值。请先让用户查看提供商自己的文档/控制台。未经验证的 `[1m]` 或未经验证的大 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 只会把故障从「压缩过早」转移到「超过真实限制很久才压缩」——更糟糕，因为在请求实际失败之前它是静默的。

deepseek.json

和

glm.json

同时设置了

[1m]

和显式的

CLAUDE_CODE_AUTO_COMPACT_WINDOW: "1000000"

。这是双保险，不是可以删掉的冗余内容——标记和显式覆盖之间的确切优先级尚未被独立逆向工程验证，因此如果你复制这两个模板之一，请同时保留两者，不要删掉其中一个。

MiniMax-M3模板使用相同的1M标记加上显式的

自动压缩值。MiniMax-M2.7模板使用显式的

限制，没有标记。

完整的step-2-16k模板正确性轶事（为什么看起来内部一致的上下文值不等于当前正确的值——要对照提供商的实时文档交叉检查模型名称，而不仅仅是周围的数字），以及一个可复用的方法来验证任何环境变量是否真的改变了通过网络发送的字节（本地

http.server

抓包，因为

--debug api

只显示内部状态），都记录在

references/context-window-config.md

中。

Common base URLs (verify with your provider)

常用基础URL（请与你的提供商确认）

Provider	Typical base URL
Kimi	`https://api.moonshot.cn` or OpenRouter-compatible endpoint
GLM	`https://open.bigmodel.cn/api/paas/v4` or OpenRouter-compatible endpoint
DeepSeek	`https://api.deepseek.com` or OpenRouter-compatible endpoint
StepFun	`https://api.stepfun.com` or OpenRouter-compatible endpoint
MiniMax	Global: `https://api.minimax.io/anthropic` ; China: `https://api.minimaxi.com/anthropic`
Anthropic	`https://api.anthropic.com`

Important: The exact endpoint depends on whether the user is calling the provider directly or through a compatibility gateway (e.g., OpenRouter). Always ask.

提供商	典型基础URL
Kimi	`https://api.moonshot.cn` 或兼容OpenRouter的端点
GLM	`https://open.bigmodel.cn/api/paas/v4` 或兼容OpenRouter的端点
DeepSeek	`https://api.deepseek.com` 或兼容OpenRouter的端点
StepFun	`https://api.stepfun.com` 或兼容OpenRouter的端点
MiniMax	全球： `https://api.minimax.io/anthropic` ；中国： `https://api.minimaxi.com/anthropic`
Anthropic	`https://api.anthropic.com`

重要提示： 确切的端点取决于用户是直接调用提供商还是通过兼容网关（例如OpenRouter）调用。务必询问用户。

Shared vs. Isolated

共享与隔离对比

Data	Location	Shared?
Session history	`~/.claude-profiles/<name>/.claude.json`	Isolated per profile
Auth tokens/cache	`~/.claude-profiles/<name>/.claude.json`	Isolated per profile
Skills	`~/.claude/skills/`	Shared via symlink
Plugin content	`~/.claude/plugins/marketplaces` , `cache` , `data` , ...	Shared via symlink
Plugin install registry	`~/.claude/plugins/installed_plugins.json`	Shared via symlink
Enabled plugin map	`~/.claude/settings.json` -> `<profile>/settings.json`	Converged by `sync-profile-settings.py` (also mirrored by `claude-plugins-sync.py` )
Plugin marketplace index	`<profile>/plugins/known_marketplaces.json`	Per-profile (installLocation is config-dir-specific; can't be shared)
Projects/memory	`~/.claude/projects/` , `~/.claude/memory/`	Shared via symlink
Hook scripts	`~/.claude/hooks/` , `~/.claude/commands/`	Shared via symlink (scripts only — NOT registration)
`settings.json` config: hook registration, marketplaces, env flags, permissions, preferences	`<profile>/settings.json`	Converged from default profile by `sync-profile-settings.py` at session start (identity keys like `model` and provider-routing/isolation env vars are never synced)
`.claude.json` behavior keys ( `workflowSizeGuideline` , notification/UI preferences)	`~/.claude.json` → `<profile>/.claude.json`	Behavior allowlist converged by the same script; state/cache/counter/migration/credential keys (incl. `projects` , `oauthAccount` , `userID` ) are never synced; unknown drifted keys are reported for human classification
Provider settings	`~/.claude/settings/<name>.json`	Shared source, loaded per profile

数据	位置	是否共享？
会话历史	`~/.claude-profiles/<name>/.claude.json`	按Profile隔离
认证令牌/缓存	`~/.claude-profiles/<name>/.claude.json`	按Profile隔离
Skill	`~/.claude/skills/`	通过符号链接共享
Plugin内容	`~/.claude/plugins/marketplaces` 、 `cache` 、 `data` 等	通过符号链接共享
Plugin安装注册表	`~/.claude/plugins/installed_plugins.json`	通过符号链接共享
已启用Plugin映射	`~/.claude/settings.json` → `<profile>/settings.json`	由 `sync-profile-settings.py` 收敛（也由 `claude-plugins-sync.py` 镜像）
Plugin市场索引	`<profile>/plugins/known_marketplaces.json`	按Profile独立（installLocation是配置目录特定的；无法共享）
项目/记忆	`~/.claude/projects/` 、 `~/.claude/memory/`	通过符号链接共享
Hook脚本	`~/.claude/hooks/` 、 `~/.claude/commands/`	通过符号链接共享（仅脚本——不包括注册）
`settings.json` 配置：Hook注册、市场、环境标志、权限、偏好	`<profile>/settings.json`	会话启动时由 `sync-profile-settings.py` 从默认Profile收敛（ `model` 等身份键和提供商路由/隔离环境变量永远不会同步）
`.claude.json` 行为键（ `workflowSizeGuideline` 、通知/UI偏好）	`~/.claude.json` → `<profile>/.claude.json`	由同一脚本收敛行为白名单；状态/缓存/计数器/迁移/凭证键（包括 `projects` 、 `oauthAccount` 、 `userID` ）永远不会同步；未知的漂移键会报告给人工分类
提供商设置	`~/.claude/settings/<name>.json`	源文件共享，按Profile加载

Troubleshooting

故障排查

A profile directory exists but claude-profiles-doctor reports it as an "orphan profile"

Profile目录存在，但claude-profiles-doctor报告为「孤立Profile」

Symptom:

claude-profiles-doctor

reports

WARN: orphan profile — no settings/<name>.json; claude-profile <name> fails. Run: claude-profile-rm <name>

Cause: the profile isolation directory exists under

~/.claude-profiles/

but the corresponding

~/.claude/settings/<name>.json

provider config file is missing.

claude-profiles-init

only scans

settings/*.json

, so an orphan profile's symlinks are never created or maintained, and

claude-profile <name>

will fail to launch with "Error: Settings file not found." The profile directory may still contain useful per-profile data (

history.jsonl

.claude.json

with provider credentials,

settings.json

, skill workspaces).

Fix:

If the profile is no longer needed:
```
claude-profile-rm <name>
```
— this safely removes the isolation directory (it checks for unexpected files first).
If you want to revive it: recreate the settings file at
```
~/.claude/settings/<name>.json
```
(use a provider template from
```
assets/templates/
```
), then run
```
claude-profiles-init
```
.

症状：

claude-profiles-doctor

报告

WARN: orphan profile — no settings/<name>.json; claude-profile <name> fails. Run: claude-profile-rm <name>

。

原因：

~/.claude-profiles/

下存在Profile隔离目录，但对应的

~/.claude/settings/<name>.json

提供商配置文件缺失。

claude-profiles-init

仅扫描

settings/*.json

，因此孤立Profile的符号链接永远不会被创建或维护，

claude-profile <name>

将启动失败并报错「Error: Settings file not found.」。该Profile目录可能仍包含有用的按Profile数据（

history.jsonl

、带有提供商凭证的

.claude.json

、

settings.json

、Skill工作区）。

解决方法：

如果不再需要该Profile：运行
```
claude-profile-rm <name>
```
——这会安全删除隔离目录（它会先检查是否有意外文件）。
如果想恢复它：在
```
~/.claude/settings/<name>.json
```
重新创建设置文件（使用
```
assets/templates/
```
中的提供商模板），然后运行
```
claude-profiles-init
```
。

A shared directory (skills/projects/hooks/agents/...) shows as a real directory, not a symlink

共享目录（skills/projects/hooks/agents/...）显示为实际目录而非符号链接

Symptom:

claude-profiles-doctor

reports

<name> is a real directory (expected symlink to ~/.claude/<name>) — drift; run: claude-profiles-init --repair

Cause: the profile was created before the symlink-convergence design landed (or was hand-created), so a shared content directory ended up as a real per-profile directory instead of a symlink. That profile's copy now silently diverges from the main

~/.claude/

copy — its skills/projects/hooks/agents are not the same as every other profile's. The broken-symlink check cannot see this (a real directory is not a broken link); on a real machine this drift went undetected for months until the dedicated real-directory check was added (2026-07-21: legacy profiles created before this check existed carried real

projects/

dirs for months, undetected).

Fix (reversible — data is archived, never deleted):

bash

claude-profiles-init --repair

For each drifted directory this archives the real dir to

<name>.pre-symlink-bak-<timestamp>

inside the profile directory, then creates the symlink that should have been there. Run

claude-profiles-doctor

again to confirm a clean bill. If an archive turns out to hold data you need, it is sitting right there — nothing was destroyed.

Note on what gets shared: after repair, that directory points at the main

~/.claude/<name>

copy, so the profile sees the same skills/projects/etc. as the default profile — which is the entire point of the shared-symlink design. The per-profile state that must stay isolated (

.claude.json

settings.json

identity keys like

model

/provider env,

plugins/known_marketplaces.json

) is never one of these symlinked dirs, so repair never touches it. Inspect the archive before discarding it if the profile held session/history data you care about — those would now resolve to the shared copy.

症状：

claude-profiles-doctor

报告

<name> is a real directory (expected symlink to ~/.claude/<name>) — drift; run: claude-profiles-init --repair

。

原因：该Profile是在符号链接收敛设计落地之前创建的（或是手动创建的），因此共享内容目录最终变成了按Profile划分的实际目录，而非符号链接。该Profile的副本现在与主

~/.claude/

副本悄然偏离——它的Skill/项目/Hook/Agent与其他所有Profile都不一样。损坏符号链接检查无法发现这一点（实际目录不是损坏的链接）；在一台真实机器上，这种漂移在几个月内都未被发现，直到添加了专门的实际目录检查（2026-07-21：在此检查存在之前创建的旧版Profile携带实际的

projects/

目录长达数月，未被发现）。

解决方法（可逆——数据会被归档，绝不会删除）：

bash

claude-profiles-init --repair

对于每个漂移的目录，它会将实际目录归档到Profile目录内的

<name>.pre-symlink-bak-<timestamp>

，然后创建本应存在的符号链接。再次运行

claude-profiles-doctor

确认状态正常。如果归档中确实包含你需要的数据，它就在那里——没有任何内容被销毁。

关于共享内容的说明：修复后，该目录指向主

~/.claude/<name>

副本，因此该Profile看到的Skill/项目等与默认Profile相同——这正是共享符号链接设计的全部意义。必须保持隔离的按Profile状态（

.claude.json

、

settings.json

中的

model

/提供商环境等身份键、

plugins/known_marketplaces.json

）永远不会是这些符号链接目录之一，因此修复绝不会触碰它们。如果该Profile包含你关心的会话/历史数据，请在丢弃归档前检查——这些数据现在会解析到共享副本。

Marketplace says "corrupted installLocation"

市场提示「corrupted installLocation」

Symptom:

/plugin

claude plugin marketplace update

reports

corrupted installLocation ... expected a path inside <config-dir>/plugins/marketplaces

Cause:

known_marketplaces.json

ended up shared across profiles (or hand-edited). Its

installLocation

is config-dir-specific because Claude validates with

path.resolve()

(symlinks NOT resolved), so one shared copy cannot satisfy multiple profiles.

Fix:

claude-plugins-sync.py

rebuilds each profile's own copy + the shared-content symlinks. It runs automatically at

claude-profile

init/launch; to run manually:

bash

python3 ~/.config/claude-switch-models-setup/claude-plugins-sync.py

症状：

/plugin

或

claude plugin marketplace update

报告

corrupted installLocation ... expected a path inside <config-dir>/plugins/marketplaces

。

原因：

known_marketplaces.json

被跨Profile共享了（或是被手动编辑过）。它的

installLocation

是配置目录特定的，因为Claude使用

path.resolve()

进行验证（不会解析符号链接），因此单个共享副本无法满足多个Profile的需求。

解决方法：

claude-plugins-sync.py

会重建每个Profile自己的副本以及共享内容符号链接。它会在

claude-profile

初始化/启动时自动运行；手动运行方式：

bash

python3 ~/.config/claude-switch-models-setup/claude-plugins-sync.py

Skill exists in default Claude but is missing in Kimi/GLM/DeepSeek

默认Claude中存在的Skill在Kimi/GLM/DeepSeek中缺失

Symptom: the default Anthropic profile can see a skill, but a third-party profile cannot.

Cause: Claude Code stores

enabledPlugins

in each config directory's

settings.json

. Sharing

plugins/cache

only makes files available; it does not enable them.

Fix:

bash

python3 ~/.config/claude-switch-models-setup/claude-plugins-sync.py

Then restart the affected Claude Code window.

症状：默认Anthropic Profile可以看到某个Skill，但第三方Profile看不到。

原因：Claude Code将

enabledPlugins

存储在每个配置目录的

settings.json

中。共享

plugins/cache

只是让文件可用；并不会启用它们。

解决方法：

bash

python3 ~/.config/claude-switch-models-setup/claude-plugins-sync.py

然后重启受影响的Claude Code窗口。

Local source edits do not show up in Claude Code or Codex

本地源码编辑未在Claude Code或Codex中生效

Read the source-change and pin-update procedure. It distinguishes source-backed routes from pinned runtime copies and inventory reports from successful synchronization and fresh-host discovery.

Source sync also manages derived cache artifacts:

Version-alias symlinks. Each cache link is named after the marketplace's current version, so every version bump left the previous link behind pointing at the very same source directory. The pass now removes sibling links that resolve to the same source; real directories are never touched, since Claude Code installs those and a live session may still hold them through
```
.in_use
```
.
installed_plugins.json
backups. Each run that changes the JSON writes a backup. The
```
KEEP_JSON_BACKUPS
```
constant in the script caps the retained set; the names end in a
```
YYYYMMDD-HHMMSS
```
stamp, so lexical order is chronological.

Both are visible in a dry run before

--apply

touches anything.

请阅读源码变更和固定版本更新流程。它区分了源码支撑路由与固定运行时副本，以及库存报告与成功同步和新主机发现。

源码同步还管理派生的缓存工件：

版本别名符号链接。 每个缓存链接都以市场的当前版本命名，因此每次版本升级都会留下指向上一个相同源码目录的链接。现在该流程会删除解析到同一源码的兄弟链接；实际目录绝不会被触碰，因为这些是Claude Code安装的，并且活跃会话可能仍通过
```
.in_use
```
持有它们。
installed_plugins.json
备份。每次更改JSON的运行都会写入备份。脚本中的
```
KEEP_JSON_BACKUPS
```
常量限制了保留的数量；文件名以
```
YYYYMMDD-HHMMSS
```
时间戳结尾，因此字典序就是时间顺序。

在

--apply

执行任何操作之前，这两项都会在试运行中显示。

A profile is missing hooks, marketplaces, env flags, or other default-profile settings

Profile缺少Hook、市场、环境标志或其他默认Profile设置

Symptom: the default profile has hook guards, marketplaces, or feature flags configured, but a third-party profile behaves as if they don't exist (no PreToolUse guards fire,

claude plugin marketplace list

is empty, a feature enabled in the default profile is off).

Sibling symptom, different layer (2026-08-17): a behavior preference set on the default profile — e.g. the workflow size guideline — has no effect in third-party profiles (a Kimi session fanned a Dynamic Workflow out to 30+ agents despite

small

being set on main). That key lives in the per-profile

.claude.json

, which symlinks and the settings.json sync both miss. See "Default-profile behavior settings don't reach third-party profiles" in

references/troubleshooting.md

Cause: those live in each profile's own

settings.json

, which is config-dir-local — symlinking directories does not cover the config layer, and it drifts silently the moment the default profile changes.

Fix:

bash

python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all

Then restart the affected window. Once the converger is registered as a SessionStart hook (setup step 6), every profile self-converges at session start, so this should only be needed after a manual settings edit you want propagated immediately.

症状：默认Profile配置了Hook防护、市场或特性开关，但第三方Profile的表现就像它们不存在一样（PreToolUse防护不触发、

claude plugin marketplace list

为空、默认Profile中启用的特性处于关闭状态）。

同类症状，不同层级（2026-08-17）： 在默认Profile上设置的行为偏好——例如工作流大小指南——在第三方Profile中不起作用（尽管主Profile设置了

small

，一个Kimi会话仍将动态工作流拆分为30多个Agent）。该键存在于按Profile划分的

.claude.json

中，符号链接和settings.json同步都会漏掉它。请参阅

references/troubleshooting.md

中的「默认Profile行为设置未同步到第三方Profile」。

原因：这些设置存放在每个Profile自己的

settings.json

中，该文件是配置目录本地的——目录符号链接不覆盖配置层，因此默认Profile一旦变更，它就会悄然漂移。

解决方法：

bash

python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all

然后重启受影响的窗口。一旦收敛工具被注册为SessionStart Hook（设置步骤6），每个Profile都会在会话启动时自动收敛，因此仅在你手动编辑了设置并希望立即传播时才需要这样做。

Third-party profile tries to use Anthropic-specific features

第三方Profile尝试使用Anthropic专属特性

Symptom: WebSearch or other Anthropic-native tools fail with 400 errors. Fix: Ensure the profile's

settings.json

sets:

json

{
  "env": {
    "ENABLE_TOOL_SEARCH": "false",
    "DISABLE_GROWTHBOOK": "1",
    "DISABLE_TELEMETRY": "1",
    "DISABLE_AUTOUPDATER": "1"
  }
}

症状：WebSearch或其他Anthropic原生工具失败并报400错误。

解决方法：确保该Profile的

settings.json

设置了：

json

{
  "env": {
    "ENABLE_TOOL_SEARCH": "false",
    "DISABLE_GROWTHBOOK": "1",
    "DISABLE_TELEMETRY": "1",
    "DISABLE_AUTOUPDATER": "1"
  }
}

Subagent calls fall back to a different model

Subagent调用回退到不同的模型

Symptom: Subagents inside a Kimi window call

claude-opus-4-7

. Fix: Set

CLAUDE_CODE_SUBAGENT_MODEL

to the same value as

ANTHROPIC_MODEL

in the profile's

settings.json

症状：Kimi窗口中的Subagent调用

claude-opus-4-7

。

解决方法：在该Profile的

settings.json

中将

CLAUDE_CODE_SUBAGENT_MODEL

设置为与

ANTHROPIC_MODEL

相同的值。

A huge-context provider compacts/summarizes way too early, or the statusline context number looks wrong

大上下文提供商过早压缩/总结，或状态栏上下文数值看起来不对

Symptom: a provider whose own docs claim ~1M tokens of context gets auto-compacted by Claude Code well below that — long sessions get summarized when there's clearly no real need to yet, or the context percentage in the statusline tracks like it's looking at a ~200K model instead of the real ceiling.

Cause: the profile's

ANTHROPIC_MODEL

(and its

ANTHROPIC_DEFAULT_*_MODEL

CLAUDE_CODE_SUBAGENT_MODEL

siblings) is missing the

[1m]

marker. Claude Code has no other way to learn the provider's real context size — the request itself succeeding with a huge prompt doesn't tell Claude Code anything, since that's a property of the upstream provider, not of the client. See

references/context-window-config.md

for the full mechanism.

Fix: add the literal

[1m]

suffix to

ANTHROPIC_MODEL

, every

ANTHROPIC_DEFAULT_*_MODEL

, and

CLAUDE_CODE_SUBAGENT_MODEL

in the profile's

settings.json

(match

kimi.json

's pattern). Restart the affected window.

症状：某提供商的文档声称有约1M tokens的上下文，但Claude Code远低于这个值就自动压缩了——长会话在显然还没有实际需要的时候就被总结了，或者状态栏中的上下文百分比看起来像是针对约200K的模型，而非真实上限。

原因：该Profile的

ANTHROPIC_MODEL

（以及对应的

ANTHROPIC_DEFAULT_*_MODEL

CLAUDE_CODE_SUBAGENT_MODEL

）缺少

[1m]

标记。Claude Code没有其他方式得知提供商的真实上下文大小——大提示请求成功本身并不能告诉Claude Code任何信息，因为这是上游提供商的属性，而非客户端的属性。完整机制请参阅

references/context-window-config.md

。

解决方法：在该Profile的

settings.json

中，为

ANTHROPIC_MODEL

、每个

ANTHROPIC_DEFAULT_*_MODEL

以及

CLAUDE_CODE_SUBAGENT_MODEL

添加字面量

[1m]

后缀（参照

kimi.json

的模式）。重启受影响的窗口。

Adding a New Provider Later

后续添加新提供商

Create
```
~/.claude/settings/<new-provider>.json
```
using a template.
Check the provider's real, verified context window and configure it —
```
[1m]
```
marker or explicit
```
CLAUDE_CODE_MAX_CONTEXT_TOKENS
```
/
```
CLAUDE_CODE_AUTO_COMPACT_WINDOW
```
, see "Configuring Context Window Size" below and
```
references/context-window-config.md
```
. Don't skip this because the template you copied from happened not to need it.
Run
```
claude-profiles-init
```
.
Add an alias to the shell rc file if desired.

使用模板创建
```
~/.claude/settings/<new-provider>.json
```
。
检查提供商真实的、已验证的上下文窗口并进行配置——
```
[1m]
```
标记或显式设置
```
CLAUDE_CODE_MAX_CONTEXT_TOKENS
```
/
```
CLAUDE_CODE_AUTO_COMPACT_WINDOW
```
，见下文「配置上下文窗口大小」和
```
references/context-window-config.md
```
。不要因为你复制的模板恰好不需要就跳过这一步。
运行
```
claude-profiles-init
```
。
如需，在Shell rc文件中添加别名。

Security Notes

安全说明

API keys are written to
```
~/.claude/settings/<provider>.json
```
in plain text, the same way Claude Code stores
```
ANTHROPIC_AUTH_TOKEN
```
. This matches Claude Code's own security model.
This skill never uploads keys or settings anywhere.
For public distribution, the bundled scripts contain no hardcoded secrets, endpoints, or user-specific paths.

API密钥以明文形式写入
```
~/.claude/settings/<provider>.json
```
，与Claude Code存储
```
ANTHROPIC_AUTH_TOKEN
```
的方式相同。这与Claude Code自身的安全模型一致。
此Skill绝不会将密钥或设置上传到任何地方。
对于公开发布，捆绑的脚本不包含硬编码的密钥、端点或用户特定路径。

Next Step

下一步

After setup, the user can immediately test by opening two terminals and running

csk

(Kimi K3) in one and

csd

in the other. Each window is independent.

When the person being set up is a workshop attendee doing it on their own machine rather than someone you are driving, hand them

references/student-setup-guide.md

instead of walking them through this file — it is written for them, front to back, without the maintenance and troubleshooting material they do not need yet.

设置完成后，用户可以立即测试：打开两个终端，在一个中运行

csk

（Kimi K3），在另一个中运行

csd

。每个窗口都是独立的。

如果被设置的人是在自己机器上操作的工作坊参与者，而不是由你操作的对象，请将

references/student-setup-guide.md

交给他们，而不是带他们通读此文件——该文档是为他们编写的，从头到尾没有他们暂时不需要的维护和故障排查内容。