Open Interpreter 模型体系全解析：从 `/model` 选择器到能力元数据与本地模型接入

Open Interpreter 围绕模型提供了一个完整的“分层元数据 + 能力门控”体系：用户通过 /model 选择 provider、模型、harness 及模型专属控制项，模型列表则由远端 /models 接口与仓库内置目录共同构建。本文以 docs/models.md 为骨架，结合 codex-rs 侧的管理器与协议源码，讲解模型元数据从哪来、能控制什么、推理档位如何映射，以及 Ollama/LM Studio 等本地 OSS 模型如何接入——读完你就能熟练使用 -m、--oss 与配置默认值搭出自己的多模型环境。

交互入口：/model 与底部状态栏

Open Interpreter 的模型能力模型（capability model）选择通过内置斜杠命令完成：

• 输入 /model 可以依次选择 provider（供应商）、model（模型）、harness（线协议适配层）以及模型专属的控制项，例如推理档位、思考开关等；
• 选择完毕后，界面底部的 footer（状态栏）会实时显示当前激活的配置，让你随时确认自己正在使用哪一套 provider + model + harness 组合。

从这里开始，模型不仅仅是“一个名字”，而是一组由元数据驱动的可交互能力集：哪些模型出现在选择器里、能不能调推理档位、支不支持贴图，都由后文的“能力元数据”决定。

Shell 覆盖：-m 与 --oss

不想进入交互式选择器时，可以直接在命令行覆盖模型选择。Open Interpreter 的 -m 参数接受 provider/model 形式的模型标识，--oss 则把会话切到本地开源 provider：

interpreter -m gpt-5.1-codex "review this module"
interpreter --oss "use my local open source provider"

# 用 -m 指定远程本地服务上的 qwen 模型
CODEX_OSS_BASE_URL=http://192.168.1.20:1234/v1 \
  interpreter --oss --local-provider lmstudio -m qwen/qwen3-coder-next

-m 与 --oss 可以组合使用（如上所示），便于在自托管/局域网服务上精确指定模型。命令行参数优先级高于配置文件，适合临时切换验证不同 provider 的兼容性。

配置默认值：model_catalog 之外的静态设置

如果你不希望在每次启动时都传参数，可以在配置文件（TOML）中固化默认的模型栈。文档中给出的默认配置如下：

model_provider = "openai"
model = "gpt-5.1-codex"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
model_verbosity = "medium"

逐项解读各字段的实际影响：

字段	含义	取值要点
model_provider	默认激活的 provider ID	如 openai、ollama、lmstudio，或 [model_providers.xxx] 自定义项
model	默认模型 ID	会与 model_provider 组合解析；-m 可覆盖
model_reasoning_effort	默认推理档位	见下文“Reasoning Effort”，medium 是均衡默认值
model_reasoning_summary	推理摘要策略	文档默认 auto，交由系统按模型行为自动决定
model_verbosity	输出冗长程度	默认 medium，用于控制回答详略

在源码中，推理档位不是随意字符串：ReasoningEffort 是一个带 FromStr 解析的强类型枚举（见 codex-rs/protocol/src/openai_models.rs），支持 none/minimal/low/medium/high/xhigh/max/ultra 之外，还能容纳模型自定义的 Custom(String) 值——这保证了“未来模型推出的新档位”不会被客户端直接拒绝，而是原样透传到线上。

模型元数据从哪来：五层数据源的分层架构

一个关键设计原则是：Open Interpreter 并没有维护一份手写的全量模型清单（更不存在“一份 Rust 里写死的所有模型列表”）。模型信息由以下五层数据源叠加而成：

数据源	职责
Provider 的 /models 接口	当活跃 provider 暴露该接口时，实时返回其可用的模型 ID 列表
codex-rs/model-provider-info/provider_catalog.json	随二进制分发的 provider/model 种子数据，由 models.dev 及配置的线上 provider 模型源生成
codex-rs/codex-api/model_compatibility_catalog.json	兼容性元数据：支持的请求参数、搜索能力、推理等级、输入模态等
codex-rs/models-manager/models.json	OpenAI 风格的模型预设（preset）元数据，供模型管理器使用
配置中的 model_catalog	可选的用户静态目录，用于为某个 provider / 会话提供兜底元数据

管理器如何把它们合并

在代码层，模型管理器定义了 ModelsManager trait（codex-rs/models-manager/src/manager.rs）。它的核心流程是：

1. 按 RefreshStrategy（Online / Offline / OnlineIfUncached）从 ModelsEndpointClient 拉取远端模型目录，或读取本地磁盘缓存 models_cache.json（默认 TTL 300 秒，见 manager.rs）；
2. 对拉取到的模型列表调用 apply_compatibility_catalog，用兼容性目录进行“富化”（enrichment，见 codex-rs/models-manager/src/compatibility_enrichment.rs），例如补齐推理等级、并行工具调用支持等字段；
3. 依据 auth 模式与模型可见性过滤，按优先级排序后返回可用的模型预设。

而内置的预设数据则由 codex-rs/models-manager/src/lib.rs 通过 include_str!("../models.json") 直接编译进二进制，实现开箱即用。

代理场景下的 provider 识别

模型管理器会先向活跃 provider 请求模型列表，然后在以下信号中识别 provider 身份，命中后叠加内置数据：

• Anthropic identity（身份标识）
• base URL
• provider 名称
• 认证环境变量（auth env var）

这意味着即使你配置的是一个代理（proxy），只要它明确指向某个已知 provider，继承的元数据依然有效——不会因为 URL 被替换就丢失上下文窗口、推理控制等关键信息。

能力元数据：一个模型“能干什么”由谁决定

模型元数据是一组可供 UI / API 读取的“能力清单”。它能控制如下维度：

• 选择器可见性：某个模型是否出现在 /model 列表中；
• 展示名称与描述：下拉框里显示什么；
• 上下文窗口大小（context window）；
• 输入模态：如纯文本 text、支持图片 image；
• API 是否支持该模型；
• 支持的请求参数；
• 推理控制形态（reasoning control shape）；
• web/搜索能力；
• 并行工具调用支持（parallel tool-call）。

在这些维度里，“是否支持搜索”“是否支持并行工具调用”“推理档位有哪些”都直接来自兼容性目录——测试用例也印证了这一点，例如 compatibility_enrichment.rs 中有 enriches_parallel_tool_call_support 与 leaves_unknown_models_untouched，说明富化只针对目录内已知模型，未收录模型保持原样。

推理控制不是布尔值：五种 Control Shape

在协议与 UI 中，“模型会不会推理”不是一个布尔开关，而是一组形态各异的控制形状。每种模型按其行为被归入下表：

Control	含义
none	没有已知的推理控制项
fixed	模型会推理，但 UI 不应暴露任何用户可控项
effort	OpenAI 风格的推理档位控制（如 low/medium/high）
thinking_toggle	布尔式的思考开关（on/off）
thinking_budget	以 token 预算为单位的思考控制

源码中的 ReasoningControl 枚举正是这五种取值的直接体现（见 codex-rs/protocol/src/openai_models.rs），且被 strum/serde 统一序列化为 snake_case，保证协议层、schema 与前端一致。fixed 形态的存在很关键：很多推理模型“默认就推理”，但厂商并不开放调节，此时 UI 应展示而不应渲染一个无效控件。

Reasoning Effort：五档标准值及 harness 映射

当模型暴露 effort 类控制时，Open Interpreter 使用下面这组标准语义：

值	用途
minimal	快速、简单的编辑
low	常规实现
medium	默认的均衡工作档
high	困难调试、重构、代码审查
xhigh	依模型而定的额外深度推理

这五个值面向“用户意图”定义，而非绑定某个厂商 API。真正的厂商差异由 harness 负责映射——每个 harness 把这些标准档翻译成对应 provider 的字段。例如 kimi-cli 的映射为：

• minimal / low → 低推理
• medium → 中推理
• high / xhigh → 高推理

映射关系之外，还有一层兼容性兜底：不支持的模型会按 provider 行为选择“隐藏”“忽略”或“拒绝”推理控制项，避免 UI 呈现一个点击无效的控件。底层 ReasoningEffort 还额外容纳了 max、ultra 与 Custom(String) 取值，让兼容目录无需升级客户端就能识别未来新档位（openai_models.rs）。

输入模态（Input Modalities）

模型的输入模态使用规范化的标签描述：

值	含义
text	常规用户回合与工具载荷
image	来自诸如 -i 等命令的图片附件

带图提问的典型用法：

interpreter -i screenshot.png "what is wrong here?"

这里有一个值得注意的兼容性细节：旧版载荷（legacy payloads）如果缺失模态元数据，出于兼容考虑会保守地默认同时支持 text 与 image；而新生成的 provider 条目则应尽可能标注真实支持的模态，以便选择器准确显示“此模型收不收图”。

本地模型接入：Ollama 与 LM Studio

Open Interpreter 内置两个本地 OSS provider：

Provider	默认 base URL	覆盖方式
ollama	http://localhost:11434/v1	CODEX_OSS_PORT 或 CODEX_OSS_BASE_URL
lmstudio	http://localhost:1234/v1	CODEX_OSS_PORT 或 CODEX_OSS_BASE_URL

使用前先启动本地服务，再直接启动对应 provider：

interpreter --oss --local-provider ollama
interpreter --oss --local-provider lmstudio

关于 --oss 的行为需要再明确一点：

• --oss 不接 --local-provider 时，会使用你保存的 oss_provider 设置；若没有保存，则打开一个选择器，并实时探测每个默认本地端点是否在响应，再让你挑选可用的那个；
• 两个 provider 默认都走 OpenAI 兼容的 /v1 路由。

换端口、换主机：请用 CODEX_OSS_BASE_URL

如果本地服务跑在别的机器或端口上，请在启动 Open Interpreter 前设置完整的、OpenAI 兼容的 /v1 base URL：

CODEX_OSS_BASE_URL=http://192.168.1.20:1234/v1 \
  interpreter --oss --local-provider lmstudio -m qwen/qwen3-coder-next

# 远程 Ollama 服务器同理，用 --local-provider ollama
CODEX_OSS_BASE_URL=http://10.0.0.8:11434/v1 \
  interpreter --oss --local-provider ollama

这条覆盖路径在源码中有直接对应实现：create_oss_provider 会先解析 CODEX_OSS_PORT（仅当其可解析为 u16 端口号时才生效），拼出 http://localhost:<port>/v1；随后若存在非空的 CODEX_OSS_BASE_URL，则完全取代前者（codex-rs/model-provider-info/src/lib.rs）。

因此，不要为了单纯改这两个内置本地 provider 的地址而单独新建一个 model_providers 条目——CODEX_OSS_BASE_URL 就是官方支持的覆盖方式，配置更省事也更不容易踩到“新旧 provider 并存”的坑。需要说明的是，源码注释把这两个 CODEX_OSS_* 环境变量标记为实验性（experimental），未来存在改为从 config.toml 读取的可能性，请留意升级日志。

模型元数据警告的含义

当看到类似 Model metadata for ... not found 的警告时，需要注意它并不代表服务器连接失败。它的真实含义是：

本地服务器返回了一个不在 Open Interpreter 兼容性目录中的模型 ID。

正确处置步骤：

1. 确认服务器实际暴露的模型 ID（例如 ollama list 或 LM Studio 的模型面板）；
2. 用 -m 传入完全一致的 ID 值；
3. 升级 Open Interpreter，确保本地目录为最新版本。

在未命中目录的情况下，Open Interpreter 仍可继续运行（使用 fallback 元数据），但某些模型专属控件或行为可能不可用。

Provider 家族与默认 Harness

当没有显式指定 harness 时，部分模型家族会自动获得一个默认 harness（线协议适配层），保证“开箱即用”：

模型 / provider 家族	默认 harness
Claude / Anthropic / Messages	claude-code
Kimi / Moonshot	kimi-code
Qwen / QwQ / DashScope	qwen-code
DeepSeek	claude-code-bare

这一自动映射把“推理档位 / 思维链格式 / 线协议”的差异收敛到 harness 层：不同的 harness 通过映射标准档位、选择 Responses / Chat / Messages 等 wire API，让上层 UI 无需关心底层各家方言（各 wire API 形态见 codex-rs/model-provider-info/src/lib.rs）。

延伸阅读

• Harness 线协议兼容矩阵：了解 claude-code、kimi-code、qwen-code、claude-code-bare 等 harness 各自支持哪些 wire API；
• Model providers 配置指南：各 provider 的认证、base URL 与专属配置步骤；
• 元数据与能力数据的真实样例，可继续翻阅 codex-rs/model-provider-info/provider_catalog.json、codex-rs/codex-api/model_compatibility_catalog.json 与 codex-rs/models-manager/models.json。