模型选择与配置

结论

CC 的模型配置是别名体系：用户面对 opus/sonnet/haiku/opusplan/[1m] 等语义别名，由 ANTHROPIC_DEFAULT_*_MODEL 环境变量和 modelOverrides 把别名解析到具体 model ID；推理强度独立成 effort 档位（low→max + ultracode）。Codex 则是裸字符串 + 档位：config.toml 的 model 直接写模型名，model_reasoning_effort（minimal→xhigh）单列，可打包进命名 profile 切换。会话内改模型两家如今都会持久化（CC v2.1.153 起 /model 写 user settings，Codex 的 /model 经 app-server 写回 config）。harness 注入模型配置的正确姿势：CC 用 --model / ANTHROPIC_MODEL（仅当次会话生效），Codex 用 -m / -c model=... CLI override——都不要去改用户的持久化配置文件。

研究问题

• 模型如何指定？别名还是完整 ID？解析链是什么？
• 推理强度（effort / reasoning）如何配置？与模型选择什么关系？
• 哪些配置是会话级、哪些是持久化？harness 注入点在哪？

各 Agent 设计与实现

Claude Code

CC 源码为社区重建版（src_2026-03-31），以下仅作架构描述与短引用。

别名体系 [一手文档 claude-code-docs/docs/model-config.md:29-46]：default（清除覆盖、回到账户推荐模型）、best（=opus）、sonnet / opus / haiku、sonnet[1m] / opus[1m]（百万上下文）、opusplan（plan 模式用 opus、执行切 sonnet）。别名在源码中有专门解析（utils/model/aliases.ts:8 收录 opusplan；model.ts:152-154, 301, 335, 458 处理 opusplan 的 plan/执行分裂）[一手源码]。

优先级（高→低）[一手文档 model-config.md:50-57，一手源码 utils/model/model.ts:58-69：specifiedModel = process.env.ANTHROPIC_MODEL || settings.model]：

1. 会话内 /model <alias|name>（v2.1.153 起 Enter 同时写入 user settings 的 model 字段成为新默认；s 键仅本会话）
2. 启动参数 --model（仅当次会话）
3. 环境变量 ANTHROPIC_MODEL（仅当次会话）
4. settings 文件 model 字段（持久）

resume 的会话保留 transcript 保存时的模型，不受当前 model 设置影响 [一手文档 model-config.md:69]。

别名→ID 解析与企业管控 [一手文档 model-config.md:96-138, 305-313]：ANTHROPIC_DEFAULT_OPUS_MODEL / _SONNET_MODEL / _HAIKU_MODEL 控制别名解析目标（Bedrock 写 ARN、Vertex 写版本名）；availableModels 限制 picker 可选项（多层 merge 去重，managed 层最高）；modelOverrides 把单个 Anthropic model ID 映射到 provider 专属字符串；CLAUDE_CODE_SUBAGENT_MODEL 统一子代理模型。ANTHROPIC_SMALL_FAST_MODEL 已废弃。

Effort 档位 [一手文档 model-config.md:173-226]：low/medium/high/xhigh/max，模型相关（Opus 4.8/4.7 支持 xhigh+max，Sonnet 4.6 到 max 无 xhigh——超出则向下取整）。设置入口五个，优先级：CLAUDE_CODE_EFFORT_LEVEL env > 用户配置档位 > 模型默认；入口含 /effort、/model 内滑条、--effort flag、settings effortLevel、skill/subagent frontmatter effort。max 与 ultracode 仅会话级。ultrathink 关键词是 prompt 内单次加强，不改 API effort 值。

Fast mode：研究预览能力，付费订阅 / extra usage 计费门槛，CLAUDE_CODE_DISABLE_FAST_MODE 可禁用；禁用原因枚举 free / preference / extra_usage_disabled / network_error [一手源码 utils/fastMode.ts:39-70]。这是「同一模型的速度档位」，与 effort（推理深度档位）正交。

思考开关：alwaysThinkingEnabled（settings）、Option+T 会话内切换、MAX_THINKING_TOKENS=0 强制关；Opus 4.7+ 恒为 adaptive reasoning，fixed budget 不适用 [一手文档 model-config.md:236-246]。

Codex CLI

配置面：~/.codex/config.toml 顶层字段 [一手源码 codex-rs/config/src/config_toml.rs:139-345]：

model = "gpt-5.5-codex"             # 裸字符串，无别名层
review_model = "..."                 # /review 专用模型
model_provider = "openai"            # 指向 model_providers map（见 providers 章）
model_context_window = 272000        # 可手动声明上下文窗口
model_reasoning_effort = "high"      # none|minimal|low|medium(默认)|high|xhigh
plan_mode_reasoning_effort = "xhigh" # plan 模式单独档位
model_reasoning_summary = "..."      # 推理摘要展示
model_verbosity = "..."              # GPT-5 Responses API text.verbosity

ReasoningEffort 枚举：None / Minimal / Low / Medium(default) / High / XHigh / Custom(String)——Custom 兜底未知档位，向前兼容服务端新值 [一手源码 protocol/src/openai_models.rs:40-50]。

Profile 机制：ConfigProfile 把 model / model_provider / model_reasoning_effort / approval_policy / service_tier（default/priority/flex，legacy fast）等打包成命名组合，--profile 一键切换 [一手源码 config/src/profile_toml.rs:24-45]。这相当于 CC 没有的「场景预设」能力。

会话内 /model：TUI 的 model picker 选定后发 AppEvent::PersistModelSelection，经 write_config_batch 写回配置并提示 "Model changed to {model}"，失败则报 "Failed to save default model" [一手源码 tui/src/chatwidget/model_popups.rs:519-533，tui/src/app/event_dispatch.rs:1301-1333]——即 Codex 的 /model 默认持久化。plan 模式存在仅会话不持久的路径（apply_model_and_effort_without_persist）。

会话级覆盖：CLI 的 -m <model> 与通用 -c key=value（覆盖任意 config 键）只影响当次进程，不写文件 [一手源码 tui/src/chatwidget/model_popups.rs:206 的提示文案："Access legacy models by running codex -m <model_name> or in your config.toml"]。

差异矩阵

最小复现

# CC：三种会话级模型注入（互不污染持久配置）
claude --model opus
ANTHROPIC_MODEL=sonnet claude
claude --effort low

# CC：检查当前生效模型与设置来源
#   /status 或 /model（picker 顶部标注 settings 来源）

# Codex：会话级覆盖 vs 持久化
codex -m gpt-5.5-codex                 # 仅当次
codex -c model_reasoning_effort=xhigh  # 仅当次
#   会话内 /model 选择 => 写回 config.toml（持久）
grep -E '^model' ~/.codex/config.toml

Harness 接入建议（Yoda 实践）

• 模型候选发现：Yoda 的 runtime-model-candidates-service 按 catalog → zenmux → officialApi → docs → cli 五个来源推断每个 runtime 的可用模型列表，7 天缓存（MODEL_CANDIDATE_CACHE_TTL_MS），并经 runtime-model-catalog 按 runtime 过滤不合法 ID [一手源码 yoda/src/main/core/settings/runtime-model-candidates-service.ts:27-50]。教训：不要硬编码模型列表——CC 别名随版本漂移，Codex 模型名随服务端发布漂移。
• 注入而非改写：Yoda 给每个会话注入模型配置用 CLI 层手段（CC --model / env；Codex -m / -c），让用户自己的 settings.json / config.toml 保持原样；否则 harness 与 CLI 双写同一文件必然冲突（CC /model 现在也会写 settings）。
• 档位映射：跨 runtime 暴露统一「效率档位」时，注意两家枚举不对齐（CC 无 minimal，Codex 无 max），harness 应做显式映射表而非透传字符串；CC 落在不支持档位会静默向下取整 [一手文档 model-config.md:184]，Codex Custom 变体可透传未知值。
• opusplan 类复合别名：harness 显示"当前模型"时别只读配置值——CC 的 opusplan 在 plan/执行期实际模型不同，应读 transcript 中 assistant 行的 message.model 字段拿真实值（usage-sync 章同款数据源）。

失效条件

• CC 别名→默认模型的映射随新模型发布滚动（文档明示 alias "update over time"），版本号相关描述（Opus 4.8 需 v2.1.154+）会过期
• CC /model 持久化行为刚在 v2.1.144→v2.1.153 间变过两次，后续仍可能调整
• Codex ReasoningEffort 档位集合扩充（Custom 变体的存在说明服务端可能先行）
• Codex profile / -c override 的优先级若改变（当前 CLI override > profile > config.toml 顶层，需回归验证）
• CC fast mode 走出研究预览后，门槛与开关名可能变化

参考资料

• CC 官方文档：claude-code-docs/docs/model-config.md（别名、effort、1M 上下文、availableModels、modelOverrides 全量参考）
• CC 重建源码：src_2026-03-31/utils/model/{model.ts,aliases.ts,modelOptions.ts,providers.ts}、utils/fastMode.ts
• Codex 源码：codex-rs/config/src/config_toml.rs、config/src/profile_toml.rs、protocol/src/openai_models.rs、tui/src/chatwidget/model_popups.rs、tui/src/app/event_dispatch.rs
• Codex 配置文档指针：codex/docs/config.md → https://developers.openai.com/codex/config-reference
• Yoda：src/main/core/settings/runtime-model-candidates-service.ts、settings/runtime-model-catalog.ts