Claude Code 接入 CLIProxyAPI：模型路由、协议转换与上下文管理

一句话结论：当前采用显式模型映射而非网关发现；Claude Code 通过 CLIProxyAPI 使用 Codex 与 Grok 模型，并分别由家族映射、Fast/Effort 转换和本地自动压缩策略控制模型路由、推理方式与上下文窗口。

阅读地图

需要特别区分：

• 发现开关只决定“要不要向网关请求模型目录”，不决定“发现哪些模型”；
• availableModels 是允许列表，不负责向网关获取模型；
• 四个 DEFAULT 变量是家族别名到实际模型 ID 的映射，不是网关发现配置；
• ANTHROPIC_CUSTOM_MODEL_OPTION 是额外增加一个自定义入口，当前用于 Grok 4.6。

研究范围与验证环境

本文根据官方文档、CLIProxyAPI 源码和本机实测整理：

• Claude Code 模型配置
• Claude Code 网关协议：模型发现
• Claude Code 的其他 LLM 网关说明
• CLIProxyAPI 源码
• CLIProxyAPI 源码版本：2e6b1d83f6c304a102aa33c1faf0a4f94d0d331e
• Claude Code 当前版本：2.1.232（模型行为最初在 2.1.227 核对，窗口逻辑在 2.1.228 核对，内置 Skills 在 2.1.229 核对）
• 本机网关地址：http://127.0.0.1:8317

需要注意：Anthropic 官方文档明确表示，不支持通过网关把 Claude Code 路由到非 Claude 模型。本文记录的是 CLIProxyAPI 在本机实现的兼容方案，不代表 Anthropic 官方支持这种用法。

本机使用的文件：

• Claude Code 配置：~/.claude/settings.json
• CLIProxyAPI 配置：~/.cli-proxy-api/config.yaml
• OAuth 凭据：~/.cli-proxy-api/*.json
• 源码仓库里的 config.yaml 是软链接，指向上面的 CLIProxyAPI 配置
• Homebrew 已不再参与当前运行链路

1. 当前方案与配置

下面是本文更新时真正生效的相关配置。密钥已脱敏。

{
  "model": "haiku",
  "effortLevel": "xhigh",
  "autoCompactEnabled": true,
  "skillOverrides": {
    "claude-api": "user-invocable-only"
  },
  "availableModels": [
    "fable",
    "gpt-5.6-sol",
    "gpt-5.6-terra",
    "gpt-5.6-luna",
    "grok-4.6"
  ],
  "env": {
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "272000",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317",
    "ANTHROPIC_AUTH_TOKEN": "cc******oh",

    "CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK": "1",

    "ANTHROPIC_DEFAULT_FABLE_MODEL": "gpt-5.6-sol",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.6-sol",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.6-terra",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.6-luna",

    "ANTHROPIC_CUSTOM_MODEL_OPTION": "grok-4.6",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "Grok 4.6",

    "CLAUDE_CODE_SUBAGENT_MODEL": "gpt-5.6-terra"
  }
}

当前没有项目级 .claude/settings.json 覆盖。model 和 effortLevel 属于交互偏好，之后仍可能被 /model 和 /effort 改写。本文更新时没有持久化 fastMode；是否开启 Fast，应以当前会话的 /fast 状态为准。

ANTHROPIC_AUTH_TOKEN 不是 OpenAI、Anthropic 或 Codex 的上游凭据。它只是 Claude Code 进入 CLIProxyAPI 的本地钥匙。真正的 Codex、XAI 等 OAuth 凭据由 CLIProxyAPI 保存和刷新。

为什么采用这套方案

当前方案采用“显式入口”，不再依赖网关自动发现：

• 关闭 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY，去掉 From gateway 重复项；
• Fable → Sol；
• Opus → Sol；
• Sonnet → Terra；
• Haiku → Luna；
• Grok 4.6 使用唯一的 Custom Model 槽位；
• availableModels 只保留 Fable、Sol、Terra、Luna、Grok 4.6，并排除 gpt-image-2；
• 子 Agent 单独固定到 Terra；
• 保留 CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK，让 /fast 可以通过本机网关使用。

Fable 与 Opus 共用 Sol 是有意的家族映射，不代表一条请求会调用两次。当前方案牺牲了“CLIProxyAPI 新增模型后自动出现在 /model”这一点，换来更短、更稳定、没有 From gateway 重复项的选择器。

2. Claude Code 如何选择和映射模型

/model 如何切换并保存选择

在本机 Claude Code 2.1.227 的 /model 选择器中：

• 选中条目后按 Enter：立即切换，并保存为以后新会话的默认模型；
• 在选择器中按 s：只切换当前会话，不保存为默认；
• 使用 –model 或 ANTHROPIC_MODEL 启动：只影响本次启动的会话。

因此，/model 一定会影响当前会话，但是否同时写入默认值，要看选择时使用 Enter 还是 s。

本文更新时，~/.claude/settings.json 中的顶层 model 为 haiku。它表示新会话默认选择 Haiku 家族入口，并通过 ANTHROPIC_DEFAULT_HAIKU_MODEL 实际发送 gpt-5.6-luna；以后再次保存其他模型时，这个字段还会变化。

Default 到底如何决定模型

/model 选择器里的 Default 不是一个具体模型，也不会阅读当前任务后动态推荐。它是一个特殊值：清除显式模型选择，然后按账号类型或 Provider 使用固定的 runtime default。

Claude Code 2.1.227 的公开规则是：

还有两层覆盖规则：

1. Anthropic Enterprise 管理员设置的 organization default 会先替代账号类型默认值；
2. managed settings 若同时提供非空 availableModels 和 enforceAvailableModels: true，而正常 Default 不在白名单中，则 Default 改为白名单里第一个允许且可用的模型。

organization default 不会下发到 LLM gateway 会话，因此当前 CLIProxyAPI 接入主要使用“账号或 Provider 默认 → 家族映射”这条链路。

本机 /model 显示：

Default (recommended)
Use the default model (currently gpt-5.6-sol[1m])

它的完整解析过程是：

当前会话被识别为 API Usage Billing
→ 该类型的 runtime default 是 Opus 5
→ ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-sol
→ 保留 Opus 的 1M 上下文语义
→ 选择器显示 gpt-5.6-sol[1m]
→ 请求发给网关前去掉 [1m]，实际 model ID 为 gpt-5.6-sol

因此，Default 当前明确走的是 Opus → Sol，不是 Fable → Sol。Fable 5 不是任何账号类型的 Default；只有显式选择 fable、把 model 设置成 fable，或者使用可解析到 Fable 的 best 别名时才会进入 Fable。

Default 能不能关闭

需要区分“限制目标”和“删除入口”：

• 不能通过受支持的配置把 Default 这一行从 /model 选择器中删除；
• availableModels 单独不会限制 Default；
• 即使 availableModels 是空数组，Default 仍然可用；
• Claude Code 2.1.175 及以后，可以在 managed settings 中同时设置非空 availableModels 和 enforceAvailableModels: true，让 Default 服从白名单；
• enforcement 只能在正常 Default 不在白名单时把它重定向到第一个可用条目，Default 这一行仍然存在。

示例：

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

这不是普通用户级 ~/.claude/settings.json 的开关，而是 managed settings 策略。macOS 文件型策略的位置是：

/Library/Application Support/ClaudeCode/managed-settings.json

当前没有这份 managed settings，且 Sol 已在 availableModels 中。即使额外启用 enforcement，Default 通过 Opus 映射到 Sol 后仍属于允许目标，结果不会改变。

本机顶层 model 已设为 haiku，因此新会话默认启动 Haiku 家族入口，并实际路由到 Luna。只要不主动选择 Default，它只是一个保留入口，不会影响当前默认选择。

官方依据：

• 模型别名与 Default 的定义
• Default 的账号类型决策表
• Default 与 availableModels 的关系
• 用 enforceAvailableModels 约束 Default
• 组织默认模型
• 1M 上下文规则

四个家族映射

ANTHROPIC_BASE_URL 只回答“请求发到哪里”；availableModels 只回答“哪些入口允许被选择”。它们都不会自动建立下面的关系：

Claude Code 内置家族入口 → 网关实际接受的模型 ID

当前映射为：

Fable → gpt-5.6-sol
Opus   → gpt-5.6-sol
Sonnet → gpt-5.6-terra
Haiku  → gpt-5.6-luna

ANTHROPIC_DEFAULT_FABLE_MODEL 与另外三个 DEFAULT 变量属于同一类配置：都把一个 Claude Code 内置家族入口固定到供应商或网关使用的模型 ID。差别在于入口的语义和 Claude Code 内部使用场景：

所以，Fable 和 Opus 同时映射到 Sol 并不冲突。它表示 Claude Code 仍保留两个不同的家族语义入口，但它们最终向 CLIProxyAPI 发送相同的 model ID。

Fable 是 Claude Code 2.1.227 已识别的内置模型家族。Anthropic 当前官方文档已经列出 fable 别名、ANTHROPIC_DEFAULT_FABLE_MODEL，以及对应的 NAME、DESCRIPTION、SUPPORTED_CAPABILITIES 配置。官方同时明确：Fable 5 不是任何账号类型的 Default，需要显式选择；Claude Code 2.1.170 以前的版本不显示也不能选择 Fable 5。

这四个变量更准确的名称是“家族别名目标”或“供应商模型 ID 固定项”，而不是四个任意 Custom Model 槽位。真正的任意 Custom Model 入口仍只有一个，由 ANTHROPIC_CUSTOM_MODEL_OPTION 提供。

其他模型配置

model

顶层 model 指定新会话的初始模型。当前为 haiku，对应 Haiku 家族入口，实际路由到 gpt-5.6-luna。

它不是强制策略。进入会话后仍可通过 /model 切换；是否把选择保存为新默认值，要看选择器操作。

availableModels

当前已经启用：

[
  "fable",
  "gpt-5.6-sol",
  "gpt-5.6-terra",
  "gpt-5.6-luna",
  "grok-4.6"
]

它不只是界面隐藏器，而是允许列表，会限制可以选择的命名模型入口。Default 是特殊项：availableModels 单独不会限制它；只有 managed settings 同时设置非空白名单和 enforceAvailableModels: true 时，Default 的解析结果才会受约束，但这一行仍不会消失。

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY

当前未配置，也就是关闭。

这样做的目的不是让 CLIProxyAPI 停止提供 /v1/models，而是让 Claude Code 不再把网关目录合并进 /model。当前需要的四个家族入口和 Grok Custom Model 都已显式配置，因此不依赖发现也能使用。

ANTHROPIC_CUSTOM_MODEL_OPTION

当前用于 Grok 4.6：

ANTHROPIC_CUSTOM_MODEL_OPTION=grok-4.6
ANTHROPIC_CUSTOM_MODEL_OPTION_NAME=Grok 4.6

它只提供一个自定义条目。Claude Code 会跳过这个条目的模型 ID 校验，直接把 grok-4.6 发送给网关。

MODEL_NAME 和 MODEL_DESCRIPTION

四个家族映射都可以有配套的 NAME、DESCRIPTION，例如：

ANTHROPIC_DEFAULT_FABLE_MODEL_NAME
ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION
ANTHROPIC_DEFAULT_OPUS_MODEL_NAME
ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION

Sonnet、Haiku 也有同样后缀。它们只修改选择器中的展示文本，不改变实际路由。当前除了 Grok 的 Custom Model NAME 外，其余 NAME、DESCRIPTION 都没有配置。

MODEL_SUPPORTED_CAPABILITIES

Fable、Opus、Sonnet、Haiku 与 Custom Model 都有对应的 SUPPORTED_CAPABILITIES 配置，可用于声明 effort、thinking 等能力。

当前没有配置这些变量，而是依赖 Claude Code 根据模型 ID 和所在入口进行内置判断。只有遇到自定义 ID 无法启用本应支持的功能时，才值得补充。

modelOverrides

modelOverrides 把具体 Anthropic 模型版本映射成供应商 ID。它解决的是“多个具体版本分别路由到哪里”，不是模型列表裁剪。

当前只需要每个家族一个目标，四个 ANTHROPIC_DEFAULT_*_MODEL 已经足够，因此没有启用。

apiKeyHelper

apiKeyHelper 可以通过脚本动态取得 API key。

本机使用固定的 CLIProxyAPI 入口密钥，直接配置 ANTHROPIC_AUTH_TOKEN 更简单，因此已经移除 helper。

3. 网关模型发现、ID 伪装与重复项

模型发现实际做了什么

当前已经删除 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY，因此 Claude Code 不会把 CLIProxyAPI 的 /v1/models 返回项作为 From gateway 条目加入 /model。

如果将来重新设置：

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

Claude Code 才会在启动阶段尝试请求：

GET /v1/models?limit=1000

这个请求有超时限制；发现开关只负责启动请求，不负责选择具体模型。

CLIProxyAPI 当前向普通 OpenAI 风格客户端公布六个模型：

gpt-5.6-sol
gpt-5.6-terra
gpt-5.6-luna
gpt-image-2
grok-4.5
grok-4.6

当请求带有 Claude Code/Anthropic 特征头时，CLIProxyAPI 会把这些模型转换成 Anthropic 风格目录，并给非 Claude 模型生成包含 claude 的伪装 ID。这样做是为了让它们通过 Claude Code 的发现过滤。具体转换过程见下文的 Header 识别、ID 伪装与还原部分。

当前 availableModels 为：

[
  "fable",
  "gpt-5.6-sol",
  "gpt-5.6-terra",
  "gpt-5.6-luna",
  "grok-4.6"
]

它有两个直接结果：

1. 保留 Fable、Sol、Terra、Luna 以及 Grok 4.6 这些入口；
2. 不允许 gpt-image-2，也不保留此前由发现流程产生的 From gateway 重复项。

以前的发现缓存位于：

~/.claude/cache/gateway-models.json

它是派生状态，不应手工维护。关闭发现后，即使旧缓存文件仍存在，也不应把它理解成当前模型配置的来源。

CLIProxyAPI 侧的模型裁剪主要发生在各 OAuth 凭据 JSON 的 excluded_models 字段中。CLIProxyAPI 主配置里的全局 oauth-excluded-models 当前没有启用。

CLIProxyAPI 如何识别 Claude Code 请求

准确地说，它识别的不是“客户端身份”，而是“请求是否带有 Anthropic/Claude Code 特征”。

CLIProxyAPI 的 /v1/models 是统一入口。收到请求后，它检查：

如果存在 Anthropic-Version 请求头
或者 User-Agent 以 claude-cli 开头
    → 进入 Anthropic 模型列表处理
否则
    → 进入 OpenAI 模型列表处理

对应源码：

• 请求头判断与路由分流
• 模型列表和 ID 伪装
• 收到模型请求后的解码

Anthropic-Version 和 User-Agent 都能由客户端自行构造，所以这不是安全意义上的身份认证。任何客户端只要满足相同条件，也会收到 Anthropic 风格响应。

同一个 /v1/models 为什么返回两种 ID

不满足上述 Anthropic 判断条件的请求，会得到 OpenAI 风格响应和原始 ID：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol"
    }
  ]
}

进入 Anthropic 分支后，CLIProxyAPI 默认把不以 claude- 开头的 ID 改写为：

claude-fable-5-dd- + 原始 ID 的字符反转

例如：

gpt-5.6-sol
    ↓ 字符反转
los-6.5-tpg
    ↓ 加前缀
claude-fable-5-dd-los-6.5-tpg

返回条目是：

{
  "id": "claude-fable-5-dd-los-6.5-tpg",
  "display_name": "GPT 5.6 Sol"
}

Claude Code 的选择器优先显示 display_name，所以用户看到 GPT 5.6 Sol；内部用于发现和请求的则是 claude-fable-* ID。

为什么伪装以及如何还原 ID

Claude Code 2.1.227 只保留 ID 中包含 claude 或 anthropic 的发现项。原始 gpt-* 和 grok-* ID 都不满足条件，无法直接进入发现结果。

CLIProxyAPI 因此做了一次可逆转换：

发现模型时：
gpt-5.6-sol
→ claude-fable-5-dd-los-6.5-tpg

真正调用时：
claude-fable-5-dd-los-6.5-tpg
→ gpt-5.6-sol

完整过程：

1. Claude Code 启动时请求 /v1/models?limit=1000
2. 请求头让 CLIProxyAPI 进入 Anthropic 模型列表处理
3. CLIProxyAPI 返回带 claude-fable-* ID 和正常 display_name 的模型目录
4. Claude Code 保留这些包含 claude 的 ID，并加入 /model 选择器
5. 用户选择模型后，Claude Code 向 /v1/messages 提交伪装 ID
6. CLIProxyAPI 把伪装 ID 还原为 gpt-* 或 grok-*
7. CLIProxyAPI 选择相应 OAuth 凭据并调用真实模型

所以，同一个 /v1/models 地址可以返回不同 ID：请求地址相同，但请求头触发了不同处理分支。

能否关闭 ID 伪装

CLIProxyAPI 提供：

claude-code:
  disable-cloaking-model-list: true

当前配置没有显式写出该项，因此使用默认值 false，也就是启用伪装。

如果改成 true，Anthropic 风格的 /v1/models 会返回 gpt-、grok- 原始 ID。由于这些 ID 不含 claude 或 anthropic，Claude Code 2.1.227 会在发现阶段忽略它们，所以当前场景不应关闭。

重复模型从哪里来

此前的重复来自两套入口同时开启：

家族映射条目
+ From gateway 发现条目

两边虽然最终路由到同一个模型，但 Claude Code 看到的内部 ID 不同：

家族映射使用：
gpt-5.6-sol
gpt-5.6-terra

网关发现使用：
claude-fable-5-dd-los-6.5-tpg
claude-fable-5-dd-arret-6.5-tpg

因此它无法知道两组 ID 最终会被 CLIProxyAPI 还原到同一个模型，也就不能可靠去重。

当前已经关闭网关发现，所以 From gateway 的 Sol、Terra、Luna、Grok 和 Image 2 不再进入选择器。Grok 4.6 只通过 Custom Model 出现，Image 2 被 availableModels 排除。

还有一种看起来相似、但性质不同的情况：Fable 和 Opus 都映射到 gpt-5.6-sol。这是两个内置家族入口主动共用同一个目标，不是网关发现造成的重复。不同 Claude Code 版本可能把相同目标折叠，也可能分别保留家族入口；无论界面显示几行，实际请求都只会发送一次。

为什么 Opus 排在 Fable 前面

这不是能力排名，也不取决于 availableModels 的数组顺序。Claude Code 会优先展示 Default 当前所属的家族入口；本机 Default 属于 Opus，因此顺序是 Default → Opus → Fable。当前没有受支持的模型选择器排序配置，调整 availableModels 或环境变量的书写顺序也不会交换这两项。

4. Fast 模式如何转换为 Priority tier

/fast 改变的是推理速度配置

Claude Code 的 Fast 模式不是一个独立模型，也不等同于降低 effort。开启后，Claude Code 会使用支持 Fast 的默认 Opus，并在 Anthropic Messages 请求中加入：

{
  "speed": "fast"
}

如果当前使用的不是支持 Fast 的 Opus，Claude Code 会先切换到默认 Opus。Claude Code 2.1.219 及以后把这个内置目标显示为 Opus 5。

effort 和 Fast 是两条独立轴线：

两者可以组合，例如同时使用 xhigh effort 和 Fast。

为什么显示 Opus 5，实际却是 gpt-5.6-sol

ANTHROPIC_DEFAULT_OPUS_MODEL 不是只替换一个字面量叫 opus 的模型，而是指定“默认 Opus 家族槽位”最终使用哪个供应商模型 ID。

当前配置为：

ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-sol

因此，本机的解析过程是：

/fast on
→ Claude Code 选择默认 Opus
→ 界面按内置版本显示 Opus 5
→ Opus 家族固定项解析为 gpt-5.6-sol
→ 请求实际发送 model: gpt-5.6-sol

实测会话记录中，同一条回答同时出现了：

{
  "model": "gpt-5.6-sol",
  "text": "现在是 Claude Opus 5（Fast mode）……"
}

结构化的 model 字段和底部状态栏反映实际请求模型；模型在自然语言中“自报家门”并不可靠。界面里的 Opus 5、Fast 官方价格等文字属于 Claude Code 的内置展示语义，不代表 CLIProxyAPI 最终调用了 Anthropic Opus 5，也不代表 Codex 订阅会按界面展示的 Anthropic 单价计费。

如果以后需要分别映射多个具体 Opus 版本，应使用 modelOverrides。当前只需要一个默认 Opus 目标，所以 family 级的 ANTHROPIC_DEFAULT_OPUS_MODEL 已经够用。

为什么最初会提示组织禁用

在允许打开 Fast 之前，Claude Code 会检查 Anthropic 组织是否具备 Fast 权限。这个检查直接访问 api.anthropic.com，不遵循 ANTHROPIC_BASE_URL。

本机只使用 CLIProxyAPI 签发的 ANTHROPIC_AUTH_TOKEN。这个 token 对本机网关有效，但不是 Anthropic API key，Claude Code 无法用它确认 Anthropic 组织权限。在没有可复用的成功缓存时，Claude Code 会把这种情况按“组织未启用 Fast”处理，并在请求到达 CLIProxyAPI 之前就拦截 /fast。

网关场景对应的配置是：

{
  "CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK": "1"
}

它只跳过 Claude Code 客户端的组织检查，不会修改模型，也不会自行产生加速效果。真正的 Fast 请求仍需网关理解 speed 字段。

CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS 只适用于权限检查确实发出、但因网络或凭据拒绝而失败的情况；它不能代替当前使用的组织检查跳过项。

官方说明：

• Claude Code Fast mode
• 通过代理和 LLM 网关使用 Fast mode
• Claude Code 模型别名与固定项

CLIProxyAPI 如何接住 speed: fast

Claude Code 通过客户端检查后，请求会进入 CLIProxyAPI。当前源码把 Anthropic 请求中的 Fast 配置转换为 Codex 的 Priority tier：

speed: "fast"
→ service_tier: "priority"

对应源码：

• Claude → Codex 请求转换中的 Fast 映射

完整链路是：

/fast on
→ 跳过不适用于本机网关凭据的 Anthropic 组织检查
→ Claude Code 选择默认 Opus
→ ANTHROPIC_DEFAULT_OPUS_MODEL 解析为 gpt-5.6-sol
→ /v1/messages 携带 model: gpt-5.6-sol 和 speed: fast
→ CLIProxyAPI 转换为 service_tier: priority
→ Codex OAuth 凭据调用 Priority tier

Fast 状态如何保存

默认情况下，在交互会话中执行 /fast on 会把偏好保存为顶层配置：

{
  "fastMode": true
}

所以重启 Claude Code 后，Fast 仍会保持开启。它与 CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK 的职责不同：

5. Effort 在 Claude Code、CLIProxyAPI 与 Codex 之间如何对应

这条链路中的 effort 分为三层：

• Codex CLI 负责“模型 effort + Codex 自己的 Agent 编排”；
• CLIProxyAPI 负责把 Claude 协议的 output_config.effort 转成 Codex 协议的 reasoning.effort；
• Claude Code 负责提供 /effort 选择，并执行 Claude Code 自己的动态工作流。

对当前 Sol、Terra、Luna，最常用的五档是直接对应的：

Codex 原生模型目录还有以下差异：

CLIProxyAPI 当前为这三个模型登记的是 low / medium / high / xhigh / max，不包含 ultra。它内部还能识别 none / auto / minimal 作为归一化输入：对当前三个模型，none 和 minimal 最终落到 low，直接传给网关的 auto 落到 medium。

但 Claude Code 的 /effort auto 不是把 auto 原样发送给网关。对当前这些自定义 GPT 模型，Claude Code 2.1.227 会先解析成 high，再发送给 CLIProxyAPI。因此 Claude Code 的 auto 不会采用 Sol 的原生默认 low，也不会采用 Terra、Luna 的原生默认 medium。

Max、Ultra 与 Ultracode

三者不能直接画等号：

Codex max
= reasoning.effort=max

Codex ultra
= reasoning.effort=max
+ Codex proactive multi-agent 编排

Claude Code ultracode
= reasoning.effort=xhigh
+ Claude Code dynamic workflow 编排

Claude Code 2.1.227 把 ultracode 的 effort 固定为 xhigh，目前没有受支持的配置项可以把它改成 max。选择 /effort max 只会提高模型 effort，不会启用 ultracode 编排；选择 /effort ultracode 则会保持 xhigh 并启用动态工作流。

即使修改 Claude Code 本身，把 ultracode 改成 max，它也只会在结构上接近 Codex ultra；两边的 Agent 触发条件、任务拆分、提示词和上下文管理仍由不同 harness 实现。

当前用户配置保存的是 effortLevel: xhigh。当选择 Sol、Terra 或 Luna 时，实际链路为：

Claude Code xhigh
→ CLIProxyAPI xhigh
→ Codex reasoning.effort=xhigh

/fast 是另一条独立维度，只控制服务优先级，不改变上述 effort 对应关系。

6. 上下文窗口与自动压缩

Codex 的 272K、258.4K 与 244.8K

这几个数字属于不同层次，不能把它们都理解成“GPT-5.6 的上下文上限”。最关键的区别是：1.05M 是上游 API 能力，272K 是当前 Codex 产品目录采用的工作档位，258.4K 和 244.8K 则是 Codex 客户端基于 272K 继续计算出的本地阈值。

关系可以简化为：

GPT-5.6 API 总窗口：1.05M
├─ 最大输出：128K
└─ 留足最大输出后的输入预算：922K

Codex 当前产品档位：272K
├─ 默认自动压缩线：244.8K（272K × 90%）
└─ 本地可用窗口保护线：258.4K（272K × 95%）

258.4K 到底有什么用

258.4K 不只是状态栏中的显示数字。Codex 源码把它作为本地 usable context window，主要用于：

1. 当前活动上下文达到 258.4K 时，强制进入自动压缩流程；
2. 切换到更小窗口的模型时，判断现有历史是否必须先压缩；
3. 远程压缩前，如果历史估算仍超过 258.4K，优先缩短部分工具调用输出；
4. 作为 TUI 和 App Server 展示上下文窗口、计算剩余百分比的分母；
5. 后端返回 context_length_exceeded 时，把本地 Token 使用状态标记为窗口已满。

不过，在默认的 Total 计数模式下，244.8K 自动压缩线通常会先触发。因此，258.4K 很少成为正常会话中的第一个触发点，更像是完整窗口的兜底保护线和统一显示基准。这也是为什么实际使用时会感觉 258K 本身没有明显作用。

258.4K 不会作为新的模型参数发给 OpenAI，也不代表 CLIProxyAPI 或 GPT-5.6 只能接收 258.4K。它首先是 Codex harness 自己的上下文管理策略。

为什么 Codex 状态栏显示 258K window

Codex 把计算后的 effective window 以 model_context_window 字段传给 TUI，因此状态栏展示的是 258K，而不是模型目录中的 272K，更不是 GPT-5.6 API 的 1.05M。

所以，这行界面文字更准确的理解是：

Codex 当前采用的本地可用上下文窗口：258.4K

而不是：

GPT-5.6 的真实 API 上下文硬上限：258.4K

272K 直发测试能证明什么

本机已经验证：一条报告 input_tokens 为 272000 的请求可以经过 Claude /v1/messages → CLIProxyAPI → gpt-5.6-sol 并正常返回。

这个结果只能证明当前路由接受了这一请求点，不能单独证明：

• 272K 是模型硬上限；
• 922K 一定能完整通过 CLIProxyAPI；
• 转换过程中绝对没有截断；
• 模型能在超长输入的任意位置稳定检索信息。

若要验证 272K 以上乃至接近 922K 的能力，需要捕获实际发给上游的原始请求，并在文本开头、中间和结尾放置随机针进行检索测试。

资料：

• OpenAI GPT-5.6 Sol 模型页
• Codex 修正 272K 模型元数据的 PR #34009
• Codex 模型目录中的 272K 配置
• Codex 的 95% effective window 定义
• Codex 的 258.4K 计算
• Codex 的压缩阈值与完整窗口保护逻辑

Claude Code 的 272K、33K 与 239K

当前配置是：

{
  "autoCompactEnabled": true,
  "env": {
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "272000"
  }
}

另外两项当前没有配置：

• autoCompactWindow 未配置，表示使用 auto；
• CLAUDE_CODE_MAX_OUTPUT_TOKENS 未配置，因此 gpt-5.6-sol 这类未知模型 ID 使用 Claude Code 的默认最大输出值 32K。

272K、33K 和 239K 分别是什么

Claude Code 2.1.228 对当前未知模型的计算是：

模型上下文窗口：272K
Autocompact buffer：33K
实际自动压缩线：272K - 33K = 239K

/context 显示的 Auto-compact window: 272k 是自动压缩计算使用的基准窗口，不是最终触发压缩的位置。界面中的各项满足：

已使用 + Free space + Autocompact buffer = 272K

当前 33K buffer 也不是用户直接配置的，它由 Claude Code 自动组成：

输出预留：min(默认最大输出 32K, 20K) = 20K
压缩安全预留：13K
Autocompact buffer：20K + 13K = 33K

因此，当前真正允许对话历史增长到的自动压缩线约为 239K。这里的 13K 是 Claude Code 2.1.228 的内部预留，没有对应的受支持配置项。

auto 模式如何取值

autoCompactWindow 使用 auto 时，Claude Code 大致按以下优先级确定基准窗口：

1. CLAUDE_CODE_AUTO_COMPACT_WINDOW；
2. settings.json 中显式设置的 autoCompactWindow；
3. 服务端缓存或实验值；
4. 已识别模型的内置窗口；
5. 当前模型上下文窗口。

gpt-5.6-sol 对 Claude Code 来说是未知的非 Claude 模型 ID，所以本机最后采用 CLAUDE_CODE_MAX_CONTEXT_TOKENS=272000。执行 /autocompact auto 可以恢复这一自动选择。

手动控制压缩时机

CLAUDE_CODE_MAX_CONTEXT_TOKENS 表示模型容量，不应拿来当压缩旋钮。需要提前压缩时，应执行：

/autocompact N

或设置 autoCompactWindow: N。但 N 仍然是基准窗口，实际压缩线还会扣除 buffer：

实际压缩线 = autoCompactWindow - Autocompact buffer

例如，在当前 33K buffer 下，希望约 220K 时压缩，应设置：

/autocompact 253000

即 253K - 33K = 220K。显式窗口还会被模型上下文窗口封顶；当前模型容量为 272K，所以保持默认输出预留时，最晚只能在约 239K 自动压缩。若目标只是尽可能晚压缩，继续使用 auto 即可。

与 Codex 压缩线的比较

两套 harness 使用不同策略：

两者相差约 5.8K，只占 272K 的约 2.1%。Claude Code 的 239K 与 Codex 的 258.4K 也不是同层数字：239K 是自动压缩线，258.4K 是 Codex 的 effective window 保护线。

若一定要让 Claude Code 精确对齐 Codex 的 244.8K，按照当前实现需要把 CLAUDE_CODE_MAX_OUTPUT_TOKENS 设为 14200：

272K - 14.2K - 13K = 244.8K

这样会把 Claude Code 的单次最大输出限制为 14.2K。为了只获得 5.8K 的额外历史空间而牺牲输出上限并不划算，因此当前保持约 239K 更稳妥。也不应把模型窗口虚报为 277.8K 来对齐压缩线。

当前建议

保持：

CLAUDE_CODE_MAX_CONTEXT_TOKENS=272000
autoCompactEnabled=true
autoCompactWindow=auto
CLAUDE_CODE_MAX_OUTPUT_TOKENS 未配置

这表示 Claude Code 正确认识当前 Codex 产品档位为 272K，并在约 239K 主动压缩，同时保留未知模型默认的 32K 单次输出上限。

资料：

• Claude Code：修正网关或自定义模型 ID 的上下文窗口
• Claude Code：设置自动压缩窗口
• Claude Code 环境变量

7. Claude Code 内置 Skills：1 + 1 + N

Claude Code 2.1.228 的内置 Skills 并不是完全同构的一组。按注册和控制方式，可以概括为“1 + 1 + N”：

这里的“N”表示第三类包含多个普通内置 Skill，而不是还有一个名为“N”的 Skill。

两个特殊 Skill 的运行时 frontmatter

这两个特殊 Skill 并没有以独立的 SKILL.md 文件安装到磁盘，而是直接注册在 Claude Code 二进制中。因此，严格来说它们没有可读取的 YAML frontmatter。下面根据本机 Claude Code 2.1.229 的实际注册对象，将字段还原成等价的 YAML 形式。

字段名 menuDescription、allowedTools、userInvocable 和 argumentHint 保留二进制中的真实写法；description 内容忠实翻译成中文。

claude-api

---
name: claude-api

menuDescription: >
  构建和调试使用 Claude API 的应用。

description: >
  Claude API / Anthropic SDK 参考资料，包括模型 ID、价格、参数、
  流式传输、工具调用、MCP、Agent、缓存、Token 统计和模型迁移。

  触发条件：必须在打开目标文件之前读取该 Skill。
  不要因为任务“看起来只改一行”就跳过。当出现以下情况时触发：

  1. Prompt 以任何形式提到 Claude 或 Anthropic，包括 Claude、
     Anthropic、Fable、Opus、Sonnet、Haiku、anthropic、
     @anthropic-ai、claude-*、us.anthropic.*、[1m]；
  2. 用户询问 LLM 的价格、模型选择、限制或缓存；
     不允许依靠记忆回答；
  3. 任务明显属于 LLM 应用，但没有指定提供商，例如 Agent、
     MCP、工具定义、多 Agent、RAG、LLM Judge、Computer Use，
     或自然语言的生成、摘要、提取、分类、改写、对话，以及
     refusal、输出截断、流式响应、工具调用、Token 等问题的调试。

  仅当任务明确使用其他提供商时跳过，而且该规则优先于所有触发条件：

  1. 查询中明确提到 OpenAI、GPT、Gemini、Llama、Mistral、
     Cohere 或 Ollama；
  2. 在项目中搜索 openai、langchain_openai、
     google.generativeai、genai、mistralai、cohere、ollama
     后发现命中。如果用户没有指定提供商，必须先执行搜索，
     不要先读取目标文件。

allowedTools:
  - Read
  - Grep
  - Glob
  - WebFetch

userInvocable: true
---

它没有配置 argumentHint。用户可以手动执行 /claude-api，模型默认也可以根据 description 自动调用。调用时，它会根据项目根目录第一层的语言标志文件选择 Python、TypeScript、Java、Go、Ruby、C# 或 PHP 文档。

其实际运行时注册还包含动态的 files 和 isEnabled 函数；专属内部禁用开关是：

CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL

claude-code-docs

---
name: claude-code-docs

menuDescription: >
  回答有关 Claude Code 功能和设置的问题。

description: >
  回答有关 Claude Code 自身的问题，包括命令、CLI 参数、设置、
  Hooks、Skills、MCP Server、子 Agent、IDE 集成、沙箱、部署，
  以及 Claude Tag（Claude in Slack）。

  在推荐任何命令、CLI 参数或配置项之前，先根据当前正在运行的
  Claude Code 版本进行验证。

  在以下情况下触发：

  1. 用户询问 Claude Code 如何工作，例如“Claude 能不能……”
     “Claude 是否支持……”“我该如何……”“有没有办法……”；
  2. 用户询问斜杠命令、CLI 参数、配置项、Hook、Skill、
     MCP Server、子 Agent、快捷键或 .claude/ 目录；
  3. 用户希望配置、自定义或排查 Claude Code；
  4. 用户询问 Claude in Slack 或 Claude Tag，例如
     “Claude Tag 是什么”“Claude 能否加入 Slack”
     “Slack 里的 @Claude”“/install-slack-app”
     “如何为 Slack 工作区配置 Claude”；
  5. Claude 即将推荐某个 Claude Code 命令、CLI 参数或配置项，
     但尚未确认当前版本确实支持它。

  以下情况跳过：

  1. 构建使用 Claude API 或 Anthropic SDK 的应用；
     这种情况使用 /claude-api；
  2. 一般性的编程问题；
  3. 有关用户自己代码库的问题。

allowedTools:
  - Read
  - Grep
  - Glob
  - WebFetch

argumentHint: "[question]"
userInvocable: true
---

它同样包含动态的 files 和 isEnabled 函数，理论上可以通过 /claude-code-docs [question] 手动调用。除了专属禁用开关，它还受到内部功能开关 tengu_birch_kettle 控制，因此不保证对每个用户或每个版本开放。

专属内部禁用开关是：

CLAUDE_CODE_DISABLE_CLAUDE_CODE_SKILL

两者的职责边界可以简化为：

claude-api
→ 如何使用 Claude API / Anthropic SDK 开发应用

claude-code-docs
→ 如何配置和使用 Claude Code 这个工具本身

为什么 claude-api 容易撑满上下文

claude-api 的常驻元数据很小，真正占用上下文的是手动或自动调用后加载的 API / SDK 正文。Claude Code 会尝试根据当前项目根目录的一层语言标志文件选择文档；如果工作目录是包含很多仓库的上层目录，且该层没有明确语言标志，它可能无法缩小语言范围，从而加载多套文档。

本机曾在 /Users/alfheim/code/oss 启动 Claude Code 后触发该 Skill，出现：

Context limit reached
/compact or /clear to continue

而在明确的 Go 仓库中调用时，只加载 Go 相关资料，虽然仍然很大，但可以放进当前 272K 窗口。因此，这不是 CLIProxyAPI 的协议转换错误，而是 Claude Code harness 在调用超大内置 Skill 时消耗了本地上下文预算。

控制方式与界面差异

常规、受支持的单项控制入口是顶层 skillOverrides。常见状态包括：

普通内置 Skills 还可以通过 disableBundledSkills 整组控制。当前二进制内部也存在 CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL 和 CLAUDE_CODE_DISABLE_CLAUDE_CODE_SKILL 两个专用环境变量，但它们没有进入官方文档，属于内部开关，不应作为首选配置接口。

还要注意：官方内置的 claude-api 已注册时，可以在 /context 的 Skills 列表和斜杠命令补全中看到，却不一定出现在 /skills 管理列表。本机 2.1.228 已实测：

/context
→ claude-api | Built-in | ~360

输入 /claude-api
→ 出现 “Reference for the Claude API / Anthropic SDK” 命令补全

/skills 中搜索 claude
→ No skills match "claude"

这三个结果并不矛盾：/skills 并不是所有特殊内置 Skill 的完整注册表。判断 claude-api 是否可用，应优先查看 /context 或直接输入 /claude-api 看命令补全。

最终解决方案：禁止自动触发，保留手动调用

最终采用用户级配置，在 ~/.claude/settings.json 中设置：

{
  "skillOverrides": {
    "claude-api": "user-invocable-only"
  }
}

实际效果：

• 对本机用户的所有项目生效；
• 不再把 claude-api 的名称和描述提供给模型，因此 Claude Code 不会自动触发它；
• 仍保留 /claude-api 斜杠命令，需要时可以由用户手动调用；
• 避免在语言识别失败时自动加载全部 API / SDK 文档并撑爆 272K 上下文；
• 不使用未公开的 CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL 内部环境变量。

当前 /Users/alfheim/code/oss/.claude/settings.local.json 中的 skillOverrides 是空对象，不会取消上面的用户级配置。只有更高优先级的项目配置以后显式写入 "claude-api": "on"、"off" 或其他状态时，才会覆盖这个全局选择。

修改后执行 /reload-skills，或重启 Claude Code。验证标准是：/context 不再把 claude-api 列为可供模型选择的 Skill，但输入 /claude-api 时仍然可以看到并手动执行该命令。

8. 如何验证当前配置

修改 settings.json 后，应彻底退出旧的 Claude Code 进程，再启动新会话。旧会话不会自动重新读取全部环境配置。

静态检查

jq '{
  model,
  effortLevel,
  availableModels,
  mappings: {
    fable: .env.ANTHROPIC_DEFAULT_FABLE_MODEL,
    opus: .env.ANTHROPIC_DEFAULT_OPUS_MODEL,
    sonnet: .env.ANTHROPIC_DEFAULT_SONNET_MODEL,
    haiku: .env.ANTHROPIC_DEFAULT_HAIKU_MODEL,
    custom: .env.ANTHROPIC_CUSTOM_MODEL_OPTION,
    subagent: .env.CLAUDE_CODE_SUBAGENT_MODEL
  },
  gatewayDiscovery: .env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY
}' ~/.claude/settings.json

预期：

• Fable 和 Opus 都是 gpt-5.6-sol；
• Sonnet 是 gpt-5.6-terra；
• Haiku 是 gpt-5.6-luna；
• Custom Model 是 grok-4.6；
• 子 Agent 是 gpt-5.6-terra；
• gatewayDiscovery 为 null，表示没有配置发现开关。

Claude Code 内验证

执行：

/model
/status

重点确认：

• 不再出现 From gateway 条目；
• 不再出现 GPT Image 2；
• Fable 与 Opus 入口最终指向 gpt-5.6-sol；
• Sonnet 指向 gpt-5.6-terra；
• Haiku 指向 gpt-5.6-luna；
• Grok 4.6 显示为 Custom Model，并能正常收到响应；
• 子 Agent 使用 gpt-5.6-terra。

Fast 链路验证

执行：

/fast on
/model
/status

预期：

• Claude Code 切换到默认 Opus 入口；
• 实际模型 ID 为 gpt-5.6-sol；
• 请求携带 speed: fast；
• CLIProxyAPI 转换为 service_tier: priority。

不要用“你是什么模型”作为验证依据。自然语言自报模型可能沿用 Claude Code 的内置家族语义；应以 /status、会话结构化 model 字段和网关日志为准。

9. 维护检查

• 发现开关与“发现哪些模型”已经分开
• 当前关闭网关发现的状态已经同步
• Fable、Opus、Sonnet、Haiku 四个家族映射已经补齐
• Fable 与另外三个 DEFAULT 配置的同类关系及差异已经说明
• Custom Grok、availableModels 与 gpt-image-2 过滤已经同步
• /model 在本机 2.1.227 中的保存行为已经核对
• Default 的账号类型决策、Opus → Sol[1m] 链路与不可隐藏边界已经核对
• header 分流、ID 编码和请求解码已经核对源码
• /fast 的客户端检查、Opus 映射和 Priority tier 转换已经核对
• 完整密钥、OAuth token 和账号隐私没有写入正文
• 内置 Skills 的 1 + 1 + N 分类、claude-api 上下文风险与界面差异已经记录
• claude-api 与 claude-code-docs 的 2.1.229 运行时 frontmatter 等价字段已经记录
• claude-api 最终采用 user-invocable-only：禁止自动触发并保留手动调用
• status 保持为 published，draft 保持为 false