AI Research 技术调研

Open Interpreter — OpenAI Codex(Rust) 的 fork，加一层「多 CLI harness 仿真」给低成本模型选最优 harness

15分钟阅读

Open Interpreter

一句话定位

当前的 Open Interpreter 已被彻底重写：它不再是那个经典的 Python「本地写代码 + 执行」agent（64k star、os mode/computer-use），而是 OpenAI Codex 的 Rust 源码树的一个 fork。OI 在 Codex 之上加的唯一独创层是 core/src/harness/ —— 一套「harness 仿真（harness emulation）」机制：用本地 runtime 去模仿 claude-code / kimi-cli / qwen-code / deepseek-tui / swe-agent 等各家 CLI 的 prompt 结构、工具 schema、消息转换与响应解析，从而给低成本开源模型喂上「最适合它的那套 harness」，以榨出最佳表现。它不会真的 shell out 去调外部 CLI（docs/harness.md:10：“The public runtime does not shell out to the real external agent CLI”）。

断代提醒：任务背景里的「agent loop / 代码执行沙箱 / os mode」是已被上游放弃的 Python 旧版（现存于社区 fork endolith/open-interpreter）。本 dossier 描述的是当前 Rust 主仓库，勿张冠李戴。

核心架构总览（目录结构关键路径 + 引用的 commit）

分析 commit：764a96ee05853d5494d7e711eefecec57ab712ef（2026-07-06，“Disable inherited CI wrapper workflows”），License Apache-2.0，语言 Rust。代码库根是 codex-rs/ 下 100+ crate + bazel 构建 + AGENTS.md，本质是 Codex 的 monorepo。

净增量分两层看：

(A) OI 独创的 harness 仿真层（codex-rs/core/src/harness/）

  • harness/mod.rs — 17 个 harness 实现清单
  • harness/routing.rs — 路由核心：wire_api(Responses/Chat/Messages) × Harness → StreamTransportRoute（已存档 src/routing.rs）
  • harness/request.rs — 唯一集成点：client.rs 调 build_chat_harness_request，按 route 分派到各 harness 的 build_request（已存档 src/request.rs）
  • harness/guidance.rs — harness_guidance 注入的额外可靠性指令（已存档 src/guidance.rs）
  • harness/session_skills.rs — 把会话级 <skills_instructions> developer block 按各 harness 原生格式重渲染（已存档）
  • 各 harness 实现 + 配套资源：claude_code.rs(4666 行/262KB)、zcode.rs(2635)、kimi_cli.rs(2687)、terminus_2.rs(2138)、deepseek_tui.rs、swe_agent.rs、mini_swe_agent.rs、opencode.rs、qwen_code.rs、kimi_code.rs、little_coder.rs、pi.rs、minimal.rs（668 行，存档为 src/harness_minimal_example.rs）；配套 *_prompt.md / *_tools.json
  • tools/src/harness.rs — Harness enum + from_config_name（已存档 src/tools_harness_enum.rs）

(B) Codex 原生底座（loop / tools / sandbox / memory / subagent / skills / hooks / MCP / otel 全部是 Codex 原生，OI 只是默认开启若干 feature）

  • core/src/session/turn.rs（2557 行）— 主 loop run_turn
  • core/src/tools/（registry/router/orchestrator/parallel + handlers/）
  • core/src/safety.rs、sandboxing/ crate、memories/、otel/、rollout/、rollout-trace/、core/src/agent/

Agent Loop（主循环 / 何时继续何时停）

**Codex 底座。**入口 core/src/session/turn.rs::run_turn（L144）。结构：外层 loop {}（L227），每轮 = 一次模型采样请求（run_sampling_request → try_run_sampling_request L2031，内部再套 loop 处理流事件/工具调用）。

  • 继续 vs 停止判据（L300–451）：needs_follow_up = model_needs_follow_up || has_pending_input（L320）。模型仍有待执行的 function calls，或有排队用户输入 → continue；否则跑 stop hooks（run_turn_stop_hooks L408）后 break。stop hook 可请求 continuation（注入 hook prompt 后继续，L415–435）。
  • 循环内嵌自动压缩防溢出：token_limit_reached 或收到 new_context_window 请求 → run_auto_compact（L351）后 continue；注释（L347）说明靠压缩把 token 拉到远低于上限以避免死循环。
  • harness 特例散在 loop 里：deepseek-tui 到 DEEPSEEK_TUI_CYCLE_TOKEN_LIMIT 触发 handoff 压缩（L378）；claude-code-bare 完成任务通知回注（L396–406）。
  • 前置步骤：run_pre_sampling_compact（L158）→ build_skills_and_plugins（L177）→ session-start hooks（L188）→ 记录输入。

记忆与上下文管理（压缩、长期记忆、会话持久化）

上下文压缩（Codex 底座）：core/src/compact.rs / compact_remote*.rs / compact_token_budget.rs；loop 内 run_auto_compact / run_pre_sampling_compact / maybe_run_previous_model_inline_compact（turn.rs L896–1176）。core/src/context_manager/（history/normalize/updates）维护 model-visible 历史。

会话持久化：rollout/ crate（recorder/state_db/session_index/compression），会话与轨迹落 SQLite state DB + rollout 文件；config/session 状态存 ~/.openinterpreter（repo README）。

长期记忆（OI 启用的 Codex feature，默认关）：memories/（read/write 两 crate）+ core/src/memories/，一等文档 docs/memories-pipeline-README.md（已存档）。两阶段管线：

  • Phase 1：后台从近期 rollout 抽取结构化 raw_memory + rollout_summary（并发、状态 DB lease/claim、密钥脱敏）。
  • Phase 2：全局 consolidation，把 stage-1 输出同步到 ~/.codex/memories/ 下 raw_memories.md / rollout_summaries/（git baseline 目录），再 spawn 一个内部 consolidation 子 agent（no approvals / no network / 仅本地写）去更新 MEMORY.md。有 usage_count/last_usage 排序与陈旧裁剪（max_unused_days）。

这条链同时是「自进化」（维度 7）与「轨迹利用」（维度 12）的证据。

工具体系（定义/调用协议/注册/权限）

Codex 底座。

  • 注册：core/src/tools/registry.rs（CoreToolRuntime trait、ToolSpec/ToolExposure；from_tools 去重注册）。
  • dispatch：core/src/tools/router.rs（ToolRouter::dispatch_tool_call_*、build_tool_call）。
  • 每轮工具集动态组装：turn.rs::built_tools（L1281）合并内置工具 + MCP 工具（list_all_tools）+ plugins + connectors，并做 tool_suggest 推荐。
  • 内置 handlers（core/src/tools/handlers/）：shell、unified_exec（exec_command/write_stdin，持久 shell 会话）、apply_patch、plan、multi_agents(_v2)、agent_jobs（CSV/批量 worker）、mcp/mcp_resource、tool_search、request_permissions、request_user_input、view_image、web(search/fetch)、sleep、current_time、get_context_remaining 等。

调用协议随 harness 变（OI 层的核心机制）：native/Responses 用 Codex function-tool schema；各 harness 把工具映射成目标 CLI 的原生 schema（如 kimi_code_tools.json、zcode_tools.json 落盘为独立资源）；swe-agent / mini-swe-agent / terminus-2 不用 tool schema，而是从助手纯文本里解析 shell 命令（见「与模型的协同设计」）。docs/harness.md:99–151 逐 harness 列出了各自暴露的工具集（如 kimi-cli 暴露 Shell/ReadFile/WriteFile/StrReplaceFile/Glob/Grep/…/Agent；qwen-code 暴露 read/write/edit/shell/glob/grep/todo/…）。

Prompt 设计（系统提示结构、动态组装）

Codex 底座 system prompt：core/gpt_5_2_prompt.md / gpt_5_1_prompt.md / prompt_with_apply_patch_instructions.md；protocol/src/prompts/base_instructions/default.md。动态组装：AGENTS.md（core/src/agents_md*.rs）、skills 的 <skills_instructions> developer block、时间提醒（session/time_reminder.rs）、repo/context 注入。

OI harness 层重写 prompt：每个 harness 自带整套 system prompt 资源文件（claude_code_prompt.rs、kimi_cli_prompt.md、qwen_code_prompt.md、kimi_code_system_prompt.md、opencode_system_prompt.md、little_coder_system_prompt.md、deepseek_tui_prompts/…），力求逐字复刻目标 CLI 的提示结构。

harness_guidance（guidance.rs，默认 on）：在 base_instructions 前追加一段 OI 自己的 <extra_instruction> 可靠性指令块。实现上 guidance_for_harness（guidance.rs:3）对 KimiCli 与 KimiCode 两者返回 KIMI_CLI_GUIDANCE，其余全返回 None。（注意：docs/harness.md:155 只说「Today it only adds extra guidance for kimi-cli」——文档与代码存在轻微出入，代码里 kimi-code 也吃这段。）该指令内容包括：优先用工具而非长篇分析、多步任务尽早用 SetTodoList、用专用文件工具而非 Python/shell 读改文件、失败后先读源码与检查输出再改、别用 fallback chain 掩盖失败、两次修复失败就停止乱试等（guidance.rs:23–39）。

Router / 编排（任务分解、多 agent、子 agent）

两个「router」含义不同，勿混：

harness 路由（OI 独创）：harness/routing.rs::resolve_stream_transport_route（L56）按 WireApi × Harness 严格映射到传输/仿真路由：

  • Responses wire → 默认 ResponsesApi；claude-code/-bare 走 ClaudeCodeResponses(Full|Bare)
  • Chat wire → 各 chat harness 走 ChatHarness(具体)，其余走 ChatCompletionsCompat
  • Messages wire → 仅 claude-code/-bare（→ MessagesHarness::ClaudeCode）与 zcode（→ MessagesHarness::ZCode）合法；其余组合直接返回 CodexErr::InvalidRequest（routing.rs L108–150，逐个 harness 给出报错文案）。

工具路由（Codex 底座）：tools/router.rs + tools/orchestrator.rs + tools/parallel.rs（并行工具调用）。

多 agent / 子 agent（Codex 底座，OI 默认开 multi_agent=true）：core/src/agent/control.rs（AgentControl）+ control/spawn.rs；工具侧 handlers/multi_agents.rs 与 multi_agents_v2/。子 agent 从当前 turn 的有效 config 派生（继承 provider/approval/sandbox/cwd，可叠加 role）。角色 core/src/agent/role.rs（default/worker/explorer，见 docs/subagents.md）。限制：agents.max_threads / max_depth / job_max_runtime_seconds；exceeds_thread_spawn_depth_limit。TUI /agent。

任务分解：handlers/plan.rs（TodoList/plan 工具）；agent_jobs 支持 CSV/批量 worker 并行。

Skill / 插件体系

Skills（Codex 底座）：skills/ crate + core-skills/；docs/skills.md。folder + SKILL.md（frontmatter name/description），metadata-first 懒加载，匹配到才载全文。位置优先级 .agents/skills/ > ~/.agents/skills/ > bundled。会话把可用 skills 组装成 <skills_instructions> developer block，各 harness 用 session_skills.rs 解析后按原生格式重渲染。

内置样例 skill：skills/src/assets/samples/qa-testing/SKILL.md（computer-use/QA：用 vercel-labs agent-browser 驱动浏览器、trycua/cua 的 cua-driver 驱动原生 GUI，按需经审批流安装）——这就是 README 说的「QA skill / Computer Use」，当前是一个 skill，而非旧版的 os mode。

Plugins：plugin/ + core-plugins/ crate；handlers/list_available_plugins_to_install.rs / request_plugin_install.rs；built_tools 里 plugins_manager.plugins_for_config 载入。Connectors：connectors/ crate（apps/MCP connector 合并）。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

主要机制 = learning memory 两阶段管线（见「记忆」维度）：从历史 rollout 自动抽记忆 → consolidation 子 agent 更新 MEMORY.md / skills/，跨会话复用。默认关。

无「eval 驱动纠错 / 训练回灌」的在线自改进（模型权重层面）。harness 层是静态适配（人工按各 CLI 逐字复刻 prompt/schema），非模型自学。循环内的「失败后换思路」属 prompt guidance（guidance.rs 的 kimi 指令、各 harness system prompt），不是结构化 self-improve 组件。→ 结论：除 memories 外，自进化基本未实现。

可观测性（日志 / trace 格式）

Codex 底座，覆盖完整。

  • OpenTelemetry：otel/ crate（config/otlp/provider/metrics/events/trace_context，W3C traceparent 注入）。
  • 工具调用 trace：core/src/tools/tool_dispatch_trace.rs；rollout-trace/ crate（把会话重建成 trace：tool_dispatch / inference / compaction / thread / reducer）。
  • rollout 落盘：rollout/ crate（recorder + SQLite state_db + persistence_metrics/sqlite_metrics）；core/src/rollout.rs。
  • 大量 tracing span（turn.rs 里 trace_span!/instrument）；analytics/ crate、turn.rs::track_turn_resolved_config_analytics。
  • feedback/ crate、response_debug_context/、prompt_debug.rs（可 dump 送给模型的最终 prompt）。

安全与权限（审批门、密钥管理）

Codex 底座，两条正交控制（docs/sandbox.md）：① sandbox_mode（read-only / workspace-write / danger-full-access，技术边界）；② approval_policy（untrusted / on-request / never，何时暂停问人）。TUI /permissions。

  • 审批评估：core/src/safety.rs::assess_patch_safety 返回 SafetyCheck::{AutoApprove{sandbox_type,user_explicitly_approved}, AskUser, Reject{reason}}；命令侧同构逻辑。AskForApproval::{Never,OnRequest,Granular,UnlessTrusted}；PermissionProfile::{Disabled,External,...}。写到 writable roots 外 / 只读沙箱 → Reject。fail-closed：无法强制沙箱时不静默裸跑（safety.rs get_platform_sandbox None 分支 + docs）。
  • 网络审批：tools/network_approval.rs、core/src/network_policy_decision.rs、network-proxy/ crate、[sandbox_workspace_write] network_access。
  • 受保护路径：.git/、agent 配置目录（docs/sandbox.md「Protected Paths」）。
  • 密钥/凭证：keyring-store/ crate、secrets/ crate、login/、aws-auth/；memories 管线做 secret 脱敏。
  • 一键去防护：--yolo / --dangerously-bypass-approvals-and-sandbox（去审批 + 去沙箱）。
  • 相关：handlers/request_permissions.rs、handlers/request_user_input.rs、elicitation.rs、shell_escalation/ crate、execpolicy/execpolicy-legacy crate（命令白/黑名单策略）。

沙箱与执行隔离

Codex 底座，跨平台原生沙箱（sandboxing/ crate + linux-sandbox/ / windows-sandbox-rs/ crate）：

  • macOS：Seatbelt（seatbelt.rs + seatbelt_base_policy.sbpl / seatbelt_network_policy.sbpl / restricted_read_only_platform_defaults.sbpl）。
  • Linux/WSL：seccomp + Landlock（landlock.rs，SandboxType::LinuxSeccomp）+ bubblewrap（bwrap.rs，bwrap/ crate）。
  • Windows：windows.rs + core/src/windows_sandbox*.rs + windows-sandbox-rs/（WindowsSandboxLevel）。
  • sandboxing/src/manager.rs：SandboxType{None,MacosSeatbelt,LinuxSeccomp}，get_platform_sandbox() 按平台选。

命令执行：core/src/exec.rs / exec_env.rs / exec_policy.rs；持久 shell 会话 handlers/unified_exec/（exec_command + write_stdin）；exec-server/ crate。执行时按 SafetyCheck 决定是否包 sandbox。danger-full-access / --yolo = 无沙箱（仅供外部隔离 VM/容器用）。

与模型的协同设计

**这是 OI 的立身之本。**harness 仿真层 = 「按模型家族选最优 harness」。docs/harness.md:76–88「Automatic Harness Defaults」：Anthropic/Claude 或任何 messages provider → claude-code；Kimi/Moonshot → kimi-cli；Qwen/QwQ/DashScope → qwen-code；DeepSeek → deepseek-tui。显式 harness = "..." 覆盖自动推断。

每个 harness 针对该模型/CLI 定制：prompt、tool schema、消息转换、reasoning-effort 映射、prompt-cache key、thinking config（claude-code 加 Anthropic thinking + context-management + title 生成请求）、startup 合成 setup 交换（qwen-code 注入日期/OS/cwd/目录列表，docs/harness.md:131–139）。

非工具协议的模型协同：swe-agent / mini-swe-agent / terminus-2 用「讨论 + 命令」文本循环——从模型纯文本响应里解析 shell 命令，OI 注入对应 action，输出作为 observation 回灌（request.rs 的 inject_*_action_calls postprocess；swe-agent 默认命令 timeout 30s，docs/harness.md:145）。这是为不擅长 function-calling 的低成本模型设计。

传输层三种 wire：Responses（OpenAI 新）/ Chat（chat-completions）/ Messages（Anthropic），chat-wire-compat/ crate 做转换；三者与 harness 的合法组合由 routing.rs 严格约束（见「Router / 编排」）。

轨迹利用（session/trajectory 是否反哺训练/评测）

落盘完备：rollout/（会话/轨迹 → 文件 + SQLite state DB）、rollout-trace/（重建 trace）、message-history/、thread-store/、thread-manager*。

反哺方向 = 记忆，不是训练：Phase 1 记忆管线直接消费历史 rollout（从 state DB 按 age/idle/claim 规则选 rollout → 模型抽取结构化记忆 → 存回 DB → Phase 2 consolidation 子 agent 更新 MEMORY.md）。即轨迹回灌到跨会话长期记忆，改善后续 session 表现。

无证据表明轨迹用于训练模型权重或跑自动 eval 打分——这是终端产品，不含训练/评测回路。external-agent-sessions / external-agent-migration crate 是导入其它 agent 会话，非训练。→ 训练回灌未实现；评测回灌未见。

与同类 harness 的关键差异（1-3 条）

  1. 它本身是「harness 的 harness」：OI 不发明一套自己的 agent runtime，而是 fork Codex 后叠一层仿真层，去逐字复刻 claude-code/kimi-cli/qwen-code/deepseek-tui/swe-agent 等他家 CLI 的表面（prompt + tool schema + wire）。同类 harness（Codex、Claude Code 本体）是「一套 runtime 服务一套 prompt」，OI 是「一套 runtime 冒充 N 家 CLI」。
  2. 动机是「给低成本开源模型配最优 harness」：路由默认按模型家族选 harness（Kimi→kimi-cli、Qwen→qwen-code…），并为弱 function-calling 模型提供 swe-agent 文本命令循环这一无 tool-schema 路径。这在通用 harness 里少见。
  3. 绝大多数「重」能力其实是 Codex 原生（loop/sandbox/memory/subagent/otel/MCP），OI 的净增量集中在 core/src/harness/ 一层 + 默认启用若干 Codex feature + QA skill + 品牌文档。评估 OI 时须把「Codex 能力」与「OI 增量」分开记。

原始源码定位

  • repo: https://github.com/OpenInterpreter/open-interpreter
  • commit/version analyzed: 764a96ee05853d5494d7e711eefecec57ab712ef（2026-07-06 17:59:23 -0700，“Disable inherited CI wrapper workflows”；Apache-2.0；Rust）
  • 关键文件列表（相对 repo 根）：
    • codex-rs/core/src/harness/routing.rs — harness 路由核心
    • codex-rs/core/src/harness/request.rs — harness 集成点 build_chat_harness_request
    • codex-rs/core/src/harness/guidance.rs — harness_guidance 可靠性指令（kimi-cli/kimi-code）
    • codex-rs/core/src/harness/session_skills.rs — skills block 按 harness 重渲染
    • codex-rs/core/src/harness/minimal.rs — harness 实现范例
    • codex-rs/core/src/harness/<name>.rs + <name>_prompt.md / <name>_tools.json — 各家 harness 复刻（claude_code / kimi_cli / qwen_code / deepseek_tui / swe_agent / zcode / …）
    • codex-rs/tools/src/harness.rs — Harness enum + from_config_name
    • codex-rs/core/src/session/turn.rs — 主 loop run_turn（L144）
    • codex-rs/core/src/safety.rs — assess_patch_safety / SafetyCheck
    • codex-rs/core/src/tools/（registry.rs / router.rs / handlers/…）— 工具体系
    • codex-rs/sandboxing/src/（manager.rs / seatbelt.rs / landlock.rs / bwrap.rs / windows.rs）— 沙箱
    • codex-rs/memories/（+ core/src/memories/）— 长期记忆两阶段管线
    • codex-rs/otel/、codex-rs/rollout/、codex-rs/rollout-trace/ — 可观测/轨迹
    • codex-rs/core/src/agent/（control.rs / role.rs）— 多 agent/子 agent
    • docs/harness.md（一等设计文档）、docs/memories-pipeline-README.md、docs/sandbox.md、docs/subagents.md、docs/skills.md、docs/hooks.md

说明：本轮精读了 routing / request / guidance / session_skills / minimal + turn.rs + safety.rs + harness.md；claude_code.rs(4666 行) 等大 harness 文件未逐行读，具体某 harness 的 prompt/schema 细节需去 core/src/harness/<name>.rs + 同目录资源文件核对。

一手源存档（sources/）

存于 /Users/zhao/projects/self-wiki/ai-research/sources/harness/open-interpreter/：

  • NOTES.md — 第一阶段源码级调研笔记（含 12 维度 + 关键文件清单）
  • src/routing.rs — harness 路由（含全部 wire×harness 合法/非法映射与单测）
  • src/request.rs — harness 集成点
  • src/guidance.rs — harness_guidance（kimi 可靠性指令全文）
  • src/session_skills.rs — skills block 重渲染
  • src/harness_minimal_example.rs — minimal harness 实现（minimal.rs 副本）
  • src/tools_harness_enum.rs — Harness enum + from_config_name（tools/src/harness.rs 副本）
  • src/turn.rs — 主 loop
  • src/safety.rs — 审批安全评估
  • docs/harness.md — harness 模式一等设计文档（官方）
  • docs/memories-pipeline-README.md、docs/memories.md — 记忆管线
  • docs/sandbox.md、docs/subagents.md、docs/skills.md、docs/hooks.md — 各子系统官方文档
  • docs/repo-README.md — 仓库 README（含 fork 声明）

关系图谱

反向链接