claude-switch-models-setup

Claude Code 配置文件与本地技能激活

概述

此技能为 Claude Code CLI 创建一个隔离但共享的配置文件系统。每个配置文件都有自己的 .claude.json 状态文件（提供商凭据和会话历史），同时在所有配置文件之间共享技能、项目、钩子脚本、Agent 和已安装的插件状态；此外，还会将每个配置文件的 settings.json（钩子注册、市场、环境变量功能标志、权限、偏好设置）以及其 .claude.json 中的行为部分（例如 workflowSizeGuideline）与默认配置文件保持一致，因此配置文件之间唯一预期的差异就是模型／提供商。

结果：你可以在一个终端中打开 Kimi，在另一个终端中打开 DeepSeek，再在第三个终端中打开 Anthropic——每个终端都运行一个完全独立的 Claude Code 进程，不会发生配置串扰。

如需减少 MCP 工具架构预加载导致的固定启动上下文，请阅读 references/mcp-startup-context.md。该文档负责 相同模式下的测量、活动配置文件发现、提供商兼容性检查、 可逆的服务抑制以及全新进程验收。

工作原理

• CLAUDE_CONFIG_DIR 告诉 Claude Code CLI 将哪个目录用作配置根目录。
• 每个配置档案都位于 ~/.claude-profiles/<name>/，并拥有独立的 .claude.json。
• 内容目录（skills/、projects/、hooks/、agents/、settings/）会符号链接回主 ~/.claude/ 目录，因此只需维护一份副本。请注意，共享的是钩子脚本，而不是钩子注册信息——注册信息保存在每个配置档案各自的 settings.json 中（见下一条）。
• 配置层——settings.json：每个配置档案都有自己的 settings.json（Claude Code 将其视为配置目录本地文件），因此其中存储的所有内容——钩子注册信息、extraKnownMarketplaces、enabledPlugins、env 功能标记、permissions、行为偏好——在默认配置档案中一旦发生更改，就会悄然产生偏差（截至 2026-07-18 的测量结果：9/9 个实际配置档案都没有任何钩子注册信息）。sync-profile-settings.py 负责收敛：它注册为 SessionStart 钩子，将默认配置档案 settings.json 中的每个键复制到每个配置档案的文件中，但身份键除外（顶层 model 和 advisorModel——后者是 Anthropic 模型路由，第三方端点无法提供服务；以及承载提供商路由或 Anthropic 原生隔离设置的环境变量——ANTHROPIC_*、CLAUDE_CODE_SUBAGENT_MODEL、ENABLE_TOOL_SEARCH、DISABLE_GROWTHBOOK/TELEMETRY/AUTOUPDATER——提供商设置文件会刻意将这些变量设为不同值）。在 env 中，非身份键会双向收敛：主配置中的键会覆盖配置档案中的键；如果主配置不再包含某个非身份键，该键就会从配置档案中删除并报告（身份键不受此规则影响——主配置从不包含它们，因此缺少它们不代表要删除）。配置档案独有的顶层键会保留；而主配置中也存在的键内嵌套集合（例如 permissions.allow、enabledPlugins）会整体收敛为主配置中的值，通过此方式丢弃的配置档案独有嵌套项会被列出（写入时显示数量，--check 时显示详情），让数据丢失清晰可见，而不是悄无声息。这正是“除模型外，所有设置在每个配置档案中都能正常工作”得以成立的原因。
  • 每次调用都会涵盖所有配置档案。无论是不带参数、使用 --all 还是使用 --check，都不会只处理其中一部分：每次都会涵盖所有 ~/.claude-profiles/*，以及 $CLAUDE_CONFIG_DIR。每次运行都会为实际发生更改的每个配置档案打印一行；没有偏差时则不输出内容——因此，偏差会显示在会话启动输出中，而不是被隐藏起来；会话启动时没有输出，就表示配置已收敛。未设置、为空或不是配置档案目录的 $CLAUDE_CONFIG_DIR 会被跳过，不会创建。
  • **退出码：**不带参数的运行无条件以 0 退出——它是会话启动钩子，不会阻止会话启动；即使主文件损坏也一样（它会发出警告，不执行收敛，并以 0 退出，因为损坏的主文件会被读取为空，向空内容收敛会移除每个配置档案中的钩子）。存在偏差时，--check 以 1 退出；主文件损坏或无法读取某个配置档案时，以 2 退出；--all 会写入，并在出现同样两类错误时以 2 退出——两者的区别在于 --check 不写入，而不是哪些错误会返回 2。--check --all 与 --check 执行相同的审计。无法读取的配置档案会被报告并跳过，不会导致其他配置档案的收敛被取消。
• 状态层——.claude.json 行为键：settings.json 不是唯一按配置档案区分的配置文件。Claude Code 还会为每个配置档案维护一个状态文件（主配置档案的文件是 ~/.claude.json；每个第三方配置档案的文件是 <profile>/.claude.json——路径并不对称，已在磁盘上验证），少数行为设置只保存在其中（workflowSizeGuideline、通知／界面偏好）。2026-08-17，workflowSizeGuideline: small 只存在于主配置档案中，11 个第三方配置档案里有 10 个没有副本——一次 Kimi 会话在系统提示词中没有大小指导的情况下，将一个 Dynamic Workflow 扩展到了 30 多个 Agent。因此，同一个收敛器还会将一份行为键允许列表同步到每个配置档案的 .claude.json 中。安全机制是脚本中的三向分类器，而不是手工维护的键列表：允许列表中的行为键会同步；通过名称模式匹配的状态／缓存／计数器／迁移／凭据键不会被触碰；任何未知且不同的键都会被报告——每次运行中，每个有偏差的键各占一行，直到人工完成分类（这道警戒线会在下一个行为键出现当天将其显现出来）。写入时会先备份，再进行原子替换；经测量，在实时测试环境重写文件时依然安全（活动会话运行 30 多分钟后，标记键仍然保留）。更改会在下一个会话中生效——测试环境会在启动时读取此文件。
• 例外——plugins/：市场内容和安装状态会共享，但每个配置档案都保留自己的 known_marketplaces.json。Claude 会使用 path.resolve() 验证市场的 installLocation（它不会解析符号链接），因此如果只共享一个文件，所有非写入配置档案都会报告“corrupted installLocation”。claude-plugins-sync.py 会构建并维护这种按配置档案区分的结构。
• claude-plugins-sync.py 还会将默认 ~/.claude/settings.json 中的 enabledPlugins 镜像到每个配置档案的 settings.json 中（仅共享缓存文件还不够；Claude Code 将“已启用”状态视为配置目录本地状态）。它会在配置档案启动时运行，并在发生更改时作出响应——下一条中的 LaunchAgent 会在默认配置档案的 settings.json 每次写入时重新运行它，因此 claude plugin enable／disable --scope user 通常会在几秒内传播到每个配置档案，无需重新启动（2026-08-22 已验证）。镜像会先接纳：只存在于部分配置档案 settings.json 中的 enabledPlugins 键（claude plugin install 的写入方式）会先写回默认配置档案，然后再进行镜像——只接纳值一致的键；跨配置档案冲突会保留在各自配置档案中，并持续发出警告，而不会被悄然覆盖。上文的 SessionStart 收敛器会在整体设置同步中涵盖同一个键；claude-plugins-sync.py 仍负责维护每个配置档案的 known_marketplaces.json 结构。skill-install-audit.py 以只读方式核对注册表／已安装／已启用／Codex 清单／~/.agents/skills 各层，以及守护进程固定的运行时版本，并检查用于判断所有内容的检出版本本身是否已经落后。prune-source-sync-backups.py 只会移除 Git 可以重新生成的 .source-sync-backups/ 备份目录；只要某个目录中有一个 blob 不存在于任何仓库中，就会报告并保留该目录。
• 本地源同步会使每台主机上的已批准源支持路由保持一致。 在选择或修复条目之前，请先阅读 主机专属激活约定。 该约定规定了清单字段、市场展开方式、Claude 插件与直接链接的区别、未解析名称的处理方式、冲突安全性和旧版兼容性。 仅注册源并不能决定激活策略；不要手动创建链接，也不要重新利用清单来管理第三方清单。
• 同步脚本使用跨进程共享锁。此锁必不可少，因为用户经常同时从 tmux 或多个终端窗口打开多个提供商窗口；并发启动必须按顺序处理市场／缓存重写，同时仍允许所有配置档案启动。
• 修改这些脚本之前，请先阅读 references/local-source-sync-architecture.md，了解完整的本地源架构。
• 如需在已批准的独立 Fleet 克隆中编写 Skill，请使用租用式编写负责人流程。
• 提供商路由通过 ~/.claude/settings/<name>.json 完成，该文件会为对应窗口设置 ANTHROPIC_MODEL、ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。该文件是完整的设置文件，而非环境文件；它也是收敛器绝不会触碰的唯一层——claude-profile 会使用 claude --settings ~/.claude/settings/<name>.json 启动，而收敛器只会写入 <profile>/settings.json。因此，任何必须按配置档案区分且必须在每次会话启动后保留的内容，都应放在这里；如果将它放入配置档案自己的 settings.json，下一次收敛就会将其恢复为默认值。这包括按配置档案区分的 permissions.deny，例如拒绝 WebSearch 和 WebFetch。
• **按配置档案区分的思考力度也保存在该提供商文件中。**默认配置档案会通过 ~/.claude/settings.json 中的 modelSettings，按 Anthropic 模型设置力度；需要设置不同力度的第三方配置档案，则应在自己的 ~/.claude/settings/<name>.json 环境变量中固定 CLAUDE_CODE_EFFORT_LEVEL（例如 "max"）。提供商文件是唯一能够保存此固定值的层：如果将它放在配置档案自己的 settings.json 环境变量中，收敛器会在下次会话启动时将其删除（默认配置档案不包含的非身份环境变量会通过删除传播机制被移除）；如果将它放在默认配置档案的环境变量中，它就会应用于默认配置档案，并且收敛到每个第三方配置档案的 settings.json 中——通常这并不正确，因为当默认旗舰模型不再需要强制最大力度时，较弱的第三方模型恰恰更需要这样做（2026-10-06 已端到端验证：通过 claude-profile 启动的会话会从自身环境中读取回固定值）。
• **凭据也保存在同一文件中，因此任何用于脚本化操作配置档案的程序都必须传入 --settings。**单独使用 CLAUDE_CONFIG_DIR=<profile> claude -p ... 会返回 Not logged in · Please run /login，因为令牌保存在提供商文件中，其他地方都不会加载它。提示信息提到了登录；真正的原因是缺少该标记。
• 收敛器没有针对单个配置档案的模式：每次调用都会涵盖所有 ~/.claude-profiles/*，以及 $CLAUDE_CONFIG_DIR，且没有任何标记可以缩小范围。如需按需收敛某个配置档案，请将 CLAUDE_PROFILES_ROOT 指向只包含该配置档案的目录，或者运行 --check 并查看逐个配置档案的输出行。默认配置档案自己的文件是数据源，绝不会被写入。

⚠️ 切勿针对虚构的主配置运行 converger

范围涵盖所有配置：包括 ~/.claude-profiles/* 和 $CLAUDE_CONFIG_DIR； 事实来源是 CLAUDE_MAIN_CONFIG_DIR。如果在 CLAUDE_PROFILES_ROOT 或 $CLAUDE_CONFIG_DIR 仍指向真实配置时，将其指向一个临时目录，那么运行会让真实配置向虚构的主配置收敛：整个 hooks 对象都会被虚构主配置中的内容替换，env 也会增加虚构主配置中的键。**该配置中注册的每个守卫都会停止触发。**输出确实会在已同步的键中列出 hooks，并且在覆盖操作移除了仅存在于配置中的条目时报告数量，但不会说明守卫已停止触发，因此看起来就像 converger 正在正常工作。只有当配置根目录和 $CLAUDE_CONFIG_DIR 也都是虚构且可丢弃的配置时，虚构的主配置才是安全的。

手动运行前，检查作用范围的两个部分：

echo "MAIN=$CLAUDE_MAIN_CONFIG_DIR ROOT=$CLAUDE_PROFILES_ROOT ACTIVE=$CLAUDE_CONFIG_DIR"

CLAUDE_PROFILES_ROOT 未设置并不表示安全——它会默认使用真实的 ~/.claude-profiles，因此所有真实配置都会收敛。除非 CLAUDE_PROFILES_ROOT 和 $CLAUDE_CONFIG_DIR 都是虚构且可丢弃的配置，否则请停止操作。测试夹具必须基于清理过的环境构建子进程环境，而不是继承当前环境——shell 配置文件会设置这些变量，而在脚本中执行 unset 并不能可靠地将其传递给子进程：

env -u CLAUDE_CONFIG_DIR -u CLAUDE_MAIN_CONFIG_DIR -u CLAUDE_PROFILES_ROOT …

机械地判断运行是否写入了内容，不要靠目测。记录运行前目标配置的 settings.json 大小，并在运行后进行比较。.sync-backup 使用 shutil.copy2 写入，该函数会保留源文件的修改时间，因此备份时间戳较早并不能证明没有写入任何内容——请比较文件大小和字节内容。

如果确实写入了真实配置，请从该配置自己的备份恢复，并逐字节验证：

cp -p <profile>/settings.json.sync-backup <profile>/settings.json

检查文件大小、JSON 有效性、顶层键数量、hooks 长度、意外的 env 键，以及 /bin/true 等沙箱特征。然后扫描其他配置：作用范围涵盖所有配置，因此一次运行可能会影响多个配置。

捕获原生结构化输出的调用方

引入 scripts/claude-profiles.sh，并在调用方必须在原生调用时捕获标准输出时，调用 claude-profile-with-command "<absolute-executable>" <profile> [claude arguments...]。 提供的可执行文件（或其符号链接）会在该配置的 CLAUDE_CONFIG_DIR 下接收原始的 --settings 和 Claude 参数；配置验证、同步、启动输出和凭据仍由原有组件负责。该可执行文件只控制原生调用，并返回该调用的退出状态。

调用此入口前，请使用可信且版本匹配、符合 claude-profile-native-command-api: 1 契约的脚本。需要此边界的调用方必须在运行配置设置之前拒绝不受支持的脚本；拦截名为 claude 的 shell 函数无法覆盖 command claude 或原生绝对路径。普通的 claude-profile 调用仍保持原有行为。

一键设置工作流

当用户说类似“设置 Claude Code 配置”或“我想在不同窗口中使用 Kimi 和 DeepSeek”时：

1. 检查前提条件

   • 已安装 claude CLI：which claude
   • Shell 为 zsh 或 bash：通过 $SHELL 检测
   • python3 可用

2. 安装配置管理器脚本——创建符号链接，不要复制

   在已克隆此仓库的机器上（维护者场景），运行随附的安装程序：

   <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 都会通过该路径调用脚本——而本仓库保存的是它们的源文件。副本会逐渐偏离，而且已部署的副本看起来与源文件没有区别。链接可以防止副本被独立编辑，也能避免源文件更新后两者悄然不一致，但前提是它一直保持为链接——支持原子保存的编辑器、rsync 或误操作的 cp 都会在不作提示的情况下将其变回普通文件。因此值得定期重新检查，而不是以为问题已经解决。这样也能让 sync-local-skill-sources.py 通过解析自身路径找到自己的源代码仓库，而不必退而求其次地猜测。

   怎样重新检查？定期检查即可；此技能未附带任何检查机制。可以在你存放此类检查的地方运行下面这一行：

   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"，然后进行差异比较。

   在没有该仓库的机器上，请改为从此技能包中复制安装程序列出的脚本，并接受这样一个事实：仓库中的修复不会同步到该机器，除非你再次复制。

   在 LaunchAgent 运行固定版本插件副本的机器上（维护者布局见 local-source-sync-architecture.md），这些链接会指向该副本在 .../plugins/cache/... 下的版本目录，而不是检出目录；只有推进固定版本时才会移动（见 troubleshooting.md 中的“推进固定版本”）。安装程序会拒绝将这类机器的链接重新指向检出目录（可通过 CSMS_SETUP_RELINK_TO_CHECKOUT=1 覆盖），因为这样一来，守护进程和 claude-profile 就会跟随检出目录所在的分支。上面的活动链接检查适用于这两种布局。

3. 添加 shell 集成

   • 在 ~/.zshrc 或 ~/.bashrc 中加载配置管理器
   • 添加别名：csk、csd、csg
   • 如有需要，手动添加其他按账户／套餐区分的变体别名——脚本的帮助文本只列出上面的基本示例；cssplan／cssp 等变体需手动添加，不会自动生成
   • 告知用户运行 source ~/.zshrc（或打开新终端）

4. 生成提供商设置文件

   • 对于用户需要的每个提供商，创建 ~/.claude/settings/<provider>.json
   • 使用 assets/templates/ 中的模板作为起点
   • 提示用户提供 API 密钥和基础 URL；绝不要硬编码默认值
   • 为该特定提供商正确设置上下文窗口——使用 [1m] 后缀，或显式设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS／CLAUDE_CODE_AUTO_COMPACT_WINDOW；请参阅下文“配置上下文窗口大小”。每创建一个新配置文件都要明确完成此项，不要照搬最近的模板中已有的设置——最近的模板不需要此设置，并不代表当前模板也不需要。
   • 包含必需的隔离标志：
     • CLAUDE_CODE_SUBAGENT_MODEL（与 ANTHROPIC_MODEL 相同）
     • ENABLE_TOOL_SEARCH: "false"
     • DISABLE_GROWTHBOOK: "1"
     • DISABLE_TELEMETRY: "1"
     • DISABLE_AUTOUPDATER: "1"
   • 可选地固定设置 CLAUDE_CODE_EFFORT_LEVEL（例如 "max"），以便在此提供商的模型受益于强制采用不同于默认配置文件的思考强度时使用。此设置应放在此提供商的文件中——绝不要放在配置文件的 settings.json 环境变量中，因为收敛器会删除它（见“工作原理”下的“按配置文件设置思考强度”）。

5. 初始化配置目录

   • 运行 claude-profiles-init
   • 这会创建 ~/.claude-profiles/<provider>/，其中包含隔离的 .claude.json 和符号链接
   • 在维护者的计算机上，这还会在同步插件元数据之前修复本地源符号链接

   状态栏配置：claude-profiles-init 会自动从 ~/.claude/settings.json 或 ~/.claude/statusline.sh 检测状态栏脚本，并将其注入每个新 配置中。如果两者都不存在，配置仍可正常使用，但不会显示状态栏。是否需要状态栏由 AI 决定： 如果合适，应安装 statusline-generator 技能并运行其安装程序，而不是让配置脚本 执行此操作。不要将依赖项安装硬编码到 Shell 脚本中。

6. 注册设置收敛器

   • 将收敛器作为 SessionStart 钩子添加到默认配置的 ~/.claude/settings.json 的 hooks.SessionStart 列表中，使用绝对路径直接调用 Python 的命令，例如 '/absolute/path/to/python3' '/absolute/path/to/sync-profile-settings.py'。不要通过 shebang 或包管理器注册 .py 文件：此钩子用于修复每个配置，不得等待共享环境／缓存锁。注册时不要带参数——不带参数的调用是会话启动模式，会收敛所有配置，且绝不会阻塞会话。不要在钩子命令中添加 --all：--all 是供用户手动运行的模式，如果主文件损坏或无法读取某个配置，会以状态码 2 退出，从而阻塞会话启动。
   • 运行初始对齐：python3 ~/.config/claude-switch-models-setup/sync-profile-settings.py --all
   • 此后，每个配置都会在每次会话启动时，将自己的 settings.json 和 .claude.json 中的行为相关部分与默认配置收敛，无论由谁启动（更改会在下次会话生效）。默认配置自身的文件是 SSOT，绝不会被写入。只检查、不写入：--check（或 --check --all，两者执行相同的检查）。

7. 验证隔离

   • 运行 claude-profiles-doctor
   • 确认每个配置目录都包含 .claude.json 和有效的符号链接

8. 为 Codex 和 Claude 选择本地源技能

   • 普通学生或不编辑技能源代码仓库的用户可跳过此步骤
   • 阅读主机专属激活约定，然后编辑计算机上的激活清单，为所需主机进行配置。对于仍保留旧路径的使用方，仅使用其中的兼容性规则。
   • 先运行 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 安装状态和本地市场清单，并在选择、安装／卸载或插件拓扑发生更改后修复派生状态

9. 向用户说明如何启动

   • csk → Kimi 窗口

   • csd → DeepSeek 窗口

   • csg → GLM 窗口

   • claude（无别名）→ 默认 Anthropic 配置

   • 可选：自行手动添加按账户／套餐区分的别名—— claude-profiles.sh 不会生成这些别名。StepFun 是一个实际示例：其订阅套餐仅通过专用套餐基础 URL (https://api.stepfun.com/step_plan，单一模型) 提供响应，而按量付费则通过 提供商的标准端点或其前置的网关进行访问——同一提供商、两种计费模式，因此应分别设为两个配置， 并使用两个别名（务必询问准确的基础 URL）：

     alias cssplan='claude-profile step-plan --dangerously-skip-permissions'
     alias cssp='claude-profile step-pay --dangerously-skip-permissions'
     

命令

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

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.). Session start
                               # already does this for all profiles; run --all to
                               # apply a manual settings edit immediately.
                               # --check audits the same scope 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

这些命令并非日常使用。对已激活的规范源所做的编辑会通过符号链接即时生效。这些一次性命令用于修复、引导初始化，或在没有 LaunchAgent 监视器的非 macOS 环境中使用。

提供商模板

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

每个模板都使用 <API_KEY> 占位符。可配置网关的模板还使用 <BASE_URL>；MiniMax 模板则固定使用文档所述的区域端点。向用户询问每个实际占位符的值；不要猜测，也不要重用当前机器上的值，除非用户明确提供了这些值。

MiniMax-M3 支持自适应或禁用思考；请让 ANTHROPIC_REASONING_MODEL 使用相同的模型。MiniMax-M2.7 的思考始终开启；不要声称可以在模板级别禁用。请从选定的模板中读取模型和上下文值。

配置上下文窗口大小

每个提供商模板都会通过两种方式之一设置模型的上下文窗口——如果设置错误，Claude Code 就无法知道模型实际能容纳多少上下文。设置过小会导致它远早于提供商的实际要求进行压缩（摘要、丢弃较早的细节）；设置过大则会导致实际限制已被超出后，它才进行压缩。

[1m] 标记的完整客户端机制——它会从模型字段中移除什么、会向 anthropic-beta 标头添加什么，以及为什么缺少 [1m] 并不意味着提供商无法容纳较大的提示词——已记录在 references/context-window-config.md 中。如果上下文数值看起来不对，请查阅该文档，而不是在编写模板时查阅。

决策规则

编写新提供商的 settings/<name>.json 时，请根据提供商经过核实的实际上下文窗口来选择——不要依据模型的营销名称，也不要照搬最相近模板的设置：

提供商的实际上下文窗口	设置内容	示例模板
约 1M 个 token，且已明确确认（不能根据模型的级别／名称推断）	在每个 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
未知／尚未核实	不要猜测，也不要仅仅因为模板需要填写某个值，就照搬其他提供商的数值。先请用户查看提供商自己的文档／控制台。未经核实的 [1m] 或较大的 CLAUDE_CODE_AUTO_COMPACT_WINDOW，只会把问题从“过早压缩”变成“直到远超实际限制才压缩”——这更糟，因为只有请求实际失败时才会发现，且此前不会发出提示。

如果模板同时提供上下文标记和明确的限制值，请同时保留，除非已核实它们的优先级。请从选定的模板中读取实际值，而不要在此处维护模型摘要。

如需核实提供商的模型身份，以及环境变量是否会改变通过网络发送的请求，请阅读 references/context-window-config.md。

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

共享与隔离

数据	位置	是否共享？
会话历史	~/.claude-profiles/<name>/.claude.json	按配置文件隔离
身份验证令牌/缓存	~/.claude-profiles/<name>/.claude.json	按配置文件隔离
账户 + MCP OAuth 令牌	macOS Keychain，条目名称取自配置目录	默认按配置文件隔离；设置 CLAUDE_SECURESTORAGE_CONFIG_DIR="" 可让所有配置文件共享同一条目，这样 MCP 服务只需授权一次即可在所有配置文件中连接——参见 credential-storage.md
技能	~/.claude/skills/	通过符号链接共享
插件内容	~/.claude/plugins/marketplaces, cache, data, ...	通过符号链接共享
插件安装注册表	~/.claude/plugins/installed_plugins.json	通过符号链接共享
已启用插件映射	~/.claude/settings.json -> <profile>/settings.json	由 sync-profile-settings.py 收敛（也由 claude-plugins-sync.py 同步）
插件市场索引	<profile>/plugins/known_marketplaces.json	按配置文件区分（installLocation 与配置目录相关；无法共享）
项目/记忆	~/.claude/projects/, ~/.claude/memory/	通过符号链接共享
钩子脚本	~/.claude/hooks/, ~/.claude/commands/	通过符号链接共享（仅脚本——不包括注册信息）
settings.json 配置：钩子注册、市场、环境变量标志、权限、偏好设置	<profile>/settings.json	会话开始时由 sync-profile-settings.py 将默认配置文件中的内容收敛到每个配置文件（model 等身份键以及提供方路由/隔离环境变量永远不会同步）
.claude.json 行为键（workflowSizeGuideline、通知/UI 偏好设置）	~/.claude.json → <profile>/.claude.json	由同一脚本收敛行为允许列表；状态/缓存/计数器/迁移/凭据键（包括 projects、oauthAccount、userID）永远不会同步；未知的偏差键会报告出来，供人工分类
MCP 服务注册表（mcpServers）	~/.claude.json → <profile>/.claude.json	以并集形式收敛：主配置中的条目会传播；仅在某个配置文件中定义的服务会保留；同名时以主配置为准。它是行为键，而非凭据——所需的 OAuth 令牌存储在 Keychain 中，并受上一行规则约束，因此注册表条目若没有共享凭据存储，每个配置文件仍需授权一次
提供方设置	~/.claude/settings/<name>.json	共享源文件，按配置文件加载

故障排查

配置文件目录存在，但 claude-profiles-doctor 将其报告为“孤立配置文件”

现象：claude-profiles-doctor 报告 WARN: orphan profile — no settings/<name>.json; claude-profile <name> fails. Run: claude-profile-rm <name>。

原因：配置文件隔离目录存在于 ~/.claude-profiles/ 下，但缺少相应的 ~/.claude/settings/<name>.json 提供方配置文件。claude-profiles-init 只扫描 settings/*.json，因此不会创建或维护孤立配置文件的符号链接，而且 claude-profile <name> 将无法启动，并显示“Error: Settings file not found.”。配置文件目录中可能仍包含有用的配置文件专属数据（history.jsonl、含提供方凭据的 .claude.json、settings.json、技能工作区）。

解决方法：

• 如果不再需要该配置文件：运行 claude-profile-rm <name>——此命令会安全地移除隔离目录（会先检查是否存在意外文件）。
• 如果要恢复该配置文件：在 ~/.claude/settings/<name>.json 处重新创建设置文件（使用 assets/templates/ 中的提供方模板），然后运行 claude-profiles-init。

共享目录（skills/projects/hooks/agents/...）显示为真实目录，而不是符号链接

症状：claude-profiles-doctor 报告 <name> is a real directory (expected symlink to ~/.claude/<name>) — drift; run: claude-profiles-init --repair。

原因：该配置是在符号链接收敛设计推出之前创建的（或由手动创建），因此共享内容目录成了每个配置各自的真实目录，而不是符号链接。该配置中的副本现在会悄然偏离主 ~/.claude/ 副本——它的 skills/projects/hooks/agents 与其他所有配置都不相同。真实目录并不是损坏的链接；claude-profiles-doctor 中的目录类型检查会检测到这种偏差。

修复（可逆——数据会归档，绝不会删除）：

claude-profiles-init --repair

对于每个存在偏差的目录，此命令会将真实目录归档到配置目录内的 <name>.pre-symlink-bak-<timestamp>，然后创建原本应该存在的符号链接。再次运行 claude-profiles-doctor，确认检查通过。如果发现归档中有需要的数据，它就在原处——没有任何内容被销毁。

关于共享内容的说明：修复后，该目录会指向主 ~/.claude/<name> 副本，因此该配置看到的 skills/projects 等与默认配置相同——这正是共享符号链接设计的全部目的。必须保持隔离的每个配置状态（.claude.json、settings.json 中的身份键，如 model/提供方环境变量，以及 plugins/known_marketplaces.json）绝不会是这些符号链接目录之一，因此修复不会触及它们。如果配置中包含你在意的会话/历史记录数据，请在丢弃归档前先检查它——这些数据现在会指向共享副本。

Marketplace 提示“corrupted installLocation”

症状：/plugin 或 claude plugin marketplace update 报告 corrupted installLocation ... expected a path inside <config-dir>/plugins/marketplaces。

原因：known_marketplaces.json 在多个配置间共享（或经手动编辑）。它的 installLocation 取决于配置目录，因为 Claude 使用 path.resolve() 进行验证（不会解析符号链接），所以一个共享副本无法满足多个配置的要求。

修复：claude-plugins-sync.py 会重建每个配置各自的副本和共享内容符号链接。它会在 claude-profile 初始化/启动时自动运行；如需手动运行：

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

默认 Claude 中有技能，但 Kimi/GLM/DeepSeek 中没有

症状：默认 Anthropic 配置可以看到某个技能，但第三方配置看不到。

原因：Claude Code 会将 enabledPlugins 存储在每个配置目录的 settings.json 中。共享 plugins/cache 只会让文件可用；它不会启用这些插件。

修复：

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

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

本地源文件编辑不会显示在 Claude Code 或 Codex 中

请阅读源文件更改和固定版本更新流程。 其中会区分基于源文件的路径与固定的运行时副本，也会区分清单报告与成功同步及新主机发现。

源文件同步还会管理派生的缓存产物：

• 版本别名符号链接。 每个缓存链接都以 Marketplace 当前版本命名。此流程会移除指向同一源的同级链接；绝不会触碰真实目录，因为 Claude Code 会安装这些目录，且活动会话可能仍通过 .in_use 持有它们。
• installed_plugins.json 备份。 每次运行中只要 JSON 有更改，就会写入备份。脚本中的 KEEP_JSON_BACKUPS 常量会限制保留数量；备份名称以 YYYYMMDD-HHMMSS 时间戳结尾，因此按字典序排列即为时间顺序。

在 --apply 执行任何更改前，试运行中会显示这两类内容。

缺少钩子、市场、环境变量标志或其他默认配置文件设置

症状：默认配置文件配置了钩子守卫、市场或功能标志，但第三方配置文件的表现却像是这些设置不存在（没有触发 PreToolUse 守卫，claude plugin marketplace list 显示为空，默认配置文件中启用的功能处于关闭状态）。

**同类症状，但属于不同层面：**在默认配置文件中设置的行为偏好（例如工作流大小指南）对第三方配置文件没有影响。该键位于每个配置文件各自的 .claude.json 中，目录符号链接和 settings.json 同步都不会覆盖它。请参阅 references/troubleshooting.md 中的“默认配置文件的行为设置未传递到第三方配置文件”。

原因：这些设置位于各配置文件自身的 settings.json 中，且仅对配置目录有效——符号链接目录不会覆盖配置层；默认配置文件一旦发生更改，这些设置就会悄无声息地出现偏差。

修复方法：

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

然后重启受影响的窗口。将合并器注册为 SessionStart 钩子（设置步骤 6）后，下一次会话启动时就会合并所有配置文件的设置，而不仅仅是启动该会话的配置文件，因此只有在需要立即应用手动修改的设置时，才需要使用 --all。

第三方配置文件尝试使用 Anthropic 专属功能

症状：WebSearch 或其他 Anthropic 原生工具报错 400。 修复方法：确保配置文件的 settings.json 设置了：

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

子 Agent 调用回退到其他模型

症状：Kimi 窗口中的子 Agent 调用 claude-opus-4-7。 修复方法：在配置文件的 settings.json 中，将 CLAUDE_CODE_SUBAGENT_MODEL 设置为与 ANTHROPIC_MODEL 相同的值。

超大上下文提供商过早压缩／总结，或状态栏中的上下文数字看起来不正确

症状：某个提供商的文档声称其上下文约为 1M 个 Token，但 Claude Code 在远低于该上限时就自动压缩了上下文——长会话明明还不需要总结，却被总结了；或者状态栏中的上下文百分比看起来像是在按约 200K 的模型计算，而不是按真实上限计算。

原因：配置文件的 ANTHROPIC_MODEL（以及其同类设置 ANTHROPIC_DEFAULT_*_MODEL / CLAUDE_CODE_SUBAGENT_MODEL）缺少 [1m] 标记。Claude Code 没有其他方式获知提供商的真实上下文大小——请求成功处理了超长提示词，并不能让 Claude Code 获知这一点，因为上下文大小取决于上游提供商，而非客户端。完整机制请参阅 references/context-window-config.md。

修复方法：在配置文件的 settings.json 中，为 ANTHROPIC_MODEL、每个 ANTHROPIC_DEFAULT_*_MODEL 以及 CLAUDE_CODE_SUBAGENT_MODEL 添加字面值后缀 [1m]（参照 kimi.json 的模式）。重启受影响的窗口。

之后添加新提供商

1. 使用模板创建 ~/.claude/settings/<new-provider>.json。
2. 检查并配置提供商经过验证的真实上下文窗口——使用 [1m] 标记或显式设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS/CLAUDE_CODE_AUTO_COMPACT_WINDOW。请参阅下文“配置上下文窗口大小”以及 references/context-window-config.md。不要因为你复制的模板恰好不需要这些设置就跳过此步骤。
3. 运行 claude-profiles-init。
4. 如有需要，在 shell rc 文件中添加别名。

审计和退役配置

配置会不断累积：为某次实验添加的变体会一直留在那里。移除任何内容之前，先审计实际使用情况——按可靠性从高到低参考以下三个信号：

1. 提示词历史记录（~/.claude-profiles/<name>/history.jsonl）——最可靠的信号。统计条目数并读取最早和最晚的 timestamp 值；完全没有 history.jsonl 的配置从未被输入过。
2. Shell 历史记录中的启动记录——例如，使用 atuin search --search-mode prefix "<alias> " 统计各启动别名的实际使用次数。
3. .claude.json 的修改时间不是使用信号——设置收敛器和行为键同步都会在会话启动时重写此文件，因此每个配置看起来都像是最近活动过（2026-10-06 观察到：一批未使用过的配置共用一次同步运行留下的近期修改时间）。

退役时应归档，切勿直接删除：

• 将配置目录和 ~/.claude/settings/<name>.json 提供方文件移至 ~/.claude-profiles/ 之外的归档位置。如果你保留的 dotfiles 备份通过 --delete 镜像该根目录，那么下次运行时它会删除已归档配置的备份副本；将归档放在镜像根目录之外即可保留它。
• 如果一个配置接替了另一个配置的角色（提供方相同，名称不同），先将旧配置的 history.jsonl 移至新配置的目录，让提示词历史记录跟随其角色。
• 孤立配置（目录存在，但没有 settings/<name>.json）的处理方式见故障排除——在恢复或移除之前，也应进行同样的审计。

无需打开窗口，即可无头验证提供方文件中的新环境变量固定值是否能传递到实际会话：

CLAUDE_CONFIG_DIR=~/.claude-profiles/<name> claude --settings ~/.claude/settings/<name>.json \
  -p 'run printenv <VAR_NAME> via Bash and reply with only its value'

已启动会话的 Bash 会继承设置中的 env，因此打印出的值证明整个启动路径——配置目录、提供方文件、环境变量应用——端到端正常。这是对“工作原理”中所述 CLAUDE_CODE_EFFORT_LEVEL 固定值的回读验证。

安全说明

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

下一步

完成设置后，用户可以立即打开两个终端进行测试：在一个终端中运行 csk（Kimi K3），在另一个终端中运行 csd。两个窗口互不影响。

如果正在设置的是自行在个人机器上操作的工作坊参与者，而不是由你代为操作，请将 references/student-setup-guide.md 交给他们，而不要带着他们阅读此文件——该指南从头到尾都是为他们编写的，不包含他们暂时用不上的维护和故障排除内容。