Open Interpreter 模型体系完全指南：模型元数据来源、推理控制、harness 默认值与本地开源模型接入

docs/zh/models.md 是 Open Interpreter（本仓库面向 Kimi K3、GLM 5.3 等开放模型的编码代理）中关于「模型」机制的核心指南。它以 /model 交互为入口，讲清了模型列表从哪来、元数据能控制什么、推理与输入模式如何在协议层建模，以及如何接入 Ollama / LM Studio 本地开源模型。读完本文，你将能在交互界面、Shell 参数与 TOML 配置三个层面精确选择并提供者无关的推理、多模态与 harness 控制，并能读懂仓库中的元数据目录与源码实现。

从 /model 开始：提供商、模型与 harness 的三层分离

在终端启动 Open Interpreter 后，输入 /model 即可打开模型选择器，在一处完成三层选择：

• 提供商（provider）：决定请求发往何处、如何认证；
• 模型（model）：发送到该端点的具体模型 ID；
• harness（工具链）：决定面向代理的提示、工具与消息行为。

选择器同时暴露「模型特定控制」（model-specific controls），例如推理档位、思考开关等。会话页脚（footer）会持续显示当前生效的模型选择，方便随时核对。

如果系统已为某个模型系列自动配置了默认 harness，你也可以用 /harness 检查并覆盖它。排查问题时务必保持「提供商 / 模型 / harness」三层分离的思维：提供商管端点与凭证、模型管要发送的 ID、harness 管请求格式与提示工程。更完整的提供商配置请见 模型提供商指南。

Shell 覆盖：一条命令完成模型指定

在非交互场景，Open Interpreter 提供 -m 与 --oss 两组快速参数：

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

这些参数在源码中定义于 共享 CLI 参数结构体，可供交互式与非交互式入口共用：

• -m, --model <MODEL>：指定代理使用的模型 ID；
• --oss：切换为开源提供商（本地 OSS 模式）；
• --local-provider <PROVIDER>：配合 --oss 指定本地提供者（lmstudio 或 ollama）；未指定时回退到配置默认或弹出选择器；
• -i, --image <FILE>：向初始提示附加一张或多张图片（逗号分隔，num_args = 1.. 允许多张）。

-m 的取值即选择器内展示的模型 ID，两者保持一致，便于把交互中确认的模型固化到脚本里。

配置默认值：TOML 中固化你的模型偏好

以下 TOML 片段来自文档示例，用于在配置文件中固化默认模型行为：

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

各字段在 配置结构定义 中都有对应的强类型字段与注释，含义如下：

配置项	作用	取值/默认
model_provider	默认提供商 ID	任意已配置提供商
model	默认模型 ID	如 gpt-5.1-codex
model_reasoning_effort	默认推理努力档位	minimal / low / medium / high / xhigh
model_reasoning_summary	推理摘要交付方式	auto / concise / detailed / none
model_verbosity	输出详细程度（GPT-5 系列 Responses API 的 text.verbosity）	low / medium / high

源码中还有两个相关但未出现在示例中的字段值得注意：

• plan_mode_reasoning_effort（config_toml.rs）：专门为 plan 模式单独设置的推理档位；
• model_supports_reasoning_summaries（config_toml.rs）：强制启用当前模型的推理摘要支持。

值得说明的是，ReasoningSummary（auto/concise/detailed/none）与 Verbosity（low/medium/high）都是在 协议配置类型 中定义的枚举，序列化时统一使用小写以与 OpenAI API 对齐——配置文件中写 auto、medium，与协议层 wire 值完全一致。

模型元数据的来源：分层数据，而非手写清单

Open Interpreter 并没有维护一份手写全部模型 ID 的 Rust 列表，而是采用分层元数据策略，多个来源按角色各司其职：

Source	Role
Provider /models endpoint	在端点可用时，获取活动提供者的实时模型 ID。
model-provider-info/provider_catalog.json	由 models.dev 生成并结合已配置的实时提供者模型来源的捆绑 provider/model 种子数据。
codex-api/model_compatibility_catalog.json	兼容性元数据，如支持的参数、搜索支持、推理等级和输入模式。
models-manager/models.json	管理器使用的 OpenAI 风格模型预设元数据。
Config model_catalog	可选的用户提供的静态目录，用于特定提供者/会话。

这些文件在仓库中的真实路径分别为 provider_catalog.json、model_compatibility_catalog.json 与 models.json；用户自定义的静态目录则通过配置键 model_catalog_json（config_toml.rs）指向一个 JSON 文件路径，仅在本进程启动时应用一次。

模型管理器（model manager）的实际工作方式是：先向活动提供者请求模型列表，再在能够通过 Anthropic 身份、基础 URL、提供者名称或认证环境变量识别提供者时，使用捆绑数据补充或种子化结果。这一点很关键——它意味着即使用户把请求指向某个代理（proxy）或网关，只要代理明确指向一个已知提供者，Open Interpreter 依然能让模型条目继承有用的元数据，而不是降级为裸 ID 列表。

捆绑模型条目在无更精确来源时如何兜底，可以看 provider_catalog_models.rs 的实现：它会以模型 ID 作为 slug 建立 fallback 条目，若模型声明了 reasoning 或 thinking_toggle，则把 default_reasoning_level 设为 medium；若模型支持思考开关，则把 reasoning_control 标记为 ThinkingToggle。

能力元数据：一条模型记录到底能控制什么

元数据不只是「名字 + 上下文长度」，一条完整的模型条目可以控制以下能力面：

• 选择器可见性（picker visibility，是否在 /model 中展示）；
• 显示名称与描述；
• 上下文窗口（context window）；
• 输入模式，如文本和图像；
• 模型是否受 API 支持（supported_in_api）；
• 支持的请求参数；
• 推理控制形态（reasoning control shape）；
• 网页 / 搜索支持；
• 并行工具调用支持。

从源码结构看，这些字段会在模型管理器中聚合为 ModelInfo 结构（如 provider_catalog_models.rs 中 ModelVisibility::List、ReasoningEffort::Medium 等赋值），并被选择器、会话启动与请求序列化阶段共同消费。可以推断：选型器里看到的优先级排序、搜索开关、是否能调图像，都来自这条聚合后的模型元数据，而非运行时临时探测。

推理：从「单一布尔值」到五种控制形态

在 UI 与协议层，推理都不是单一的布尔值。Open Interpreter 协议定义了五种推理控制形态（见 ReasoningControl 枚举）：

Control	Meaning
none	无已知推理控制。
fixed	模型会推理，但 UI 不应暴露控制。
effort	OpenAI 风格的努力控制。
thinking_toggle	布尔型思考开/关控制。
thinking_budget	令牌预算思考控制。

也就是说：同样是「会思考的模型」，有的应当给用户一个低/中/高档位选择器，有的只该给开关，有的干脆由系统固定推理、不需要暴露任何 UI——协议通过 reasoning_control 区分这些情况。

推理努力档位与 harness 映射

当模型暴露的是 effort 控制时，Open Interpreter 统一使用以下五档取值：

值	用途
minimal	快速、简单的编辑。
low	常规实现。
medium	默认的平衡工作。
high	硬核调试、重构、审查。
xhigh	模型特定的额外推理。

这五档直接对应协议层 ReasoningEffort 枚举 中 Minimal/Low/Medium/High/XHigh 的 wire 值（as_str() 输出小写 minimal…xhigh）。协议还额外预留了 None、Max、Ultra 以及 Custom(String)（用于客户端尚不认识的模型自定义档位，例如 thinking-toggle 模型把 "Thinking" 作为开启选项，见 openai_models.rs）。

这些档位并不会被原样发给所有服务商。 不同的 harness 会把它们映射到提供者特定字段。文档给出的实例是：kimi-cli 将 minimal 与 low 映射为低推理，medium 映射为中等，high 或 xhigh 映射为高。因此，你在选择器里看到的五档 UI 是统一的，落到各提供商请求体里的字段却可能截然不同。

对于不暴露推理控制的模型，Open Interpreter 会根据提供者行为选择隐藏、忽略或拒绝推理控制——这既防止向不支持的端点发送无效参数，也解释了为什么某些模型在选择器里看不到推理档位。

输入模式：text、image 与老负载的兼容默认

规范的输入模式标签定义在 InputModality 枚举，协议层已预留 text、image、audio 三种：

值	含义
text	正常的用户回合和工具负载。
image	通过 -i 等命令附加的图像。

附加图像的实际命令为：

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

-i 参数在 shared_options.rs 中定义为可重复、逗号分隔的多值参数，因此一条命令可同时携带多张图片。

需要注意向后兼容策略：省略模式元数据的旧式负载（legacy payload）会保守地默认支持文本和图像，以免老请求被新模型拒绝；而由目录生成器产出的新 provider 条目则应在已知时注明真实模式（如仅文本的模型就只标 text）。

本地开源模型：Ollama 与 LM Studio

Open Interpreter 内置了两个本地开源（OSS）提供商，无需任何 API 密钥：

提供商	默认基础 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

这两个内置提供者的基础 URL 拼接逻辑可以在 create_oss_provider 实现 中看到：先用 CODEX_OSS_PORT 拼出 http://localhost:{port}/v1，若 CODEX_OSS_BASE_URL 存在则整体覆盖。代码注释明确标注这些 CODEX_OSS_* 环境变量目前是实验性的。

使用流程是：先启动本地服务，再启动 Open Interpreter 并直接指定提供者：

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

不带 --local-provider 的 --oss 会使用你已保存的 oss_provider 配置（配置键见 config_toml.rs，其取值在校验函数中只接受 lmstudio、ollama 两个内置 ID，见 validate_oss_provider）；若未保存，则弹出选择器，逐个探测默认本地端点是否有响应。

若本地服务器位于其他主机或端口，需在启动 Open Interpreter 前设置完整的、兼容 OpenAI 的 /v1 基础 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。文档特别强调一条使用纪律：不要仅仅为了更改任一内置本地提供者的地址而创建单独的 model_providers 条目——CODEX_OSS_BASE_URL 才是受支持的覆盖方式，自己包一层 provider 反而会绕开内置端点的特殊处理逻辑。

模型元数据警告

输出中出现 Model metadata for ... not found 时，表示本地服务器返回的模型 ID 未出现在 Open Interpreter 的兼容性目录中——它本身并不代表服务器连接失败。正确的处理路径是：

1. 确认服务器真实暴露的准确模型 ID；
2. 用该 ID 原样通过 -m 传入；
3. 更新 Open Interpreter 以获得最新的兼容性目录。

Open Interpreter 可以继续使用回退元数据运行（fallback 逻辑见 provider_catalog_models.rs），但部分模型特定的控制或行为（如推理档位、思考开关）可能不可用。

提供者系列与 Harness 默认值

某些模型系列在未显式指定 harness 时，会从模型/提供商系列自动推导出默认 harness：

模型/提供商系列	默认 harness
Claude/Anthropic/Messages	claude-code
Kimi/Moonshot	kimi-code
Qwen/QwQ/DashScope	qwen-code
DeepSeek	claude-code-bare

选择逻辑从「匹配条件」推导默认 harness（详见 模型提供商指南中的默认 harness 选择）：命中 Anthropic/Messages wire API 或 claude 系列 ID 走 claude-code，命中 Kimi/Moonshot 相关名称或域名走 kimi-code，命中 Qwen/QwQ/DashScope 走 qwen-code，命中 DeepSeek 走 claude-code-bare。因此文档表格里的四行本质上覆盖了当前主流开源编码模型的 wire-api 形态：

• Anthropic Messages 原生协议的模型 → claude-code；
• Kimi / Moonshot 平台 → kimi-code；
• 阿里云 DashScope 生态的 Qwen 系 → qwen-code；
• DeepSeek 需要 Anthropic 兼容请求但无复杂工具行为 → claude-code-bare。

如果默认推导不符合你的预期，可在配置中用 harness = "..." 显式覆盖。各 provider 的详细认证与推荐模型路径可分别参考 Kimi K3 指南、DeepSeek 指南 与 Z.AI / GLM 指南，wire API 兼容性矩阵见 Harness 文档。

小结：模型能力的完整闭环

把以上几节串起来，Open Interpreter 的模型体系是一条完整的「元数据 → 选择器 → 配置 → 请求」链路：目录（provider_catalog.json）提供模型种子，兼容性目录（model_compatibility_catalog.json）提供推理与多模态能力注解，管理器优先用提供者实时 /models 端点刷新、再按提供者特征匹配捆绑数据做增强，最终在 /model 选择器、页脚、-m 与 TOML 默认值中统一呈现。推理控制以 ReasoningControl 五种形态建模、以五档努力值为统一 UI、由 harness 负责映射到提供者字段；输入模式用规范的 InputModality 标签描述，并为老负载保留文本+图像的兼容默认。理解了这层分层与聚合逻辑，无论是接入本地 Ollama/LM Studio、调试「元数据未找到」警告，还是在不同模型之间评估推理与多模态能力，都能直接定位到仓库中对应的源码与数据文件。