Model Config

本文从概念和使用方式的角度，说明如何为不同的模型使用场景（槽位）分别配置模型名、Auth（provider）、Wire API 和采样参数。重点是"怎么用、有什么效果、常见怎么配"，配置字段的完整参考见子文档 Model Slot Overrides 配置说明

核心概念

模型槽位（Slot）

Codely 把模型使用场景拆成 4 个独立槽位，每个槽位可以有自己的模型、Auth、Wire API 和采样参数：

槽位	用途	默认模型
`model`（Main）	主对话模型	codely-core
`flashModel`（Flash）	快速/内部模型：JSON 生成、压缩、下一步判断等	codely-flash
`multimodalModel`（Multimodal）	多媒体分析（图片/视频/音频）	codely-vl
`defaultAgentModel`（Agent）	默认 Agent / Subagent 模型	codely-air

两个正交的维度：Auth 与 Wire API

Auth（authType） 决定用哪个 provider 的凭证、baseUrl、模型列表来源。
Wire API（wireApi） 决定请求的投影/传输格式：
- chat → OpenAI Chat Completions 风格，codely 默认为 chat
- responses → OpenAI Responses API 风格
- messages → Anthropic Messages 风格

这两者是独立配置项，但共同决定一个槽位实际使用的 provider runtime。effective 配置相同的槽位会复用同一个底层连接；不同则各自独立。

继承关系

contentGenerator 顶层是全局默认，contentGenerator.overrides.<slot> 是槽位覆盖。槽位没配的字段继承全局；全局没配的走内置默认（见下文）。

Wire API 的默认行为

如果完全没有配置 wireApi，codely 默认 chat：

Anthropic 认证 → 默认 messages
其他认证 → 默认 chat

最常见用法：只用命令行参数，不持久化 ⭐

绝大多数情况下你不需要写任何 settings 文件。 直接用命令行参数临时指定 Wire API 即可，只影响当前这次运行，不会写回任何配置文件：

# 让主模型用 Anthropic Messages 格式
codely --wire-api messages

# 让主模型用 OpenAI Responses 格式
codely --wire-api responses

# 别名同样可用
codely --wire_api responses

效果：--wire-api 作用于主槽位（model）的会话级覆盖。已经在 settings 中为某个槽位单独配置了 wireApi 的槽位不受该命令行参数影响。

也可以同时临时切换 Auth（需要 CUSTOM_AUTH=1，见下节）：

codely --auth anthropic --wire-api messages
codely --auth openai --wire-api responses

这是推荐的"轻量"用法：配置不落盘，换一个 provider/格式只是换一行命令。

启用非默认 Provider：必须设置 `CUSTOM_AUTH=1`

默认情况下，Codely 只允许 codely-oauth。一旦你要使用任何其他 provider（openai / anthropic / qwen-oauth / gemini-api-key / vertex-ai），必须设置环境变量 CUSTOM_AUTH=1，否则启动会报错：

--auth-type="openai" requires CUSTOM_AUTH to be set (e.g. CUSTOM_AUTH=1).

在 `.codely-cli/.env` 中写变量（推荐）

把 CUSTOM_AUTH=1 和各 provider 的凭证写进 .codely-cli/.env，Codely 启动时会自动加载。查找顺序：从当前目录逐级向上找 .codely-cli/.env（其次 ./.env），最后回退到 ~/.codely-cli/.env（其次 ~/.env）。

# .codely-cli/.env  —— 必须有这一行才能用非默认 provider
CUSTOM_AUTH=1

# OpenAI 兼容 provider
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1

# Anthropic 兼容 provider
ANTHROPIC_AUTH_TOKEN=sk-ant-xxx
ANTHROPIC_BASE_URL=https://your-anthropic-compatible-endpoint

# Gemini / Vertex
GEMINI_API_KEY=xxx
GOOGLE_API_KEY=xxx

各 authType 对应读取的环境变量：

authType	凭证环境变量	baseUrl 环境变量
`openai`	`OPENAI_API_KEY`	`OPENAI_BASE_URL`
`anthropic`	`ANTHROPIC_AUTH_TOKEN`	`ANTHROPIC_BASE_URL`
`gemini-api-key`	`GEMINI_API_KEY`	—
`vertex-ai`	`GOOGLE_API_KEY`	—
`qwen-oauth`	OAuth 动态 token	—
`codely-oauth`	OAuth 动态 token	Codely 默认网关，不必额外配置

放在工作区 .codely-cli/.env 则只对该项目生效；放在 ~/.codely-cli/.env 则对所有项目生效。

交互式配置（TUI）：`/model config`

在会话中输入 /model config 打开模型配置对话框，可逐槽位可视化配置并保存到 settings。

界面布局

Model Config
Scope: User (1=User, 2=Workspace, 3=System)
Tabs: [Main]  Flash  Multimodal  Agent

> Model: gpt-4o
  Auth: openai
  Wire API: chat
  Temperature: 0.3
  Reasoning Effort: (inherit)

操作方式

操作	按键
切换保存范围（Scope）	`1` 用户级 / `2` 工作区级 / `3` 系统级
切换槽位（Tabs）	方向键或 `Tab`，在 Main / Flash / Multimodal / Agent 间切换
选择字段	上下方向键移动到 Model / Auth / Wire API / Temperature / Reasoning Effort
编辑/选择	`Enter` 进入编辑
保存	`s`
关闭	`Esc`

选项说明

Auth 可选：inherit / openai / anthropic / codely-oauth / qwen-oauth / gemini-api-key / vertex-ai。选 inherit 表示继承全局 auth。
Wire API 可选：inherit / chat / responses / messages。
Reasoning Effort 可选：inherit / minimal / low / medium / high / xhigh / max。
Model 会从该槽位 effective auth 对应 provider 拉取可用模型列表，并保留 Custom model... 让你手动输入。

修改 Wire API 通常需要重启后才完全生效，界面会以黄色提示 Restart required。 Model 列表按槽位 effective auth 拉取，切换某槽位 auth 后会重新拉取对应 provider 的列表（不同 auth/baseUrl 不复用彼此缓存）。

常见用例

用例 A：临时换 main model 格式（最常用，不持久化）

只想这次跑用 Anthropic Messages 或 OpenAI Responses 格式：

codely --wire-api messages -m neo/messages/claude-opus-4-8
# 或
codely --wire-api responses -m neo/responses/gpt-5.5

用例 A-1：切换 main model 格式（持久化）

.codely-cli/settings.json 添加：

{
  "model": "neo/messages/claude-opus-4-8",
  "contentGenerator": {
    "overrides": {
      "model": {
        "wireApi": "messages"
      }
    }
  }
}

⚠️ 此时如果通过 /model use 直接切换模型，那么除非模型支持 messages 协议，否则可能出错。并且下次进入 codely 默认 main model 的 wireapi 永久改为 messages。

用例 B：主模型用 Anthropic，其余用默认（持久化到工作区）

.codely-cli/.env：

CUSTOM_AUTH=1
ANTHROPIC_AUTH_TOKEN=sk-ant-xxx
ANTHROPIC_BASE_URL=https://your-anthropic-endpoint

.codely-cli/settings.json：

{
  "model": "claude-sonnet-4",
  "contentGenerator": {
    "authType": "codely-oauth",
    "wireApi": "chat",
    "overrides": {
      "model": {
        "authType": "anthropic",
        "wireApi": "messages"
      }
    }
  }
}

效果：主对话走 Anthropic + messages，flashModel / multimodalModel / defaultAgentModel 继续用 codely-oauth + chat，互不影响。

用例 C：Flash 槽位用便宜快的模型省成本

{
  "flashModel": "gpt-4o-mini",
  "contentGenerator": {
    "overrides": {
      "flashModel": {
        "authType": "openai",
        "wireApi": "chat",
        "samplingParams": { "temperature": 0.1 }
      }
    }
  }
}

用例 D：所有项目统一配置（用户级全局）⭐

想让所有项目都默认用同一套 provider/模型，只需配置一次用户级文件。

~/.codely-cli/.env（对所有项目生效）：

CUSTOM_AUTH=1
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1

~/.codely-cli/settings.json（对所有项目生效）：

{
  "model": "gpt-4o",
  "flashModel": "gpt-4o-mini",
  "multimodalModel": "gpt-4o",
  "defaultAgentModel": "gpt-4o",
  "contentGenerator": {
    "authType": "openai",
    "wireApi": "chat"
  }
}

之后在任意项目里直接 codely 即可。单个项目若要覆盖，再在该项目的 .codely-cli/settings.json 写槽位 override 即可（工作区级优先于用户级）。

⚠️ Provider 不兼容的情况

authType 和 wireApi 必须与 provider 实际支持的接口匹配，否则会请求失败（4xx / 解析错误 / 字段被拒）。常见不兼容场景：

Wire API 与 endpoint 不匹配：
- responses 只能用于支持 OpenAI Responses API 的 endpoint。很多 OpenAI 兼容网关只实现了 Chat Completions，对它们用 responses 会失败——应改用 chat。
- messages 只能用于 Anthropic Messages 风格的 endpoint。
- chat 用于 OpenAI Chat Completions 风格的 endpoint。
模型不支持某些采样/扩展字段：reasoning_effort、chat_template_kwargs（如 enable_thinking）、extra_body 等并非所有模型/provider 都支持，写了可能被忽略或直接报错。仅在确认目标 provider 支持时使用。
baseUrl 与 authType 不一致：例如把 authType: openai 指向一个只支持 Anthropic 协议的 baseUrl，会导致协议层不兼容。Auth 决定凭证/baseUrl 来源，Wire API 决定协议，两者要对得上。
缺少 CUSTOM_AUTH=1：使用任何非 codely-oauth 的 provider 时若没设 CUSTOM_AUTH=1，启动直接报错（见上文）。
缺少对应凭证环境变量：选了某 authType 却没在 .env 配置它要求的 key（如 openai 缺 OPENAI_API_KEY），会因无凭证而失败。

经验法则：先确认 endpoint 实现的是哪种协议，再选对应的 wireApi；OpenAI 兼容网关默认优先尝试 chat，只有确知支持 Responses 时才用 responses。

配置优先级与生效范围

作用范围优先级（高 → 低）：命令行参数 > 工作区 .codely-cli/ > 用户级 ~/.codely-cli/ > 内置默认。
字段继承：槽位 overrides.<slot> 覆盖 contentGenerator 全局；全局覆盖内置默认。
命令行不落盘：--wire-api / --auth 等只影响当前进程，不写回 settings；它们作用于主槽位（model）的会话级覆盖，已显式配置 override 的其他槽位不受影响。
环境变量来源：CUSTOM_AUTH 与各 provider 凭证从 .codely-cli/.env 加载（工作区优先，其次用户级）。

核心概念​

模型槽位（Slot）​

两个正交的维度：Auth 与 Wire API​

继承关系​

Wire API 的默认行为​

最常见用法：只用命令行参数，不持久化 ⭐​

启用非默认 Provider：必须设置 CUSTOM_AUTH=1​

在 .codely-cli/.env 中写变量（推荐）​

交互式配置（TUI）：/model config​

界面布局​

操作方式​

选项说明​

常见用例​

用例 A：临时换 main model 格式（最常用，不持久化）​

用例 A-1：切换 main model 格式（持久化）​

用例 B：主模型用 Anthropic，其余用默认（持久化到工作区）​

用例 C：Flash 槽位用便宜快的模型省成本​

用例 D：所有项目统一配置（用户级全局）⭐​

⚠️ Provider 不兼容的情况​

配置优先级与生效范围​

相关文档​