Open Interpreter 配置全指南：从 `~/.openinterpreter/config.toml` 示例模板到 Profiles 与 CLI 实战

~/.openinterpreter/config.toml 是 Open Interpreter 的全局配置文件，决定模型、沙箱、审批、历史、Profiles、自定义 Provider、MCP 服务器与功能开关等全部行为。本文以仓库中官方给出的 示例配置模板 为骨架，逐段解读每个键的取值与作用，并对照 配置参考 与 config 源码 进行纵深扩充。读完你将能亲手搭建一份可用的 config.toml，并熟练使用 --profile 与 -c 实现配置切换与单次覆盖。

配置文件放哪里：位置、可选性与权威 Schema

示例配置文档开篇就明确了使用方式：将文件放入 ~/.openinterpreter/config.toml，然后按自己的工作流编辑。这是 Open Interpreter 的全局（用户级）活动配置入口，所有命令行会话启动时都会读取。

需要特别注意的是文档反复强调的一个原则：此处的每个键都是可选的。config.toml 不是一份必须填满的清单，而是一套"增量覆盖"模板——你不写某个键，程序就使用该键的默认值或由所选 Provider 决定的推荐值。

官方文档同时指出：每个字段的权威来源是自动生成的模式文件 codex-rs/core/config.schema.json。因此当你对某个键的取值不确定，或遇到"键名拼写是否正确""某个表是否支持未知字段"这类问题时，直接查阅该 JSON Schema 是最可靠的方式。从源码结构看，配置的解析、校验、合并与分层逻辑集中在 codex-rs/config/src 下：types.rs 定义各配置类型与枚举、mcp_types.rs 定义 MCP 服务器结构、profile_toml.rs 处理 Profiles 的 TOML 表示，loader/ 目录承载加载与分层合并逻辑。更完整的背景可进一步阅读 配置文档。

完整示例模板总览

以下即官方 示例配置模板 的全文，它按功能把配置划分为六大区块：模型与 Provider、Harness 兼容、沙箱与审批、日志与历史、Profiles、自定义 Provider、MCP 服务器与 Features。后续小节将逐段拆解：

# ---------------------------------------------------------------
# Model and provider
# ---------------------------------------------------------------

model_provider = "openai"
model = "gpt-5.1-codex"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
personality = "pragmatic"
web_search = "cached"

# ---------------------------------------------------------------
# Harness compatibility
# ---------------------------------------------------------------

# Leave unset to choose the recommended harness for the selected provider.
# harness = "kimi-code"
harness_guidance = true

# ---------------------------------------------------------------
# Sandbox and approvals
# ---------------------------------------------------------------

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false
writable_roots = []

# ---------------------------------------------------------------
# Logging and history
# ---------------------------------------------------------------

log_dir = "~/.openinterpreter/log"

[history]
persistence = "save-all"
max_bytes = 104857600

# ---------------------------------------------------------------
# Profiles
# ---------------------------------------------------------------

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.review]
model = "gpt-5.1-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

# ---------------------------------------------------------------
# Custom provider
# ---------------------------------------------------------------

[model_providers.example]
name = "Example"
base_url = "https://api.example.com/v1"
env_key = "EXAMPLE_API_KEY"
wire_api = "responses"

# ---------------------------------------------------------------
# MCP servers
# ---------------------------------------------------------------

[mcp_servers.docs]
command = "docs-server"
default_tools_approval_mode = "prompt"

[mcp_servers.docs.tools.search]
approval_mode = "approve"

# ---------------------------------------------------------------
# Features
# ---------------------------------------------------------------

[features]
hooks = true
multi_agent = true
shell_tool = true
shell_snapshot = true
unified_exec = true
memories = false
apps = false
plugins = false
undo = false

模型与 Provider 配置

模板第一段配置会话最核心的部分——用什么模型、花多少推理预算、以什么风格交流：

model_provider = "openai"
model = "gpt-5.1-codex"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
personality = "pragmatic"
web_search = "cached"

键	取值	作用
model	string	默认模型 ID。
model_provider	provider id	用于 model 的提供商条目（在 [model_providers.*] 表或内置 Provider 目录中选择）。
model_reasoning_effort	minimal、low、medium、high、xhigh	对支持它的模型的推理预算。模板用 medium 作为日常默认，是速度与深度的折中。
model_reasoning_summary	auto、concise、detailed、none	显示多少推理摘要。auto 让程序自动决定，none 完全不展示。
personality	friendly、pragmatic、none	TUI 中的沟通风格。pragmatic 侧重直接高效，适合编码任务。
web_search	cached、live、disabled	网络搜索行为：cached 优先使用缓存、live 实时搜索、disabled 关闭。

值得说明的是 model_provider 与 model 是配套关系：model 是默认模型 ID，而 model_provider 指向"哪个 Provider 为这个模型服务"。模板以 openai + gpt-5.1-codex 为例，但 Open Interpreter 面向开放模型生态（例如 Kimi K3、GLM 5.3 等），你可以把 model_provider 指向 内置 Provider 目录 或自己在 [model_providers.*] 中定义的服务。完整模型与 Provider 能力矩阵可参考 models 文档 与 providers 文档。

Harness 兼容配置

# Leave unset to choose the recommended harness for the selected provider.
# harness = "kimi-code"
harness_guidance = true

• harness（string）：Open Interpreter 的框架（harness）兼容模式，用于让不同 Provider/模型的指令格式与工具调用协议对齐。模板中的注释给出关键提示：保持未设置，即可自动为所选 Provider 选择推荐的 harness；被注释掉的 kimi-code 只是一个可选项示例。
• harness_guidance（boolean）：在框架模式下是否允许 Open Interpreter 提供自己的引导（guidance）。

日常使用建议：除非你明确知道需要强制某个 harness（例如调试某些开放模型的兼容性问题），否则应让该键留空，交给自动选择逻辑处理。

沙箱模式与审批策略

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false
writable_roots = []

这是安全模型的核心。三个取值分别代表不同的本地命令沙盒强度：

sandbox_mode	含义
read-only	只读：代理不能修改工作区文件，适合审查与只读调研场景。
workspace-write	可写工作区：代理可以修改当前项目文件，但系统文件等仍被隔离。
danger-full-access	完全访问：不施加沙箱限制，仅在你信任任务与模型时使用。

approval_policy 决定运行命令前何时向你询问，三个取值对应三种风险姿态：

approval_policy	含义
untrusted	最保守：对未经信任的来源/命令要求更频繁的确认。
on-request	按需询问：仅在需要时弹出审批。模板采用此值，兼顾效率与可控。
never	永不询问：全程自动放行，高风险，仅适合完全可信的自动化场景。

与之配套的 [sandbox_workspace_write] 表细化了工作区沙箱的参数：

• network_access（boolean）：是否允许沙箱内命令访问网络。模板设为 false——多数本地编码任务不需要代理访问网络。
• writable_roots（string 数组）：除工作区外额外允许写入的路径根。模板留空 []，即不额外开放任何目录。

配置参考 还展示了该表支持的两个补充键：exclude_tmpdir_env_var 与 exclude_slash_tmp（是否排除把 $TMPDIR 环境变量与 /tmp 暴露给沙箱）。在 types.rs 中，SandboxWorkspaceWrite 结构体同样定义着这四个字段（writable_roots、network_access、exclude_tmpdir_env_var、exclude_slash_tmp），印证了配置层与源码类型的一一对应。

实践建议：如果你需要更细粒度的文件系统/网络访问控制（例如"工作区可写但 **/*.env 拒绝""只放行特定域名"），请使用权限配置文件（default_permissions + [permissions.*] 表），而不要在单个活动配置中把 sandbox_* 与权限系统混用。完整示例见 permissions 文档。

日志目录与会话历史保留

log_dir = "~/.openinterpreter/log"

[history]
persistence = "save-all"
max_bytes = 104857600

• log_dir（path）：日志写入目录，默认指向用户目录下的 .openinterpreter/log。
• [history] 表控制会话历史记录行为：
  • persistence：save-all 表示把全部历史条目保存到磁盘；如果你想"会话结束不落盘"，则设为 none。在 types.rs 的 HistoryPersistence 枚举中，这两个取值对应 SaveAll（默认值）与 None。
  • max_bytes（usize）：历史文件的最大字节数。模板中的 104857600 恰为 100 MiB。源码注释明确说明：文件一旦超过该上限，最旧的条目会被丢弃（见 types.rs 的 History 结构），因此你无需手动清理日志文件。

Profiles：一套配置，多套场景

Profiles 是模板中最实用的进阶功能：它继承顶层已设置的键，只对被覆盖的键生效，从而让你在共享同一份基础配置的同时，快速切换不同任务场景。

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.review]
model = "gpt-5.1-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

模板定义了两个具有代表性的 Profile：

• profiles.fast：日常轻量任务。换用更小的模型 gpt-5.1-codex-mini，并把推理预算降到 low，换取低延迟。
• profiles.review：代码审查场景。用回完整模型、把推理预算拉到 high 以获得更深入的思考，同时强制 sandbox_mode = "read-only"——审查任务只读不写，从配置层面杜绝代理意外修改代码。

使用 Profile 运行非常简单：

interpreter --profile review

这条命令会以 review 场景（完整模型 + 高推理预算 + 只读沙箱）启动会话。Profile 的 TOML 表示与合并逻辑位于 profile_toml.rs 与配置加载层，从源码结构看，每个 Profile 都沿用顶层配置作为默认基底，仅覆盖自身声明的键——这正是它"薄覆盖、快切换"的设计来源。

自定义 Provider：接入任意 OpenAI 兼容服务

[model_providers.example]
name = "Example"
base_url = "https://api.example.com/v1"
env_key = "EXAMPLE_API_KEY"
wire_api = "responses"

当内置 Provider 目录不满足需求时，你可以通过 [model_providers.<id>] 表声明一个自定义 Provider，然后在顶层用 model_provider = "<id>" 引用它：

• name：展示名称。
• base_url：API 端点，指向任一 OpenAI 兼容网关。
• env_key：存放 API 密钥的环境变量名（此处为 EXAMPLE_API_KEY），避免把密钥写死在配置里。
• wire_api：线协议类型。模板取 responses（Responses API）；多数兼容服务可能要求 chat（Chat Completions 协议）。

配置参考 为 Provider 表补充了三个常用于生产环境的调优键，可按需加入模板：

[model_providers.example]
name = "Example"
base_url = "https://api.example.com/v1"
env_key = "EXAMPLE_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

此外，Provider 认证也可以委托给外部命令动态获取令牌（适合短期凭证自动刷新的场景）：

[model_providers.example.auth]
command = "example-token"
args = ["print"]
refresh_interval_ms = 300000
timeout_ms = 5000

MCP 服务器：按需挂载工具并分级审批

模板第三大区块演示了如何把外部 MCP 工具服务器接入会话：

[mcp_servers.docs]
command = "docs-server"
default_tools_approval_mode = "prompt"

[mcp_servers.docs.tools.search]
approval_mode = "approve"

• [mcp_servers.docs] 声明一个名为 docs 的 MCP 服务器，command = "docs-server" 表示以 stdio 子进程方式启动它。
• default_tools_approval_mode = "prompt"：为该服务器未单独配置的所有工具设置默认审批模式（prompt 即先提示再执行）。
• [mcp_servers.docs.tools.search] 是工具级覆盖：只把 search 这一个工具单独升级为 approve（显式批准）。

也就是说，MCP 工具的审批可以做到"服务器级默认 + 工具级例外"的双层精细控制。与之对应，源码 mcp_types.rs 中的 McpServerConfig 结构明确持有 default_tools_approval_mode 字段与 tools: HashMap<String, McpServerToolConfig> 字段——后者即按工具名索引的逐工具审批配置，正是 [mcp_servers.docs.tools.search] 语法的类型基础。

配置参考 还给出了该表的扩展字段，适合模板上手后进一步加固：

[mcp_servers.docs]
command = "docs-mcp"
args = ["--stdio"]
env = { DOCS_TOKEN = "env:DOCS_TOKEN" }
startup_timeout_sec = 10
tool_timeout_sec = 60
required = false
enabled_tools = ["search", "read"]
disabled_tools = ["delete"]
default_tools_approval_mode = "prompt"

[mcp_servers.docs.tools.search]
approval_mode = "approve"

其中 enabled_tools/disabled_tools 是显式的工具白名单/黑名单，required = false 表示该服务器初始化失败不阻断会话，startup_timeout_sec 与 tool_timeout_sec 分别限制启动与单次工具调用的超时。若你接入的是 HTTP MCP 服务器，则使用 url、bearer_token_env_var、http_headers、env_http_headers 等字段而非 command。更完整的 MCP 使用说明见 MCP 文档。

Features 功能开关：该开哪个，该关哪个

模板最后一段用一个 [features] 表集中控制"产品功能表面"：

[features]
hooks = true
multi_agent = true
shell_tool = true
shell_snapshot = true
unified_exec = true
memories = false
apps = false
plugins = false
undo = false

这里模板做了一个值得借鉴的安全姿态：默认把涉及扩展生态与状态变更的功能（memories、apps、plugins、undo）关掉，只开启核心编码能力。各功能键与官方默认姿态对照如下（来自 配置参考）：

键	默认姿态	作用
features.hooks	on	生命周期钩子。
features.multi_agent	on	子代理工具与 /agent 命令。
features.shell_tool	on	内置 shell 命令工具。
features.shell_snapshot	on	Shell 环境快照。
features.unified_exec	默认开启，平台不支持时除外	基于 PTY 的 exec 工具。
features.memories	off	持久记忆的生成/使用。
features.apps	off	应用/连接器表面。
features.plugins	off	插件包。
features.undo	off	在支持的平台上提供撤销。
features.network_proxy	off	沙盒网络代理控制。

模板显式列出这些键的好处是把决策写进配置、可审计可复现；如果你确实需要记忆、插件或应用能力，把对应键翻转为 true 即可。更深入的信息可分别参考 hooks 文档、memories 文档、plugins 文档 与 subagents 文档。

CLI 实战：Profile 切换与单次覆盖

配置文件本身只是起点，模板还给出了两条最常用的命令行使用方式。

以某个 Profile 启动：

interpreter --profile review

为单次运行覆盖一个值，使用 -c 参数。注意 TOML 值需要嵌套引号转义：

interpreter -c approval_policy='"never"' "fix the failing tests"

这条命令在不改动配置文件的前提下，把本次会话的 approval_policy 临时覆盖为 "never"（免审批），然后直接让代理执行"修复失败的测试"这一自然语言任务。-c 适合 CI、脚本或一次性实验场景——把"会动的策略"留在命令行，把"稳定的基线"留在 config.toml，是这套配置体系的推荐分工。

从模板到生产：一张检查清单

综合官方模板与配置参考，落地一份生产级 ~/.openinterpreter/config.toml 时可依次自检：

1. 模型：model_provider 是否指向正确的 Provider 目录，model 是否是目标模型 ID，model_reasoning_effort 是否符合任务的深度/成本平衡（minimal~xhigh 五档）。
2. Harness：是否保持了未设置状态以使用自动推荐；若强制指定请确认该 Provider 确实支持。
3. 沙箱：sandbox_mode 是否与信任边界匹配（审查用 read-only、日常编码用 workspace-write、仅可信场景用 danger-full-access）；是否需要额外开放 writable_roots 或 network_access。
4. 审批：approval_policy 的取值是否与运行环境一致（交互终端用 on-request、无人值守 CI 再考虑 never）。
5. 历史：确认 max_bytes 是否符合磁盘预期（104857600 = 100 MiB），敏感环境可把 persistence 设为 none。
6. Profiles：为"快速试跑""深度审查"等重复场景抽象出 [profiles.*]，避免重复传参。
7. 自定义 Provider：密钥走 env_key 指向的环境变量，必要时补齐重试与流式超时参数。
8. MCP：对每个挂载的服务器明确默认审批模式，并对高影响工具做工具级覆盖。
9. Features：关闭当前不需要的扩展面，保持攻击面最小。

完成以上配置后，配合 interpreter --profile <name> 与 interpreter -c key=value "任务"，即可在不同工作流之间零成本切换。所有键的最终解释权以自动生成的 config.schema.json 为准——当你需要排查或升级配置时，那是比任何教程都更新的第一手资料。