Open Interpreter：面向低成本模型的编码智能体——Harness 模拟、协议兼容与实战指南

2026-09-05 11:53:27作者：邬祺芯Juliet

本文基于仓库中文 README 的核心内容展开，介绍 Open Interpreter——一个用 Rust 构建、专为低成本模型优化的编码智能体——的安装与启动方式，重点剖析其核心的 Harness（智能体框架）模拟机制与底层路由实现，并说明它如何通过 ACP 与 Codex exec 协议嵌入到你已有的编辑器、SDK 工作流中。读完本文，你可以独立完成安装配置、为不同模型服务商选择正确的 harness，并理解其请求路由的源码级原理。

一、项目定位：Codex 分支 + Harness 模拟

Open Interpreter 是 OpenAI Codex 的一个分支（fork），其核心目标不是复刻完整产品，而是模拟那些能让低成本模型发挥最佳性能的"智能体运行框架"（harness）。harness 会修改面向模型的提示词、工具模式、消息转换以及响应处理，同时保持 Open Interpreter 自身的原生 Rust 运行时不变。

几个关键事实（来自 README_ZH.md）：

项目近期使用 Rust 重新实现了服务商推荐的 Kimi Code 智能体框架，使 Kimi K3 模型可以在熟悉的 Codex 风格界面中运行；
当前仓库是新版 Rust 实现，基于 Codex 构建。原来那个用 Python 编写的 open-interpreter 项目目前由社区以 fork 形式继续维护，与本仓库是两个不同的代码库；
项目采用 Apache-2.0 许可证，主代码位于 codex-rs Rust workspace 中。

二、安装与快速上手

安装脚本分平台提供。macOS 和 Linux 执行：

curl -fsSL https://www.openinterpreter.com/install | sh

Windows（PowerShell）执行：

irm https://www.openinterpreter.com/install.ps1 | iex

安装完成后，在终端中输入 i 或 interpreter 即可开始一次会话。

配置和会话状态都保存在本地的 ~/.openinterpreter 目录中，产品专属的运行时状态不依赖任何远端私有格式。更完整的安装说明见安装指南与快速开始。

三、核心机制：`/harness` 切换智能体框架

3.1 使用方式

在 TUI 交互界面中输入 /harness 即可查看并切换当前 harness。README 中给出的实际输出如下：

> /harness

native
claude-code
claude-code-bare
zcode
kimi-code
kimi-cli
qwen-code
deepseek-tui
swe-agent
minimal

也可以在配置文件中固定 harness，或在单次运行中用 -c 临时覆盖（-c 接受 TOML 键值对）：

interpreter -c harness='"kimi-code"' "solve this task"

3.2 Harness 标识与请求路由

下表完整继承了 Harness 文档中的标识定义：

Harness 标识	Wire API	请求路由	参考
unset 或 `""`	`responses`	Responses API	原生 Open Interpreter/Codex 兼容表面
unset 或 `""`	`chat`	Chat Completions 兼容性	通用 OpenAI 兼容聊天提供商
`claude-code`	`responses`、`chat` 或 `messages`	Claude Code 在提供商传输层上的塑形	Claude Code 完整代理表面
`claude-code-bare`	`responses`、`chat` 或 `messages`	Claude Code 在提供商传输层上的塑形	Claude Code 裸配置
`zcode`	`messages`	Anthropic Messages harness	ZCode 形态的 GLM 编码代理表面
`deepseek-tui`	`chat`	Chat harness	DeepSeek TUI / CodeWhale
`kimi-code`	`chat`	Chat harness	当前的 Kimi Code 配置
`kimi-cli`	`chat`	Chat harness	旧版 Kimi CLI 配置
`qwen-code`	`chat`	Chat harness	Qwen Code 配置
`swe-agent`	`chat`	Chat harness	SWE-agent 配置
`minimal`	`chat`	Chat harness	Open Interpreter 最小化聊天工具表面
任意其他字符串	`chat`	Chat Completions 兼容性	自定义标记；无内建 harness 请求构造器

3.3 源码视角：Harness 枚举与路由解析

从源码结构看，harness 的完整集合定义在 Harness 枚举中。除了 TUI 列表中的十个标识，枚举里还包含若干内部变体（little-coder、mini-swe-agent、opencode、pi、terminus-2）以及一个 Other(String) 变体用于承载任意自定义字符串——这正好对应文档中"任意其他字符串走通用 Chat Completions 兼容性"的行为。配置名到枚举的映射由 Harness::from_config_name 完成（空字符串与 None 一律回落到 Native）。

harness 与配置的关系体现在 config_toml.rs 中：

/// Optional default harness family to emulate, such as `claude-code`.
pub harness: Option<String>,

/// Whether to include Open Interpreter guidance for the selected harness.
pub harness_guidance: Option<bool>,

真正的分发生效点在 resolve_stream_transport_route：它根据 (wire_api, harness) 二元组决定每次请求走哪条传输路线——Responses API 原生路由、Chat Completions 兼容路由、某条 chat harness 路由，还是 Messages harness 路由。各 harness 的具体请求构造实现分散在 codex-rs/core/src/harness/ 目录下的独立模块中（如 kimi_code.rs、claude_code.rs、swe_agent.rs、kimi_cli.rs 等）。

值得注意的是一条硬性拒绝规则：当 wire_api = "messages" 而 harness 不是 claude-code/claude-code-bare/zcode 时，路由解析会直接报错。例如原生模式会返回：

wire_api = "messages" requires a harness-native transport; configure harness = "claude-code" or "claude-code-bare" for Anthropic-style sessions

这与文档中"Messages 需要 harness 本地的传输层，因此原生模式被拒绝"的描述完全一致，对应的断言测试见 routing.rs 测试。

四、路由兼容性与自动 Harness 推断

4.1 路由兼容性矩阵

Harness 路由具有严格的匹配要求：

Provider `wire_api`	兼容的 harness
`responses`	原生 Responses、`claude-code` 与 `claude-code-bare`
`chat`	原生聊天兼容性、`claude-code`、`claude-code-bare`、`deepseek-tui`、`kimi-code`、`kimi-cli`、`qwen-code`、`swe-agent` 与 `minimal`
`messages`	`claude-code`、`claude-code-bare` 与 `zcode`（原生模式被拒绝）

因此 Anthropic 风格的提供商通常需要显式配置：

model_provider = "anthropic"
harness = "claude-code"

而大多数兼容 OpenAI 的托管提供商使用 wire_api = "chat"，可以通过通用聊天兼容性或匹配的聊天 harness 运行。

4.2 自动 Harness 默认值

当配置中未显式设置 harness 时，Open Interpreter 会根据提供商 ID、提供商名称、base_url 和模型 ID 推断默认值。推断逻辑实现于 default_harness_for_provider_model：

检测到的家族	默认 harness
Anthropic、Claude 模型 ID、Anthropic 基础 URL，或任何 `messages` 提供商	`claude-code`
Kimi/Moonshot 提供商 ID、名称、基础 URL 或模型 ID	`kimi-code`
Qwen/QwQ/DashScope 提供商 ID、名称、基础 URL 或模型 ID	`qwen-code`
DeepSeek 提供商 ID、名称、基础 URL 或模型 ID	`claude-code-bare`

显式的 harness = "..." 配置总是优先于推断结果。源码中有一段产品决策注释值得注意：DeepSeek 之所以默认走 claude-code-bare 而不是 deepseek-tui，是因为"claude-code-bare 在 DeepSeek 模型上取得了最好的结果，deepseek-tui 仍可通过 /harness 手动选择"（见 lib.rs 第 220-223 行）。

4.3 每个 Harness 具体改了什么

claude-code：在所选提供商的 Responses、Chat 或 Anthropic Messages 传输层上构建 Claude Code 形态的请求，添加 Claude Code 系统提示、思考配置、上下文管理设置、标题生成请求以及 Claude 形态的工具表面（Bash/PowerShell、Read、Write、Edit、TodoWrite、Glob、Grep、网页搜索/获取、LSP、计划唤醒及 Claude 风格子代理处理程序）。
claude-code-bare：使用与 claude-code 相同的传输层，但采用"裸"配置——更小的提示/配置形态与不同的输出默认值。DeepSeek 会自动选择此配置。
zcode：使用兼容 Anthropic Messages 的请求，配以 ZCode 形态的系统提示、头部、工具、todo 与计划行为、技能、会话上下文及子代理表面。工具调用仍在 Open Interpreter 的原生 Rust 运行时中执行。注意：该 harness 要求 wire_api = "messages"，内置的 Z.AI 提供商默认使用 chat，需先手动配置 Messages 端点，参见 Z.AI、GLM 与 ZCode 指南。
kimi-code：使用兼容 Chat Completions 的请求，搭配当前 Kimi Code 的提示、工具定义、prompt-cache 键、思考配置和消息格式。这是 Kimi 与 Moonshot 提供商（包括 Kimi K3）的默认配置；Kimi 工具调用由 Open Interpreter 的原生 Rust 运行时执行，不会调用外部 Kimi 可执行文件。Kimi Code 订阅使用 kimi-for-coding 提供商（可通过内置 Kimi 登录流程认证），Moonshot Platform API 密钥则使用 moonshotai 提供商。详见 Kimi K3 指南。
kimi-cli：旧版 Python Kimi CLI 形态的系统提示，包括工作目录列表、AGENTS.md 加载、Kimi 技能发现、prompt-cache 键、推理力度映射及 Kimi 工具模式（Shell、ReadFile、WriteFile、StrReplaceFile、Glob、Grep、ReadMediaFile、SearchWeb、FetchUrl、SetTodoList、plan-mode 控制、后台任务列表/输出/停止、AskUserQuestion 与 Agent）。仅在需要兼容已退役的 Python CLI 配置时使用；新的 Kimi 会话应使用 kimi-code。
deepseek-tui：DeepSeek TUI/CodeWhale 形态的系统提示，添加回合元数据、仓库上下文、未找到项目说明时生成的项目指令，以及 DeepSeek TUI 工具模式（shell、apply patch、edit/write/read file、list directory、grep/file search、git status/diff、diagnostics、checklist、plan 与 tool search）。详见 DeepSeek 指南。
qwen-code：Chat Completions 请求加 Qwen Code 启动上下文——在用户对话前插入一个合成的设置交换，包含日期、操作系统、当前目录以及一个小的文件夹列表。处理程序包括 read file、write file、edit、shell command、glob、grep、todo write、ask user question、plan exit 与 agent。
swe-agent：采用类似 SWE-agent 的讨论/指令循环而非工具模式：助手响应被解析为 shell 命令，Open Interpreter 注入相应动作，并将命令输出作为观察返回。默认命令超时为 30 秒。
minimal：紧凑的软件代理系统提示，将函数工具映射为普通的 Chat Completions 工具列表。当提供商支持聊天工具、但不需要特定 harness 表面时非常有用。

4.4 `harness_guidance`

harness_guidance = true 默认启用。目前它只为 kimi-cli 添加额外指导，其他 harness 会忽略此设置。若要进行更严格的 harness 运行，可在配置中关闭：

harness_guidance = false

一份完整的相关配置示例（Moonshot + Kimi K3）：

model_provider = "moonshotai"
model = "kimi-k3"
harness = "kimi-code"

[model_providers.moonshotai]
name = "Moonshot AI"
base_url = "https://api.moonshot.ai/v1"
env_key = "MOONSHOT_API_KEY"
wire_api = "chat"

更多提供商与 wire_api 细节见模型服务商配置指南与配置参考。

五、ACP 兼容与 Codex 兼容

Open Interpreter 在协议层面保持开放，可以接入已有的工具链，而不是要求你更换整套环境。

5.1 作为 ACP 智能体运行在编辑器中

Open Interpreter 可在兼容 Agent Client Protocol（ACP）的编辑器和客户端中使用：将客户端配置为启动 interpreter acp 即可。ACP 服务端的 Rust 实现位于 codex-rs/acp-server，接入示例见 ACP 指南。

5.2 一行代码切换 Codex SDK 的二进制

如果你已经在用 OpenAI Codex SDK，可以保留原有 SDK，仅把底层二进制指向 interpreter：

-const codex = new Codex();
+const codex = new Codex({ codexPathOverride: "interpreter" });

Open Interpreter 使用的是与 Codex 相同的 exec 协议（实现见 codex-rs/exec）。SDK 集成细节见 SDK 指南。

仓库还内置了一个不依赖模型服务商的本地兼容性检查脚本，可直接运行验证 exec 协议兼容性：

scripts/test-codex-sdk-compat.sh

六、计算机操作：内置 QA 技能

Open Interpreter 内置 QA 技能，让任何模型都能操作和测试界面：

通过 agent-browser（vercel-labs 出品的浏览器自动化项目）在真实浏览器中操作 Web 应用；
通过 trycua/cua 操作和测试原生桌面应用。

该能力属于技能（skills）体系的一部分，相关机制见 Skills 文档。

七、功能总览

综合 README 与源码结构，当前版本的功能面如下：

功能	说明	仓库依据
原生沙箱	在 macOS、Linux 和 Windows 上通过原生沙箱执行命令	codex-rs/linux-sandbox、codex-rs/sandboxing、Sandbox 文档
`/model` 切换	在 TUI 中切换模型服务商和模型	codex-rs/tui
`/harness` 切换	查看或切换 Rust 原生的模型框架	codex-rs/tools/src/harness.rs
QA 技能	通过内置 QA 技能测试 Web 应用和原生应用	codex-rs/ext 扩展体系
ACP 智能体	通过 `interpreter acp` 作为编辑器的 ACP 智能体运行	codex-rs/acp-server
本地状态	配置和会话状态保存在本地的 `~/.openinterpreter`	配置文档
扩展机制	支持 `exec`、MCP、技能、hooks、权限和 `AGENTS.md`	codex-rs/mcp-server、codex-rs/hooks、codex-rs/exec

CLI 的完整参数说明可查阅 CLI 参考，权限与审批流程见权限文档。

八、服务商目录的生成方式

Open Interpreter 的模型服务商与模型列表是工具自动生成的，而非在 Rust 代码中手工维护。从 codex-rs 目录可以运行目录生成脚本：

cd codex-rs
python3 scripts/write_provider_catalog.py            # 刷新所有托管服务商
python3 scripts/write_provider_catalog.py --provider <provider-id>   # 仅更新指定服务商（可重复该参数）

生成产物落地为 provider_catalog.json，由 model-provider-info 模块在运行时消费。需要拉取实时模型源时，须按服务商文档中说明提供对应凭据。