Project Instructions

Commands

• pnpm test runs unit tests.
• pnpm lint must pass before final changes.
• Use pnpm typecheck after editing TypeScript types.

Conventions

• Keep server code under src/server.
• Keep UI components small and colocated with their tests.
• Prefer existing helpers in src/lib.

Cautions

• Do not edit generated files under src/generated.
• Ask before changing database migrations.

仓库中关于 `AGENTS.md` 的作用域、`project_doc_max_bytes` 上限与 `/init` 流程的完整说明，见 [docs/agents_md.md](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/docs/agents_md.md?utm_source=gitcode_repo_files)。

## Config Profiles：模型、提供商、沙箱与审批的默认值

当定制目标不是“规则”而是“行为默认值”（默认模型、提供商、沙箱模式、审批策略、功能开关）时，应当使用 TOML 配置文件，完整参考见 [docs/config.md](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/docs/config.md?utm_source=gitcode_repo_files)。

### 配置文件的存放层级

- 用户级配置：`~/.openinterpreter/config.toml`；
- 项目级配置：可信项目内的 `.openinterpreter/config.toml`；
- 一次性覆盖：命令行 `-c key=value`，仅对当次调用生效。

官方给出的配置优先级（高者覆盖低者）为：

1. 内置默认值
2. 系统或被托管配置
3. 用户配置
4. 可信项目配置
5. 所选 profile
6. CLI 覆盖（`-c`、`--enable`、`--disable` 或专用 flags）

这套优先级意味着：你可以放心在项目里放 `.openinterpreter/config.toml`，它既不会破坏你的个人全局偏好，也会被更上层的显式命令覆盖。在 TUI 中可用 `/debug-config` 查看生效值及其来源（对应实现见 [docs/config.md](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/docs/config.md?utm_source=gitcode_repo_files) 与 schema 文件 [codex-rs/core/config.schema.json](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/core/config.schema.json?utm_source=gitcode_repo_files)，后者可用于编辑器补全或 CI 校验）。

### 常见设置

```toml
model = "gpt-5.1-codex"
model_provider = "openai"

# "minimal" | "low" | "medium" | "high" | "xhigh"
model_reasoning_effort = "medium"

# "auto" | "concise" | "detailed" | "none"
model_reasoning_summary = "auto"

# "read-only" | "workspace-write" | "danger-full-access"
sandbox_mode = "workspace-write"

# "untrusted" | "on-request" | "never"
approval_policy = "on-request"

# "friendly" | "pragmatic" | "none"
personality = "pragmatic"

web_search = "cached"
log_dir = "~/.openinterpreter/log"

定义并使用 Profile

Profile 是“一组命名好的设置”，很适合在不同工作模式间切换：

[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"

启用方式：

interpreter --profile review

例如上面的 review profile 就把沙箱锁成只读、推理强度拉满，天然适合做代码评审；fast 则用轻量模型快速跑日常任务。注意 -c 接受 TOML 风格的值，字符串要加引号防止 shell 剥掉：

interpreter -c model='"gpt-5.1-codex-mini"' -c approval_policy='"never"'

功能开关（feature flags）也有短形式：interpreter --enable hooks --disable memories。可选的实验性行为统一放在 [features] 下，如：

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

此外，仓库还提供 harness 设置用于切换兼容模式（native、Claude Code、DeepSeek TUI、Kimi Code、Qwen Code、SWE-agent、minimal 等），以及 shell_environment_policy、[history]、[memories] 等更多细节——需要完整参数时可查阅 docs/config.md 与 docs/config-reference.md。

Skills：把重复流程打包成按需加载的技能

“流程性的、反复执行的”定制内容应放进 Skills。一个 skill 就是一个包含 SKILL.md（必需）的文件夹，可附带 scripts/、references/、assets/ 等目录：

cut-release/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Open Interpreter 先读取 skill 的元数据，只有当请求匹配时才加载完整内容——这正是“Keep Instructions Small”理念在机制层面的实现。

一个最小 skill 的 SKILL.md 长这样：

---
name: cut-release
description: Prepare a release by testing, updating changelog, and tagging.
---

When asked to cut a release:

1. Run the test suite.
2. Update the changelog.
3. Bump the version according to semver.
4. Prepare the commit and tag, but ask before publishing.

其中 front-matter 的 description 控制 skill 何时被选中，所以描述要写得具体。适合做成 skill 的典型场景有：发布检查清单、内部报告生成、仓库专属迁移流程、设计与评审标准、需要固定执行顺序的命令序列。

存放位置与优先级

路径	作用域
.agents/skills/	仓库或目录级技能
~/.agents/skills/	个人技能
Bundled skills	内置工作流

名字冲突时，本地技能优先于个人与内置技能。官方建议新技能一律放在 .agents/skills（共享、与工具无关的目录），这样其他兼容智能体无需导入即可复用；~/.openinterpreter/skills/ 仍会被读取，但只是旧版兼容回退，不应再用来放新建的用户技能。

需要注意的是，skill 脚本同样走正常的沙箱与审批控制——一个 skill 应说明脚本做什么、何时运行，而不能指望绕过权限（docs/skills.md）。在 TUI 中用 /skills 浏览已安装技能。

MCP：接入外部工具与数据源

当定制对象是“智能体应显式调用的外部能力”时，使用 Model Context Protocol（MCP）。它适合问题跟踪系统、私有文档、数据库、内部 CLI 等场景——比起用 shell 命令“即兴发挥”，显式注册的工具更可控、可审计。

接入 stdio 服务器

在 ~/.openinterpreter/config.toml 中配置：

[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
env = { LINEAR_API_KEY = "env:LINEAR_API_KEY" }

或使用 CLI：

interpreter mcp add linear -- npx -y @linear/mcp-server

接入 HTTP 服务器

[mcp_servers.docs]
url = "https://mcp.example.com"
bearer_token_env_var = "DOCS_MCP_TOKEN"

CLI 形式：

interpreter mcp add docs --url https://mcp.example.com \
  --bearer-token-env-var DOCS_MCP_TOKEN

服务器管理命令包括 interpreter mcp list/get/remove/login/logout，OAuth 登录适用于支持 OAuth 的 streamable HTTP 服务器；TUI 中 /mcp 查看已加载服务器，/mcp verbose 查看工具详情。更完整的配置面（审批模式、工具过滤、超时、环境变量注入、启用/禁用）以及安全问题请参考 docs/mcp.md。

Hooks：把策略变成每次必跑的确定性脚本

Hooks 是 Open Interpreter 的“确定性层”：在智能体生命周期的事件点上运行受信任的命令，用于策略检查、日志记录、提示词扫描、自定义上下文注入或运行后校验。它由 [features] hooks = true 开启（默认开启），只有当你想彻底关闭生命周期脚本时才置为 false。

Hooks 在配置层旁发现：用户级 ~/.openinterpreter/hooks.json、项目级 .openinterpreter/hooks.json（均可内联在 config.toml），以及插件携带的 hook。多来源命中时全部执行——高层配置不会替换低层的 hooks。

信任模型很关键：非托管的命令 hook 必须先被审查并信任才会运行，信任记录绑定到精确的 hook 定义，所以 hook 一旦改动就需要重新审查。TUI 中用 /hooks 管理；对已由外部完成校验的自动化流程可传 --dangerously-bypass-hook-trust，但应极少使用。

事件与 JSON 形式

支持的事件包括 SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SubagentStart、SubagentStop、Stop 等。示例（在 Bash 工具运行前拦截）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .openinterpreter/hooks/pre_tool_use.py",
            "timeout": 30,
            "statusMessage": "Checking command"
          }
        ]
      }
    ]
  }
}

TOML 内联等价形式：

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 .openinterpreter/hooks/pre_tool_use.py"
timeout = 30
statusMessage = "Checking command"

matcher 是正则表达式，可匹配工具名（如 Bash、^apply_patch$、Edit|Write、mcp__filesystem__read_file）、会话事件（startup|resume|clear|compact）或压缩事件（manual|auto）。命令 hook 从 stdin 收到一个含 session_id、cwd、hook_event_name、model 等字段的 JSON 对象；部分事件能注入模型可见上下文，部分能阻止/拒绝工具调用——例如 PreToolUse hook 可以这样拒绝一条命令：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by repository policy."
  }
}

官方明确提醒：Hooks 是护栏，不能替代沙箱与审批（docs/hooks.md）。

Subagents：用专用助手代理并行干活

当任务适合“拆给专门的小代理”时，可启用多代理特性并使用 Subagents。子代理是独立于主会话的 agent 线程，适合隔离调查、大范围代码搜索、评审扫描或并行探索。当前构建默认开启 [features] multi_agent = true，TUI 用 /agent 派发。

内置角色常见有 default（通用助手）、worker（聚焦执行/调查）、explorer（只读探索与总结），可用角色随构建与配置变化。

常用限制参数：

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

• max_threads：最大并发 agent 线程数；
• max_depth：agent 嵌套派生 agent 的深度；
• job_max_runtime_seconds：CSV/批处理 worker 作业的默认超时。

你也可以在配置里定义自定义角色，例如一个“只读探查者”：

[agents.explorer]
description = "Inspect code and report findings without editing."
developer_instructions = "Stay read-only. Prefer rg and direct file references."
model = "gpt-5.1-codex"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

可选的扩展字段还包括 nickname_candidates、mcp_servers 与 skill 配置。需要注意：子代理默认继承当前沙箱与审批姿态，除非角色配置收窄了它；即使子代理不是当前可见线程，审批提示也可能弹出（docs/subagents.md）。

Memories：跨会话的个人偏好（可选）

Memories 是承载稳定的个人偏好与长期工作习惯的实验性功能，默认关闭。启用方式：

[features]
memories = true

[memories]
use_memories = true
generate_memories = true