简介

Oh My Pi（命令行名 omp）是一款跑在终端里的 AI 编码智能体，官方口号是「一个内置 IDE 能力的编程智能体」（A coding agent with the IDE wired in）。它由 Stencil Labs 维护，派生自 Mario Zechner 的 Pi，整体重写为专注编程工作流的智能体：会话、子智能体、斜杠命令、扩展全部用 TypeScript 编写，底层搜索、Shell、AST、PTY、桌面控制等热路径用约 8 万行 Rust 实现并以 N-API 插件形式链接进同一个进程，全部代码采用 MIT 许可。

官方给出的规模数字：60+ 个模型提供商、31 个内置工具、14 种 LSP 操作、28 种 DAP 操作、约 80000 行 Rust 核心代码。同一个 omp 二进制可运行于 macOS、Linux 和 Windows，不需要 WSL 桥接。

• 官网：https://omp.sh/
• 文档：https://omp.sh/docs
• 仓库：https://github.com/can1357/oh-my-pi
• npm 包：@oh-my-pi/pi-coding-agent（bin 名为 omp）
• Discord：https://discord.gg/4NMW9cdXZa

核心特点与优势：

• 进程内原生实现： 不调用外部的 rg、grep、find、bash。ripgrep、glob、find 直接链接进进程；Shell 是自研的 bash 5.3 引擎，67 个命令行工具（ls、sed、sort、xargs，甚至 jq）被移植进 pi-builtins crate 在进程内运行，热路径上没有 fork/exec 往返。很多机器上根本没有那些外部程序，即便有，每次调用也要付一次进程往返的开销。
• Hashline 内容哈希编辑： 模型只需指向行锚点，不必重新输入要修改的内容，因此「空白字符对不上、反复报 string not found」这类失败被消除；文件若已被改动，锚点会失配，补丁会在破坏任何东西之前被拒绝。官方基准：Grok Code Fast 1 的编辑成功率从 6.7% 提升到 68.3%，Grok 4 Fast 的输出 token 减少 61%，MiniMax 通过率 2.1 倍，Gemini 3 Flash 比 str_replace 高 5 个百分点。
• 每次写入都接入 LSP： 要求重命名得到的就是真正的重命名，调用会走 workspace/willRenameFiles，文件移动前先更新重导出、barrel 文件和带别名的导入。诊断、跳转、符号、代码操作都作为工具暴露给模型。
• 驱动真正的调试器： 内置对 gdb、lldb-dap、codelldb、debugpy、dlv、rdbg、js-debug-adapter、netcoredbg、kotlin-debug-adapter、php-debug-adapter、bash-debug-adapter、dart/flutter-debug-adapter、elixir-ls-debugger 的识别，可以下断点、单步、看栈帧和变量，而不是到处加 print。
• 时间回溯式流规则（TTSR）： 规则平时休眠，正则或 AST 一旦命中就在 token 输出到一半时中止流，把规则作为系统提醒注入并从同一位置重试。纠偏能力不需要每轮都付出上下文开销，注入内容在上下文压缩后依然保留。
• 一等公民的子智能体： task 工具把任务分发到相互隔离的 worktree，每个 worker 有自己的工具集，最终产出经过 schema 校验的对象供父智能体直接读取，不用解析大段文字，并行 worker 之间也不会产生合并冲突或留下没人管的修改。Alt+A 打开 Agent Hub 查看实时对话、发送引导消息、唤醒挂起的 worker 或结束卡住的那个。
• advisor 第二个模型盯着每一轮： 独立的上下文和模型读取主智能体的每一轮，行内插入 nit（提醒）、concern（顾虑）或 blocker（硬性阻断）三级注释，因此能发现执行者匆忙略过的问题。
• GitHub 只是另一个文件系统： 16 种内部协议（pr://、issue://、agent://、skill://、ssh://、conflict://、security://、xd:// 等）在所有文件系统类工具中透明解析，read pr://1428 与 read src/foo.ts 返回同样的结构，grep 可以像遍历目录一样遍历 diff，agent://<id>/findings.0.path 能按路径从子智能体输出里取字段。合并冲突向 conflict://N 写入 @theirs、@ours 或 @base 即可解决，批量用 conflict://*。
• 继承你其他工具已经写好的配置： 首次运行时原生读取磁盘上已有的 8 种格式的规则、技能和 MCP 配置，来自 .claude、.cursor、.windsurf、.gemini、.codex、.cline、.github/copilot 和 .vscode，没有迁移脚本，没有 YAML 转 TOML。
• 代码执行可回调工具： 持久化的 Python 和 Bun worker，两个内核都能通过本地回环桥接回调智能体自己的 read、search、task。可以在 Python 里用 tool.read 加载 CSV，再用 JavaScript 绘图，全程不离开同一个单元格。
• 先预览再接受： ast_edit 返回带替换数量的 Proposed 卡片，改动处于暂存状态，智能体向 xd://resolve 写一行理由后 TUI 才变成 Accept 卡片并真正写盘，要么全部成功要么全部不做。
• 带优先级和结论的代码评审： /review 派生专门的评审子智能体并行审查，明确告诉你能不能发布，问题按 P0 到 P3 排序并给出置信度评分。
• omp commit 原子拆分： 把不相关的修改拆成按依赖排序的原子提交，存在循环依赖时在写入任何内容前拒绝。
• ACP：可由编辑器驱动： 在 Zed 里跑 omp acp，得到的是终端里同一个智能体——读你正在看的缓冲区，通过编辑器自身的保存流程写入，在编辑器的终端里起 shell，有破坏性的工具先暂停弹权限提示。无需桥接、无需插件。
• 四种入口： omp 交互式 TUI、omp -p 一次性执行、omp --mode rpc 的 JSON-RPC stdio 服务、omp acp 的 Agent Client Protocol，外加 Node/Bun SDK。

需要提前知道的边界（避免过度期待）：

• 记忆默认关闭（本机实测 memory.backend = off），需要显式设为 local、mnemopi 或 hindsight 才会跨会话记忆。
• 默认审批模式是 yolo（本机实测 tools.approvalMode = yolo），即读、写、执行都自动放行、不弹确认框。文档明确写着「审批提示不是沙箱」，交互使用推荐改成 write。
• github、security_scan、computer、generate_image、tts、ast_grep、checkpoint、rewind、learn、manage_skill 这些工具默认关闭，要在设置里开。
• 单个二进制体积 205～265 MB（内嵌 Rust 原生模块、bash 引擎、50+ 种 tree-sitter 语法、两套 BPE 分词表等）。
• SDK 走的是 Bun（要求 Bun 1.3.14 或更新），不是 Node.js 运行时；npm 包的 engines 也写着 bun >= 1.4.4。
• 子智能体是 headless 运行的，没有逐工具的交互审批（按 yolo 跑），且每个 worker 是独立模型会话，是成本乘数；advisor 也单独计费。
• 凭据库 agent.db 不做静态加密，Windows 上只依赖账户的文件系统 ACL。
• 官方不提供生产级 collab 中继服务器，也不分发自托管二进制；协作链接是持有即生效的凭据。
• ssh:// 远程读取只支持 POSIX 主机，不支持 Windows SSH 目标。

下载

各平台获取方式对照

方式	命令	适用场景
一键脚本（macOS/Linux）	curl -fsSL https://omp.sh/install | sh	官方推荐，自动选择安装路径
一键脚本（Windows）	irm https://omp.sh/install.ps1 | iex	在 PowerShell 中执行
Scoop（Windows）	scoop install oh-my-pi	main 桶已收录，最短路径
Homebrew	brew install can1357/tap/omp	macOS / Linuxbrew
Bun（官方推荐）	bun install -g @oh-my-pi/pi-coding-agent	已有 bun ≥ 1.4.4
Nix（免安装试跑）	nix run github:can1357/oh-my-pi	想先试试
Nix（装入 profile）	nix profile add github:can1357/oh-my-pi	Nix ≥ 2.30；旧版用 nix profile install
mise	mise use -g github:can1357/oh-my-pi	需要固定版本
GitHub Release	见下表	离线部署、需要校验和

Nix Flake 使用者还可以用 packages.<system>.omp、overlays.default、nixosModules.default 或 homeManagerModules.default；Home Manager 可以声明式安装并管理配置：

nix
{
  inputs.omp.url = "github:can1357/oh-my-pi";

  # 在你的 Home Manager 模块里：
  imports = [ inputs.omp.homeManagerModules.default ];
  programs.omp = {
    enable = true;
    settings.startup.quiet = true;
  };
}

Nix 还有两个构建开关：Wayland 屏幕录制默认关闭（链接 libpipewire 会增加约 750 MB 运行时闭包），用 omp.override { withWaylandScreencast = true; } 开启；发布构建用 fat LTO 链接 pi-natives，omp.override { withFatLto = false; } 改用 thin LTO，本地重建快得多。Rust 依赖和原生插件在不同的 derivation 中构建，所以改 Rust 会复用已编译的依赖，改 TypeScript 会复用已构建的插件。

GitHub Release 二进制清单

发布页：https://github.com/can1357/oh-my-pi/releases/latest。以 v18.16.0（2026-11-02 发布）为例，实测资产如下：

资产名	平台	大小
omp-windows-x64.exe	Windows x64	232.3 MB
omp-windows-arm64.exe	Windows arm64	215.6 MB
omp-darwin-arm64	macOS Apple Silicon	205.7 MB
omp-darwin-x64	macOS Intel	217.0 MB
omp-linux-x64	Linux x64（glibc）	264.2 MB
omp-linux-arm64	Linux arm64（glibc）	225.7 MB
omp-linux-musl-x64	Linux x64（musl / Alpine）	221.5 MB
omp-linux-musl-arm64	Linux arm64（musl / Alpine）	218.4 MB
omp-browser-relay-extension.zip	Chrome 浏览器中继扩展	6 KB
SHA256SUMS.txt	全部资产的 SHA-256 校验和	1 KB

原生插件另有 x64 的 AVX2 与基线两种构建，平台覆盖 linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64、win32-arm64。下载后校验：

sh
sha256sum omp-linux-x64

powershell
Get-FileHash .\omp-windows-x64.exe -Algorithm SHA256

omp-windows-x64.exe 的官方 SHA-256 是 c249a9ed0a57c748fb1247d8ee9e2d0fe1b13229266ce74d8810a76a591e21fc。我用 Scoop 装完后对本机 D:\Scoop\apps\oh-my-pi\current\omp.exe 算了一遍哈希，结果一字不差——Scoop 桶里的就是官方 Release 二进制。Scoop manifest 里的下载地址也直接指向 https://github.com/can1357/oh-my-pi/releases/download/v18.16.0/omp-windows-x64.exe#/omp.exe，hash 字段与 SHA256SUMS.txt 中的一致。

版本核实

写作时核实的信息（2026-11-05）：

来源	结果
GitHub 最新 Release	v18.16.0，发布于 2026-11-02
npm @oh-my-pi/pi-coding-agent	dist-tags.latest = 18.16.0，engines = {"bun": ">=1.4.4"}，bin = {"omp": "dist/cli.js"}
Scoop main 桶	oh-my-pi 18.16.0，bin 为 omp.exe，License 标注 MIT，更新于 2026-11-03
本机 omp --version	omp/18.16.0

安装

Windows

1. 方式一：Scoop（推荐）

Scoop 的 main 桶已经收录，一条命令解决 PATH 和后续更新：

powershell
scoop install oh-my-pi
scoop info oh-my-pi      # 查看版本、许可、来源、是否已装
scoop update oh-my-pi    # 升级

装完 omp.exe 落在 D:\Scoop\apps\oh-my-pi\current\（取决于你的 Scoop 根目录），shim 自动进 PATH，不用手工配环境变量，也不用重开终端。

2. 方式二：官方 PowerShell 一键脚本

在 PowerShell 中执行（不是 cmd）：

powershell
irm https://omp.sh/install.ps1 | iex

需要传参时不能直接管道，要用 scriptblock 形式：

powershell
& ([scriptblock]::Create((irm https://omp.sh/install.ps1))) -Binary
& ([scriptblock]::Create((irm https://omp.sh/install.ps1))) -Binary -Ref v18.16.0
& ([scriptblock]::Create((irm https://omp.sh/install.ps1))) -Source -Ref main

参数含义：-Source 走 bun 安装（必要时自动装 bun）、-Binary 强制下载预编译二进制、-Ref 指定 tag/commit/branch（二进制模式只接受 v<version> 形式的 Release tag，要装分支或 commit 必须配 -Source）。

我读了 install.ps1 的实际逻辑，要点如下：

1. 要求 PowerShell ≥ 5.1，低于此版本直接抛错退出。
2. 默认安装目录 $env:LOCALAPPDATA\omp，最终文件 omp.exe；可用环境变量 PI_INSTALL_DIR 覆盖。
3. 不带参数时的策略是：机器上有 bun 就走 bun 源码安装，没有就下载预编译二进制；带了 -Ref 而没指定模式则强制走 -Source。
4. 预编译二进制来自构建服务 https://build.stencil.so，脚本先取 API 返回的 sha256 再下载校验；先下到 .omp.download.exe，校验通过才 move 到位。
5. 脚本会自动把安装目录追加到用户级 PATH（[Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")），并提示需要重开终端。
6. 源码模式下 -Ref 需要 git；脚本还会检查 git-lfs 以及 PATH 上的 bash.exe（Cygwin / MSYS2 / WSL）。

3. 方式三：手动放二进制

从 Release 下载 omp-windows-x64.exe，重命名为 omp.exe，放进任意目录并把该目录加入 PATH。它是自包含的单文件可执行程序，没有安装器、没有额外运行时依赖。

macOS / Linux

1. 一键脚本

sh
curl -fsSL https://omp.sh/install | sh

固定版本或强制二进制：

sh
curl -fsSL https://omp.sh/install | sh -s -- --binary --ref v18.16.0

install.sh 的实际逻辑：

1. 安装目录 INSTALL_DIR="${PI_INSTALL_DIR:-$HOME/.local/bin}"，即默认 ~/.local/bin/omp。
2. 构建服务 BUILD_URL="${PI_BUILD_URL:-https://build.stencil.so}"。
3. 脚本里写死 MIN_BUN_VERSION="1.4.4"。
4. 给了 --ref 而没指定模式时，默认走 source（bun）安装。
5. 二进制模式强制要求系统里有 sha256sum 或 shasum，否则报 sha256sum or shasum is required to verify the downloaded binary 并退出——校验不通过不会安装。
6. 会检测 Alpine/musl（/etc/alpine-release 存在，或 ldd --version 含 musl）并选择对应的 musl 二进制。
7. 下载用 curl -fsSL --connect-timeout 10 --speed-limit 1024 --speed-time 30，然后 chmod +x 并 mv -f 到 ${INSTALL_DIR}/omp。
8. 装完检查 ~/.local/bin 是否在 PATH 中：在就打印 Run 'omp' to get started!，不在就打印 Add ${INSTALL_DIR} to your PATH, then run 'omp'。

Alpine / musl 注意： 预编译的 musl 二进制动态链接 libstdc++ 和 libgcc，原生 Alpine 不自带，先执行：

sh
apk add libstdc++ libgcc

2. Homebrew

sh
brew install can1357/tap/omp

3. Bun（官方推荐）

sh
bun install -g @oh-my-pi/pi-coding-agent

支持 macOS · Linux · Windows，bun ≥ 1.4.4。

这里有个我本机实测到的坑：我装的 bun 是 1.4.3，低于脚本里的 MIN_BUN_VERSION="1.4.4"，走 bun 路径会被直接拒绝，报错原文是：

text
Bun 1.4.4 or newer is required. Current version: 1.4.3
Upgrade Bun at https://bun.sh/docs/installation

如果你也被拒，先看一眼 bun --version。Windows 上更省事的办法是用 Scoop 或直接下二进制，绕开 bun 门槛。

4. Nix

sh
# 免安装直接跑
nix run github:can1357/oh-my-pi

# 装入当前 profile（Nix < 2.30 用 nix profile install）
nix profile add github:can1357/oh-my-pi

# 构建并冒烟测试可分发的 Nix 包
nix build .#omp

从源码构建

全新克隆的仓库要先装工作区依赖并构建本地 Rust / N-API 插件，源码版 CLI 才能启动：

sh
bun setup                 # 安装 Bun 工作区依赖并构建 @oh-my-pi/pi-natives
bun dev                   # 启动源码版
bun dev -- --version      # 非交互式冒烟检查

改了 Rust crate 或 packages/natives 之后要重新跑 bun run build:native；依赖变化后跑 bun run gen:nix 重新生成 nix/bun.nix（不要手工编辑该文件，它只在 bun.lock 变化时生成）。Nix 用户可以 nix develop 拿到固定版本的 Bun、Rust 工具链和全部原生构建依赖。调试用 /debug 打开调试、上报和性能分析工具。

验证安装

sh
omp --version

本机实测输出：

text
omp/18.16.0

omp --help 会打印 USAGE、FLAGS、EXAMPLES、COMMANDS，外加一份环境变量清单和默认开启的工具清单，值得完整看一遍。

确认配置目录：

sh
omp config path

本机实测输出 C:\Users\lhw\.omp\agent。首次运行后这个目录里会出现 config.yml、agent.db、models.db、history.db、skill-descriptions.db、last-changelog-version，以及 sessions/、cache/、predict/、terminal-sessions/ 等子目录；同级还有 ~/.omp/logs、~/.omp/natives、~/.omp/run。SQLite 库打开时旁边会有 -wal 和 -shm 文件。

跑一遍模型目录确认能读到内置模型库：

sh
omp models ls

本机实测输出（节选，说明离线也能列出目录）：

text
deepseek (4)
┌──────────────────────────────┬─────────┬─────────┬──────────────┬────────┐
│ model                        │ context │ max-out │ thinking     │ images │
├──────────────────────────────┼─────────┼─────────┼──────────────┼────────┤
│ deepseek-flash               │      1M │    384K │ low,high,max │ yes    │
│ deepseek-v4-flash            │      1M │    393K │ low,high,max │ no     │
│ deepseek-v4-flash-vision-exp │      1M │    393K │ low,high,max │ yes    │
│ deepseek-v4-pro              │      1M │    393K │ low,high,max │ no     │
└──────────────────────────────┴─────────┴─────────┴──────────────┴────────┘

Shell 补全

omp 根据实时的命令与参数元数据生成自己的补全脚本，因此永远不会与实际 CLI 脱节。子命令、参数和枚举值是静态补全；模型名（--model、--smol、--slow、--plan）按内置模型目录解析，--resume 按磁盘上的会话解析。

sh
# zsh — 加到 ~/.zshrc（或把输出写进 $fpath 上的文件）
eval "$(omp completions zsh)"

# bash — 加到 ~/.bashrc
eval "$(omp completions bash)"

# fish — 装一次
omp completions fish > ~/.config/fish/completions/omp.fish

重开终端或 source 启动文件，敲 omp 再按 Tab 验证。

安装常见故障对照

现象	原因与处理
omp: command not found / omp 不是内部或外部命令	安装目录不在 PATH。Linux/macOS 默认 ~/.local/bin，Windows 默认 %LOCALAPPDATA%\omp。按安装脚本打印的提示加入 PATH，然后开一个新终端再试——PATH 只影响之后启动的进程。
Bun 1.4.4 or newer is required	bun 版本低于门槛。升级 bun，或改用 -Binary / Scoop / Release 二进制绕开。
sha256sum or shasum is required to verify the downloaded binary	精简容器里没有校验工具。装 coreutils（或 Perl 的 shasum）后重试，脚本不会跳过校验。
Alpine 上启动报缺 libstdc++ / libgcc	musl 二进制动态链接了这两个库。apk add libstdc++ libgcc。
PowerShell 执行策略拦截 irm | iex	用 scriptblock 形式，或先 Set-ExecutionPolicy -Scope Process Bypass。脚本本身要求 PowerShell ≥ 5.1。
Binary installs take a release tag (v<version>) for --ref	二进制模式只认 Release tag。要装分支或 commit 就改用 --source --ref <branch>。
装完版本不是想要的	带 --ref 时脚本默认走 source 模式（需要 git 和 bun）。要精确控制就用 --binary --ref v<version>。
GUI 里启动的编辑器找不到 omp	GUI 进程的 PATH 往往不含 shell 的配置。用绝对路径，或在 ACP 配置里写绝对路径。
更新	omp update（-c 只检查、-f 强制、-l 只更新插件、--canary / --stable 切通道）；Scoop 用户用 scoop update oh-my-pi。

首次配置：登录与选模型

三种给凭据的方式

1. OAuth 登录（文档推荐）

会话里执行 /login 或 /login <provider>，浏览器完成授权后回到终端。终端侧也可以 omp login。同一提供商重复 /login 可叠加多个账号。登出用 /logout [provider] 或 omp auth-broker logout <provider>（后者会移除该提供商的所有行）。手动回调流程里，/login <redirect-url> 用来提交回调地址或设备码——这些回调 URL 和设备码要当密钥对待（它们不会进入输入历史）。

2. API Key 环境变量

启动前在当前终端导出。环境变量只对之后启动的进程生效，所以设置完要在同一个窗口里启动 omp。

PowerShell：

powershell
$env:ANTHROPIC_API_KEY='sk-ant-...'
omp

Git Bash / macOS / Linux：

sh
export ANTHROPIC_API_KEY=sk-ant-...
omp

也可以只给单次运行提供、不落盘：

sh
omp --api-key sk-ant-... --model anthropic/claude-sonnet-4-5 "..."
OPENAI_API_KEY=sk-... omp --model openai/gpt-5.5 "..."

3. .env 文件

按 <当前目录>/.env → ~/.omp/agent/.env → ~/.omp/.env → ~/.env 的顺序加载（profile 模式下第二项是 ~/.omp/profiles/<name>/agent/.env）。.env 不会热重载，且继承来的环境变量优先级高于所有 .env 文件；.env 文件里写 OMP_FOO 会同时复制成 PI_FOO；变量名要匹配 [A-Za-z_][A-Za-z0-9_]*。不要把含密钥的 .env 提交进仓库。

凭据优先级与存储位置

providers 文档给出的 7 级解析顺序：

text
1. --api-key
2. models.yml 里 providers.<id>.apiKey
3. 已存储的 OAuth
4. /login 保存的 key
5. 提供商环境变量 / .env
6. 其他已存储的 key
7. 自定义回退解析器

已存储的 OAuth 会盖过环境变量里的 ANTHROPIC_API_KEY，所以要换凭据得先 /logout——只设环境变量是不生效的。/logout 一次只移除一个凭据；文档特别提示不要用删 agent.db 的方式来登出。在 models.yml 里钉死的 key 又会盖过 OAuth。

凭据存在 ~/.omp/agent/agent.db（SQLite）。这个库不做静态加密：POSIX 上 omp 会把目录建成 0700、库文件改成 0600，Windows 上只能依赖账户的文件系统 ACL。SQLite 打开时旁边还有 agent.db-wal 和 agent.db-shm。要保护的是整个目录以及它的任何备份或同步副本，不只是 agent.db。

团队或多机场景另有两件套：omp auth-broker serve（凭据保险库，默认绑 127.0.0.1:8765）和 omp auth-gateway serve（HTTP 正向代理，默认绑 127.0.0.1:4000，bearer 存在配置根的 auth-gateway.token，权限 0600）。相关命令：omp auth-broker login anthropic、omp auth-broker login anthropic --via=user@broker、omp auth-broker token [--regenerate]、omp auth-broker status、omp auth-broker import <path>、omp auth-broker migrate、omp auth-gateway token [--regenerate]、omp auth-gateway check（--strict 会做真实的提供商检查并消耗少量配额）、--no-auth（允许任意本地调用者）。环境变量：OMP_AUTH_BROKER_URL、OMP_AUTH_BROKER_TOKEN（解析顺序 env → auth.broker.token → <config-root>/auth-broker.token）、OMP_AUTH_BROKER_SNAPSHOT_TTL_MS（默认 3600000，0 关缓存）、OMP_AUTH_BROKER_SNAPSHOT_CACHE（默认 ~/.omp/cache/auth-broker-snapshot.enc）、OMP_AUTH_BROKER_ACCOUNT_POOL_FILE（失败关闭，[] 会隐藏所有账号）。

注意：只给 broker URL 不给 token 会导致启动失败且没有本地回退；broker 的 bearer 就是保险库的管理凭据，重新生成后要重启 broker；健康检查端点不鉴权；refresh token 只留在 broker 上；gateway 的 bearer 能花你的配额；不要把 0.0.0.0:8765 暴露出去。omp token <provider> 打印的 API Key 或 OAuth access token 要当密钥对待（--raw 不解包嵌套凭据 JSON、--force-refresh 刷新 OAuth、-l 列账号、-a <n> 选第 n 个，1 起）。

首次启动向导

omp 第一次启动会打开设置向导：

1. 在 Set up your providers 页保持 Sign in 标签，选提供商，回车，完成浏览器登录后回到终端。可以登录多个提供商。
2. 如果你已经导出了 API Key，它已经可用，直接按 Esc 跳过这一步。
3. 提供商连完后按 Esc。
4. 在 Choose your default model 页输入关键字搜索，从你配置好的提供商里选中一个模型回车，omp 会把它保存为新会话的默认值。
5. 完成剩下的终端外观选项，每一项都会先预览再保存。

之后的启动直接进提示符。OAuth 用户可以用 /login 重新打开登录，/model 改当前会话的模型。随时可以用 omp setup 重跑向导（需要 TTY），omp setup python [--check] [--json] 和 omp setup speech [--check] [--json] 分别装 Python 内核与语音依赖。想跳过向导可以设 OMP_SKIP_SETUP。

模型角色

omp 用「角色」把不同用途路由到不同模型。角色只决定用哪个模型，行为由 agent 决定，这是两个不同的概念，文档专门用一页讲这个区分。

角色	用途
default	常规对话
smol	低成本地批量派发子智能体、机械性修改
slow	深度推理
plan	计划模式
commit	生成提交信息与变更日志
vision	图像描述（当前模型不能收图时的委托目标）
designer	UI/UX 相关的 designer 子智能体
task	通用 task 子智能体
advisor	逐轮审阅的第二个模型
tiny	会话标题、记忆抽取、词补全等本地小模型场景

README 概述里写的是「九种角色」，而 roles 文档页列出上面 10 个（多了 designer）。以文档页为准。未分配的 smol、slow、designer 可能落到 default，tiny 跟随 smol，advisor 会去找一个独立的强模型。

modelRoles 可以完全为空，omp 会从已认证的模型里自动解析。手工配置写在 ~/.omp/agent/config.yml：

yaml
modelRoles:
  default: anthropic/claude-sonnet-4-5
  slow: openai-codex/gpt-5.3-codex:high
  smol: anthropic/claude-haiku-4-5

值的写法：选择器或模糊模式、逗号分隔的有序选择器、别名 @role（* 等于 @default，pi/role 是遗留写法）、思考强度后缀 off|minimal|low|medium|high|xhigh|max|auto。设 modelRoleStorage: project 后角色改动会保存到项目的 .omp/config.yml 而不是全局（默认 global）。

切换方式：

控制	结果
/model 或 Alt+M	打开模型中心，查看或修改持久的角色分配。TUI 里这个命令不接受模型 ID 参数
/switch 或 Alt+P	只给当前会话挑一个临时模型，不改保存的角色设置
Ctrl+P / Ctrl+Shift+P	在已配置的角色模型顺序中前后循环（默认 smol → default → slow，由 cycleOrder 控制）
Shift+Tab	循环当前模型支持的思考强度（含配置了的 Auto）
Ctrl+T	显示或隐藏思考块——只改可见性，不改推理强度

启动时用 --model、--smol、--slow、--plan 覆盖，对应环境变量 PI_SMOL_MODEL、PI_SLOW_MODEL、PI_PLAN_MODEL，flag 优先于环境变量。思考强度更高通常能改善困难推理，但延迟和 token 用量也会上升；不支持可配置思考的模型会明说而不是偷偷改。选 Auto 时，状态栏会在本轮被分类后显示解析出的强度。

模型查找与目录维护：

sh
omp models                     # 或 omp models ls
omp models find sonnet
omp models anthropic           # 列出某个提供商
omp models refresh             # 刷新目录
omp models refresh lab         # 只刷新某个提供商
omp models --json
omp --list-models

自定义 OpenAI 兼容提供商

在 ~/.omp/agent/models.yml（或 models.yaml）中声明，根键只能是 providers：

yaml
providers:
  spark:
    baseUrl: http://192.168.10.223:8000/v1
    api: openai-completions
    apiKey: dummy
    models:
      - id: minimax-m3
        name: MiniMax M3
        contextWindow: 100000
        maxTokens: 32000

验证并使用：

sh
omp models spark          # 确认能发现该提供商的模型
omp setup                 # 在选默认模型那一步选中它
omp -p --model local-openai/Qwen/Qwen2.5-Coder-32B-Instruct "Reply with only OK"

或者跳过选择器，直接在 ~/.omp/agent/config.yml 里预写默认模型：

yaml
modelRoles:
  default: spark/minimax-m3

也可以在会话中打开 /model 把它分配给 default 角色。

api 字段支持的协议：openai-completions、openai-responses、openai-codex-responses、azure-openai-responses、anthropic-messages、bedrock-converse-stream、google-generative-ai、google-gemini-cli、google-vertex，另有 typesafe、openrouter-decisions、openai-decisions、workers-ai-systemone 等评判类 API。

apiKey 的解析顺序是 !command（取命令 stdout）→ 环境变量名 → 字面量文本；auth 默认 apiKey，可设 none，oauth 只在预先支持时可用；authHeader: true 会注入 Authorization: Bearer <resolved-apiKey>。环境变量名写错时会静默回退成把这个名字当字面 key，结果就是 401/403。

未声明字段的模型默认值：名字即 id、纯文本、无推理能力、上下文 128000、输出 16384、成本 0。discovery.type 支持 ollama、llama.cpp、lm-studio、openai-models-list、litellm、proxy（只有 proxy 会跳过提供商级的 api），discovery.timeoutMs 是正整数毫秒。旧的 models.json 会迁移到 models.yml。

模型级可写的字段很多，常用的有 id、name、api、baseUrl、reasoning、thinking、input（[text] 或 [text, image]）、tokenizer（claude-v3、claude-v47、claude-v5、claude-v5-sonnet、qwen3、deepseek-v3、kimi-k2、glm5）、supportsTools、cost（input/output/cacheRead/cacheWrite，四个都必填）、contextWindow、maxTokens、omitMaxOutputTokens、headers、compat、compactionModel、remoteCompaction。thinking.mode 可取 effort、budget、google-level、anthropic-adaptive、anthropic-budget-effort。modelOverrides 用来改内置模型的字段，但不能改 id、api、baseUrl，且 cost 可以只写部分。compat 下有几十个开关用于适配各家怪癖，例如 maxTokensField（max_completion_tokens 或 max_tokens）、reasoningContentField（reasoning_content / reasoning / reasoning_text）、thinkingFormat（openai / openrouter / zai / qwen / qwen-chat-template）、promptCacheMode（none / automatic / explicit）、supportsStrictMode、streamIdleTimeoutMs、extraBody。

本地引擎的默认地址：ollama → http://127.0.0.1:11434、llama.cpp → http://127.0.0.1:8080、lm-studio → http://127.0.0.1:1234/v1，分别可用 OLLAMA_BASE_URL（或 OLLAMA_HOST）、LLAMA_CPP_BASE_URL、LM_STUDIO_BASE_URL 覆盖，本地实例无需密钥。Ollama 的上下文长度用 OLLAMA_CONTEXT_LENGTH。

一个坑：models.yml 里只要有一条无效，所有走该文件的自定义提供商都会被禁用，报错是 models.yml validation failed，且校验错误会在 omp models 之前打印。modelRoles、modelProviderOrder 属于 config.yml，不要写进 models.yml；也不要把普通服务器标成 ollama。

内置提供商与认证方式

文档站把提供商分成四类，认证标签含义：oauth = 用你在该提供商的账号登录，plan = 通过编程套餐订阅使用，local = 连接本地服务器（密钥可选）。

• 前沿 API（直连 API 与网关，可按角色混用不同提供商）：Anthropic oauth、OpenAI、OpenAI Codex oauth、Google Gemini、Google Vertex、Google Antigravity oauth、xAI、SuperGrok oauth、DeepSeek、Mistral、Groq、Cerebras、SambaNova、Fireworks、Together、Baseten、DeepInfra、Hugging Face、NVIDIA、Meta、Inception、Amazon Bedrock、Azure OpenAI、SiliconFlow、GMI Cloud、CoreWeave、Sakana AI、Command Code、Charm Hyper、StepFun、Helmcode、OpenRouter、Synthetic、Vercel AI Gateway、Cloudflare AI Gateway、Wafer Serverless。
• 编程套餐（走订阅额度，/login 登录后即可在会话中使用）：Cursor oauth、GitHub Copilot oauth、GitLab Duo、Devin oauth、Kimi Code plan、Moonshot、MiniMax Coding Plan plan、MiniMax Coding Plan CN plan、Alibaba Coding Plan plan、Qwen Portal oauth、Z.AI / GLM Coding Plan plan、Zhipu Coding Plan plan、Xiaomi MiMo、Qianfan、Umans plan、NanoGPT、Novita、Venice、Kilo、ZenMux、OpenCode Go、OpenCode Zen。
• 本地部署（兼容 OpenAI 的 /v1/models）：Ollama local、Ollama Cloud、LM Studio local、llama.cpp local、vLLM local、LiteLLM。

几个容易搞混的提供商 ID（文档专门点出）：openai-codex 走 ChatGPT 订阅，openai 走 API（OPENAI_API_KEY），无头环境的 Codex 用 openai-codex-device；google 用 GEMINI_API_KEY，两个 ID 不可互换；xai 与 xai-oauth（SuperGrok / X Premium+）不同；Copilot 走 GitHub 设备流，Enterprise 主机随凭据保留；zai-coding-plan 的凭据存在 zai 名下；Azure 只有 key 是不够的；Bedrock 走 AWS 凭据链和区域；在 models.yml 里显式写出提供商 ID 会关闭自动发现。查看与排障：omp config get disabledProviders，禁用某个提供商用 omp config set disabledProviders '["ollama"]'。

路由的四个开关

• 回退链：retry.fallbackChains 下按角色或按模型配置。主模型返回 429 或触及配额上限时，链中下一项接管本轮剩余部分，冷却后自动恢复。相关键：retry.modelFallback（默认 true）、retry.fallbackRevertPolicy（默认 cooldown-expiry，可选 never）。链的键可以是角色名、provider/model-id、provider/*、provider/id-prefix/*，条目必须是提供商限定的。
• 按路径限定模型：给 enabledModels 和 disabledProviders 条目加 path: 前缀，就能在某个仓库固定一组模型而不动全局配置，限定条目覆盖该路径及其下所有内容。
• 轮换凭据：同一提供商叠加多个 API Key，运行时按会话亲和性轮换，每个凭据单独退避。适合单个密钥中午前就烧光配额的情况。用 omp dry-balance 可以在不跑会话的情况下测试账号选择（--count <n>、--concurrency <n>、--json、--bench 会给每个 OAuth 账号发一次真实基准请求）。
• 用量感知回退：retry.usageAwareFallback（默认 false）、retry.usageReservePct（默认 10）、retry.usageReservePolicy（默认 confirm，可选 auto / fail-closed）。

配置文件与优先级

无需任何配置文件即可使用。要定制时按下述层级合并，从左到右优先级递增：

text
内置默认 → 全局 ~/.omp/agent/config.yml → 项目 <cwd>/.omp/config.yml
        → PI_CONFIG_FILES 里的文件 → 重复的 --config 文件（后者胜）
        → 运行时 flag / 环境变量

规则：映射深合并，数组整体替换（项目的数组会整体替换全局的）；项目配置只认启动目录下的 .omp/config.yml，不向上查找父目录；config.yaml 后缀同样接受；命名 profile 走 ~/.omp/profiles/<name>/agent/config.yml（omp --profile <name> 或环境变量 OMP_PROFILE，旧的 PI_PROFILE 仍可用）；PI_CODING_AGENT_DIR、PI_CONFIG_DIR（默认 .omp）可改目录；omp config init-xdg 可初始化 XDG 布局。

命令行读写配置：

sh
omp config list                    # 列出全部设置与当前值（凭据字段打码）
omp config list --json
omp config get theme.dark
omp config set theme.dark catppuccin-macchiato
omp config set compaction.enabled false
omp config set providers.maxInFlightRequests '{"anthropic":2}'
omp config reset theme.dark        # 恢复 schema 默认值（是写入默认值，不是删掉该键）
omp config path                    # 打印当前生效的 agent/config 目录
omp config init-xdg                # 初始化 XDG Base Directory 布局
omp --config ./ci.yml -p "..."     # 单次运行的 YAML 覆盖层，可重复
omp --profile work config list     # 针对某个 profile

注意：config set / config reset 永远写全局文件，不会写项目文件；config list 会对凭据打码，但 config get 明确取凭据键时会返回真实值，注意输出别外泄。没有 /reload-settings，直接改文件要下次启动才生效。持久化 YAML 非法时会被改名为 *.broken-<timestamp>-<pid>-<id> 并导致启动失败；--config 覆盖层是严格模式，文件缺失或格式错误会直接阻止启动。布尔值接受 true/false、yes/no、on/off、1/0，数组和记录用 JSON。覆盖层路径按工作目录解析，~ 会展开。

本机实测的几项默认值（v18.16.0，逐项 omp config get 读出）：

键	实测值
memory.backend	off
tools.approvalMode	yolo
compaction.enabled	true
plan.enabled	true
github.enabled	false

文档给出的其他默认值：暗色主题 titanium、亮色主题 light、启动回退 dark、defaultThinkingLevel 为 high、steeringMode 与 followUpMode 为 one-at-a-time、interruptMode 为 immediate、modelRoleStorage 为 global、tools.xdev 开启、dev.autoqa 开启、图片缩放开启。

设置的命名空间很多，按 /settings 的分页组织：

分页	主要命名空间
Appearance	theme、symbolPreset、colorBlindMode、composer、statusLine、terminal、images、tui、display、showHardwareCursor
Model	modelRoles、modelTags、modelProviderOrder、cycleOrder、modelRoleStorage、enabledModels、defaultThinkingLevel、hideThinkingBlock、personality、temperature、topP、topK、minP、presencePenalty、repetitionPenalty、textVerbosity、tier、retry、advisor、prewalk
Interaction	autoResume、power、git、steeringMode、followUpMode、interruptMode、loop、doubleEscapeAction、treeFilterMode、autocompleteMaxVisible、spelling、paste、startup、update、marketplace、magicKeywords、completion、error、ask、recap、collab、share、stt
Context	workspace、contextPromotion、extendedContext、compaction、snapcompact、branchSummary、ttsr
Memory	memory、autolearn、memories、mnemopi、hindsight
Files	edit、read、readLineNumbers、lsp
Shell	shellPath、bash、bashInterceptor、shellMinimizer、eval、python、ruby、julia
Tools	tools、todo、glob、grep、astGrep、astEdit、debug、launch、speechgen、generate_image、inspect_image、computer、checkpoint、fetch、vault、github、web_search、security、browser、async、irc、mcp、tasks、extensionHandlers、dev
Tasks	plan、goal、title、task、worktree、skills、commands
Providers	providers、provider、disabledProviders、secrets、live、tts、speech、codexResets、exa、searxng、auth

extensions、disabledExtensions、commit、gc、thinkingBudgets 只能在 YAML 里改。

使用

最基本的用法

进项目目录，启动：

sh
cd my-project
omp

你启动 omp 的目录就是本次会话的项目根。 然后用普通语言描述一个有边界的目标即可，不需要斜杠命令或特殊提示词格式。官方 quickstart 推荐的第一次试水提示词：

text
Inspect this project for one small bug or inconsistency that can be verified locally. Explain what you found, make the smallest safe fix, and run the most relevant check.

using 文档给的更典型的例子：

text
Find the refresh-token race, fix only the implementation and its focused tests, show me the diff, and run those tests. Do not commit.

接着可以在同一会话里要求一次聚焦的复审，再继续追加：

text
Show me the diff and explain each changed file. Do not make more changes.

text
Looks good. Run the relevant check once more and summarize any remaining risk.

一个可靠的交互任务通常是这五步：

1. 说清结果和边界：指名 bug 或功能、关键路径、不能动的东西、应该通过的检查。
2. 让它调查：它会叙述进度，并把每次读取、命令或修改作为卡片显示在记录里。
3. 需要时介入：工作中途发引导消息、回答问题、拒绝不安全的动作。
4. 审阅证据：展开工具卡片和 diff，检查改动路径、命令退出状态、测试结果和最终解释。
5. 在同一会话里细化：直接说哪里不对或还缺什么，比如「保留公开签名」「补上缺失的边界用例」「把 cache.ts 的改动回滚」。

文件修改是边做边写进工作区的，除非你要求提交，否则不会 commit。你的编辑器、git diff 和会话记录仍然是最终的审阅面。

界面三块区域

• 记录区：你的消息、助手文本与思考、通知、提问、工具卡片。新活动出现在底部。工具卡片显示待处理 / 成功 / 失败 / 取消，编辑卡片带受影响路径和 diff 摘要。
• 编辑器区：带边框的输入框，你在这里写下一条提示。自动补全、附件 chip、排队消息提示和临时对话框都围绕它出现。选择器或问题底部的提示行显示当前焦点面适用的按键。
• 状态栏：默认显示当前模型与思考等级、工作模式、路径、Git 状态、上下文占用、花费、会话名。窄终端会省略或缩短某些段。Plan、Goal、Vibe、Loop、Fast、协作等状态会在这里出现。

文档特别强调：状态栏不是装饰。在认定 omp 跑错目录、用错模型、没有写权限或上下文用完之前，先看状态栏。 它的预设和分段可以在 /settings 里改（statusLine.preset、statusLine.transparent）。

输入技巧

你想做的事	操作
发送提示	Enter
换行	Shift+Enter、Ctrl+J 或 Alt+Enter。Windows Terminal 用户建议用 Alt+Enter
引用项目文件	输入 @，继续打字模糊搜索，选中路径。@path 会自动读进本轮
补全路径	输入相对 / 父级 / home / 绝对路径的一部分，用补全列表，Tab 接受高亮项
附加图片	Ctrl+V 粘贴，或拖入、粘贴图片路径。编辑器里出现 chip 表示附件已确认。也可以 @path/to/image.png
附加大段粘贴文本	直接粘贴。多行或大段粘贴会折叠成带编号的 paste chip 以保持编辑器可读，删除 chip 即删除该附件
用外部编辑器写长草稿	Ctrl+G 打开 $VISUAL（回退 $EDITOR），保存并关闭后文本回到 omp
找回之前的提示	Ctrl+R 搜索提示历史

散文、@file、粘贴文本和图片可以组合进同一条提示。要说清每个附件是干什么用的——光有路径提供的是上下文，不是意图。 例如：

text
Compare @src/auth/refresh.ts with @test/auth/refresh.test.ts. The attached screenshot is the production error. Fix the race without changing the token format, then run the focused test.

@file 的几条规则：文本作为上下文包含，受支持的图片作为图像输入发送；@file 缺失或不可读会让命令直接失败，不会静默忽略；rpc / rpc-ui 模式下 @file 不展开，要通过协议发送输入。图片默认归一化并缩放，超过 20 MiB 的图片被拒绝；当前模型不能直接收图时，omp 通常会委托一个配好的视觉模型生成描述。图像行为在 /settings 的 Model → Vision 和 Appearance → Images 下配置。

命令行也可以直接带附件：

sh
omp @requirements.md "Implement the first unchecked item"
omp @before.png @after.png "Match the second design"
omp @plan.md @screenshot.png "Implement this"
printf '%s\n' 'Explain packages/core' | omp -p

stdin 不是 TTY 时 omp 会自动读取，不需要 - 标记。

自己直接跑本地命令

在编辑器里以转义前缀开头，命令直接执行，不经过模型选择或调用：

text
! git status
!! git diff --stat
$ print(2 + 2)
$$ import os; print(os.getcwd())

前缀	行为
! command	在你的用户 shell 里跑，结果流式显示在 TUI 中，并计入对话上下文
!! command	跑并显示，但输出不进入模型上下文
$ code	在会话共享的 Python 内核里跑，结果计入上下文。$ 后必须有空格，所以 $HOME 这类文字仍是普通散文
$$ code	跑 Python 并显示，但不加入模型上下文

Esc 取消正在运行的 shell 或 Python 转义。成功的 ! cd path 会同时移动 omp 的交互工作目录。这些命令用你本地的用户权限运行，可以立刻改文件；!! 和 $$ 只是把输出排除在模型上下文外，不是安全沙箱。 对应的事件钩子是 user_bash（!/!!）和 user_python（$/$$）。

审阅工具卡片

工具卡片是你的提示与最终答案之间的审计线索。先看标题（它标明动作、命令、路径或远程资源），再看状态和结果。

• Ctrl+O 展开或折叠工具输出——被截断的命令记录或完整可见 diff 都用它。
• Ctrl+Shift+O 隐藏或显示工具活动，想要纯散文视图时用。
• 卡片成功只代表那个动作完成了，不代表整个任务是对的。要单独检查最终的测试或验证卡片。
• 失败或取消的卡片仍是有用证据。读完错误再告诉 omp 是重试、换方法还是停下。
• 编辑类卡片要看路径和增删行数，范围或行为不对就立刻要求纠正。

回答审批与提问

如果审批模式或某个工具的策略要求确认，omp 会在动作前暂停并显示它想做什么。要读命令、目标、diff 预览和理由，不要只看标题就批准。 用屏幕上显示的选择器按键选允许或拒绝，Esc 取消提示——关闭不等于批准，不会推断出任何许可。

需要产品输入时会弹问题对话框（由 ask 工具触发，智能体可以在回合中途调用）：↑/↓ 移动、Enter 选单选答案；多选题用 Space 切换再 Enter 前进；Other 行可以输入自定义答案；某行提供解释性说明时按 n；多个问题用 Tab、Shift+Tab 或 ←/→ 换页，在最后一页审阅并提交；Esc 取消而不是猜，然后在编辑器里说明缺失的约束。同样的提示卡片也会通过 ACP 呈现，编辑器无需自己实现选择器。

默认 Yolo 审批模式允许常规的读、写、执行，所以你可能看不到审批提示。想要写入和命令前确认，就在 /settings 的 Interaction → Approvals 里选 Always ask，或启动时带 omp --approval-mode always-ask。

引导、排队、中断、继续

omp 工作时你可以继续打字，提交键决定这条消息影响当前轮还是等下一轮：

动作	默认按键	什么时候用
引导当前轮	Enter	当前思路需要纠正：「不要改 schema」「用已有的 helper」「调查完就停」
排队后续消息	Ctrl+Q 或 Ctrl+Enter	当前任务应该先做完：「之后解释一下迁移风险」
把排队消息取回编辑器	Alt+Up 或 Shift+Up	排错了或想改待发消息
中断当前操作	Escape	停掉一轮、本地 shell/Python 转义、重试或其他活跃操作
继续之前的意图	发送 . 或 c	你在合适的位置打断了，想让它接着做而不重述任务
重试上一个失败的助手轮	Alt+R	提供商或轮次失败，同样的请求再试一次

引导消息是给现在的，后续消息是给智能体让出之后的。待发消息条会显示排了什么。steeringMode、followUpMode、interruptMode 三个设置控制排队消息是一起排空还是逐条处理、引导是立即打断还是等待。也可以用 /queue <message> 显式排队，编辑器里 -> message 和 => message 是等价简写。

Escape 是焦点敏感的：自动补全或选择器打开时，第一次按是关掉那个面；在主编辑器里才是中断当前工作。它不会退出 omp。 Loop 模式下它停止当前迭代但 Loop 仍开着，要再执行一次 /loop 才关闭。/pause 可以在下一个安全边界冻结主智能体、子智能体和 advisor（在飞的调用会完成，Esc、Enter 或空格恢复）。

一次性执行、管道与 CI

入口	行为
omp	交互式文本模式，打开 TUI 并保持会话运行
omp -p / omp --print	无头文本模式：处理请求、写出答案、退出
omp -p --mode json	输出换行分隔的结构化事件流，用于自动化
omp --mode rpc	通过 stdio 运行 JSON-RPC 服务
omp --mode rpc-ui	RPC 并启用 UI 扩展事件
omp --mode acp / omp acp	通过 stdio 运行 Agent Client Protocol 服务

--mode text 是默认值；--print 控制文本 / JSON 运行是否在请求后退出，协议模式始终是服务。--mode 只接受 text、json、rpc、rpc-ui、acp 五个值，任何显式 --mode 都是无头的。

命令行的三种形态：

sh
omp [launch flags] [@files...] [messages...]
omp launch [launch flags] [@files...] [messages...]
omp <command> [arguments] [command flags]

launch 是默认命令。第一个非 flag 词如果不是已注册命令，omp 就把剩下的词当作初始请求——所以 omp "fix the build" 是启动会话，而 omp models 是列模型。请求以命令名开头时要显式写 omp launch …。 所有带值的长选项都接受 --flag value 和 --flag=value 两种写法；用 -- 停止解析 flag：

sh
omp -- "Explain why --force is dangerous here"

已加载的扩展可以新增启动 flag，omp --help 会把它们和内置的一起显示出来。

常用组合（官方示例）：

sh
# 在另一个目录启动，并额外挂一个工作区根
omp --cwd apps/web --add-dir packages/ui "Fix the broken component test"

# 恢复会话并把结果保留为独立分支
omp --fork 01JZ8Y2A "Try the smaller design"

# CI 里的有界一次性运行
omp -p --mode json --no-session --max-time 10m \
  "Check whether generated files are current" > omp-events.jsonl

# 限制会话能力，写入需审批
omp --tools read,grep,glob --approval-mode write \
  "Audit the migration without changing files"

# 查模型，再基准测试两个候选
omp models find sonnet
omp bench sonnet gpt-5.6 --runs 3

# 管理项目级市场插件
omp plugin marketplace add https://example.com/marketplace.json
omp plugin install widget@example --scope project
omp plugin list

# 只做检查、不做破坏性操作
omp config get defaultThinkingLevel
omp gc --json
omp worktree clear --dry-run

无头模式的其他常见形态：

sh
omp -p --print-thoughts "Explain this stack trace"
git diff | omp -p "Review this diff"
printf '%s\n' "Summarize the last commit" | omp
omp --mode json "Find every TODO under src" > run.jsonl
omp -p "/review focus on authentication regressions"
omp -p --advisor "…"
omp --goal "Investigate the importer"

还有两个花钱的保险丝（本机 omp --help 实测存在）：--warn-cost=<USD> 在会话花费（含子智能体）达到该美元数时警告一次；--max-cost=<USD> 达到后停止发送新的模型请求，已在飞的请求可能超出，print 模式退出码为 3。--wait-async 让 print 模式在退出前等待本次运行的后台任务，并用每个结果唤醒会话（对应 async.printWake；除非设了 --max-time，否则没有时间限制）。

会话管理与恢复

会话自动保存，没有 Save 命令。存储根目录 ~/.omp/agent/sessions/，命名 profile 是 ~/.omp/profiles/<name>/agent/sessions/；XDG 变量可能改变位置，所以 /session info 才是权威。

命令行：

sh
omp -c                  # 继续当前项目最近的会话（--continue）
omp -r                  # 打开会话选择器（--resume / --session）
omp -r <id-or-path>     # 按 ID 前缀或 JSONL 路径恢复
omp -r ./received-session.jsonl
omp --fork <id>         # 从已存会话分叉出新会话
omp --restore <path>    # 恢复后接着做上一个进程没做完的事（含被中断的轮次与它在跑的子智能体）
omp --from-claude       # 导入 Claude Code 会话
omp --from-codex        # 导入 Codex 会话
omp --export <session> [output.html]   # 把 JSONL 渲染成 HTML 后退出
omp --no-session        # 本次运行不落盘（临时）
omp --session-dir <dir> # 覆盖会话存储与查找目录
omp --profile work      # 用独立的 auth / sessions / settings / caches
omp --profile work --alias omp-work    # 为该 profile 建 shell 快捷命令后退出
omp share <session> [--gist]           # 通过分享服务或私密 gist 分享
omp config set autoResume true
omp session pack | unpack | moved | lease   # 把会话交给另一台机器，或查看运行中的 omp 拥有哪些会话

-c 在没有精确匹配时会回退到该目录最近修改过的会话。这也是 SSH 或终端断连后的恢复路径：持久化的记录会被重放，包括仍在写入的尾巴。

会话内斜杠命令：

命令	用途
/new	新开会话，保留当前的在磁盘上
/clear	原地清空对话上下文，保留会话（会写一条 reset_boundary 记录）
/drop	删除当前会话并新开一个
/resume [session-id|@claude|@codex]	打开本地选择器 / Claude·Codex 导入选择器 / 恢复匹配的会话 ID（仅交互 TUI）
/rename <title>	给当前会话设用户自定义标题
/pin [session-id]	把当前或指定会话在恢复列表里置顶
/session info	显示当前会话 id、路径、谱系和统计
/session delete	删除当前持久会话并回到选择器（流式中或内存会话不可用）
/session pin [account]	把当前提供商钉到某个已存 OAuth 账号（与顶层 /pin 不同）
/fresh	关闭提供商侧流状态并以全新提供商状态开始，不改本地记录（过期提示缓存、卡住的流用它；流式中不可用）
/move <path>	移到另一个已存在目录，重载目录级设置与发现的能力，并把该路径设为工作目录；流式中不可用
/add-dir / /remove-dir / /dirs	增删查额外工作区根。工作目录本身不能被 remove，要用 /move

会话树的三个命令，区别要说清：

命令	用途
/tree	在当前会话内跳到更早的消息或另一个分支。某轮跑歪了用它
/branch	从同一会话文件的较早消息开一条备选线
/fork	把对话克隆成一个新的会话文件，再去试另一条路

选择器按键：↑/↓ 移动、Enter 确认、Tab 在「当前目录」和「全部项目」之间切换、Delete 或 Backspace（搜索框为空时）删除。会话树里另有 Alt+↑/Alt+↓、Page Up/Page Down 或 ←/→、Home/End、直接打字搜索（Backspace 删字符）、Enter 切换、Shift+Enter（先总结再切换）、Shift+L 打标签、Ctrl+O/Ctrl+Shift+O 循环过滤、Alt+D/T/U/L/A（默认 / 无工具 / 仅用户 / 仅带标签 / 全部）、Alt+A 显示全部、Esc 或 Ctrl+C 关闭。Esc 会先清掉活跃搜索再关选择器。/settings → Interaction → Input → Double-Escape Action 可设为 Tree（默认）或 Branch；相关开关 branchSummary.enabled；树里已到位时会显示 Already at this point。压缩不会把树压平。

两处文档对 /branch 的描述不一致：session-tree 页说 /branch 跟随 Double-Escape Action 设置（默认打开与 /tree 相同的导航器），而 sessions 页说 /branch 直接打开一个用户消息选择器。用的时候以实际界面为准。

退出：/exit、/quit、/q 或 Ctrl+D。Ctrl+D 会保存未发送的非空草稿，恢复该会话时还原一次。Ctrl+C 清空编辑器，半秒内再按一次退出——所以想「离开并保留草稿」要用 Ctrl+D。

文档明确的提醒：HTML 导出是给阅读用的，不能拿来恢复会话，且内容敏感；分享链接持有者就能读该快照（密钥在 URL fragment 里，不会发给存储服务），大会话可能被裁剪；JSONL 可能含密钥；--no-session 的运行无法恢复、删除或分叉（分叉需要持久化）；硬崩溃可能丢掉正在流式写入的尾巴；删除是破坏性的，先把 JSONL 导出；移动 / 删除 / 分叉前要等流式结束；导航式的移动之后如果 omp 被杀，恢复时可能回到最后一个已记录的端点。

会话文件是 JSONL、逻辑版本 3，文件名形如 <filesystem-safe-timestamp>_<session-id>.jsonl；大图片外置到 ~/.omp/agent/blobs/<sha256> 并以 blob:sha256:<64位十六进制> 引用，所以只有 JSONL 而没有 blob 库是不完整的。物理第 1 行是固定 256 UTF-8 字节（含换行）的可变 title 记录，原地更新，形如 {"type":"title","v":1,"title":…,"source":"auto"|"user","updatedAt":…,"pad":…}。头部记录 type:"session" 带 version、id（UUIDv7，应视为不透明）、timestamp、cwd、additionalDirectories、title、titleSource、parentSession、previousSessionFiles、providerPromptCacheKey。条目类型包括 message、thinking_level_change、model_change、service_tier_change、mode_change、compaction、branch_summary、reset_boundary、label、title_change、ttsr_injection、credential_pin、session_init、custom（不进模型上下文）、custom_message（进上下文）。消息角色有 user、developer、assistant、toolResult；stopReason 有 stop|length|toolUse|error|aborted；块类型有 text、image、thinking、redactedThinking、toolCall、fallback、anthropicServerTool。超过 500000 字符的字符串会被截断，jsonlEvents 会被剥掉。没有持久化的 active-leaf，文件顺序提供初始叶子，不要从时间戳推断分支。不要原地编辑活跃会话文件（omp 在迁移或可写操作时可能重写文件）。配对工具结果要用 message.toolCallId === block.id，分支情况下相邻性不可靠。内容不做脱敏（可能含密钥、session_init 提示、credential_pin.hash）。

命令行检查会话文件：

sh
find ~/.omp/agent/sessions -name '*.jsonl' -print
jq -c . ~/.omp/agent/sessions/<project>/<session>.jsonl
jq -r '.type' session.jsonl
jq -c 'select(.id and has("parentId")) | {type,id,parentId,timestamp}' session.jsonl
grep -o 'blob:sha256:[a-f0-9]\{64\}' session.jsonl | sort -u
omp render -w 120 --timing      # 用生产级渲染器重画整份记录
omp anonymize                   # 产出可分享的脱敏副本（内容打码、元数据保留、路径与字面量替换为一致的 mock token）

上下文压缩与交接

上下文快满时先跑 /context 看各来源的 token 预算，再决定动作：

命令	作用
/compact [focus]	按配置的方法手动压缩，可带关注点说明
/compact soft [focus]	强制用当前模型做一次本地摘要
/compact remote [focus]	先试 OpenAI 兼容的服务端压缩，失败再本地摘要
/compact snapcompact	把历史归档成密集位图图像，不做 LLM 摘要；不接受 focus 文本
/shake [elide|images|thinking]	不做摘要直接移除重型上下文。裸形式 / elide 剥掉工具结果和大块内容，另两个模式剥图像块或思考块
/handoff [focus]	生成交接文档并作为压缩条目提交进同一会话

自动压缩默认开启。关键默认值：compaction.methodOrder = [remote, snapcompact, handoff, shake, soft]、keepRecentTokens = 20000、thresholdTokens = -1、thresholdPercent = -1（设置时会被夹到 1–99%）、reserveTokens 未设时取「16384 token 与窗口 15% 中的较大者」、midTurnEnabled = true、asyncEnabled = true、autoContinue = true、idleEnabled = false（idleThresholdTokens = 200000、idleTimeoutSeconds = 300）、handoffSaveToDisk = false、supersedeReads = true、dropUseless = true、v2RetainedMessageBudget = 64000、display.collapseCompacted = true。

自动压缩时屏幕上会出现 Auto server compaction…、Auto-snapcompact…、Auto-handoff…、Auto-shake…、Auto-shake completed 等提示，分隔线形如 256K→20K、soft-compacted、remote-compacted、handed-off，Ctrl+O 展开摘要，Esc 取消（Compacting context… (esc to cancel)）。其他会看到的字符串：Nothing to compact (session too small)、Already compacted、Nothing to shake、No images found、No thinking blocks found，以及 artifact://… 形式的恢复引用。

/handoff 的名字容易误解：它不创建、不分叉、也不切换到另一个会话，只在当前会话内原地压缩（文档用引用块专门强调了这点）。它需要会话空闲且消息量足够，不会自动结束当前轮。compaction.handoffSaveToDisk（默认 false）只对自动交接生效，会把带时间戳的 handoff-*.md 写到工件目录。交接分隔线形如 ──────── handed-off · 180K→24K · ctrl+o ────────；进行中提示 Generating handoff… (esc to cancel)，成功提示 Context handed off and compacted in place；失败信息如 Handoff failed: No model selected for handoff、Handoff failed: No API key for …；忙碌时提示 Wait for the current response to finish or abort it before handing off.；空的交接简报算失败，不算取消；输入已经溢出时 omp 通常不会启动新的交接。

其他提醒：手动 /compact 会中止正在运行的响应；/shake images 和 /shake thinking 不生成恢复工件，只在那些材料确实不再需要时用；snapcompact 需要一个有视觉能力的模型，且文本要能被它自带的图像字体表示；常规压缩不会删除会话记录。想调整顺序可以直接改，例如 compaction.methodOrder: [handoff, remote, snapcompact, shake, soft]。

记忆

跨会话的持久知识（仓库约定、决策、评审偏好），默认关闭，且与压缩是两回事。智能体在运行中用 retain 写下事实、用 learn 记录可复用经验、用 recall 取回，并把每个会话压缩成一个心智模型，在下个会话的第一轮加载。

sh
omp config set memory.backend local      # 或 mnemopi / hindsight
omp config get memory.backend
omp config set memory.backend off        # 关闭
omp config get hindsight.apiUrl
export HINDSIGHT_API_TOKEN='replace-me'

四个取值：off、local（批量摘要）、mnemopi（本地 SQLite 引擎）、hindsight（远程服务，默认 http://localhost:8888，云端 https://api.hindsight.vectorize.io）。HINDSIGHT_* 环境变量覆盖 hindsight.* 配置。默认按项目作用域隔离，这个仓库学到的东西只留在这个仓库。

相关工具：retain（写入持久事实）、recall（搜索原始记忆）、reflect（基于记忆库综合答案）、memory_edit（按 id 更新/遗忘/作废，仅 mnemopi）、learn（记录可复用经验，可提升为托管技能）、manage_skill（增删改查自动学到的技能）。

会话内命令：/memory（等于 /memory view，显示当前注入的记忆载荷）、/memory stats、/memory diagnose、/memory clear（别名 /memory reset，清空持久记忆数据与工件后刷新系统提示词）、/memory enqueue（别名 /memory rebuild，排队一次整合维护）。mm 族仅交互 TUI 且需要启用 Hindsight 后端与心智模型：/memory mm [list]、/memory mm show <id>、/memory mm refresh [id]、/memory mm history <id>、/memory mm seed、/memory mm delete <id>（别名 remove）、/memory mm reload。也可以走 /settings 的 Memory 页。

存储路径：local 后端在 ~/.omp/agent/memories/<encoded-project>/，里面有 memory_summary.md、MEMORY.md、learned.md、skills/；mnemopi 在 ~/.omp/agent/memories/mnemopi/。

local 后端的部分默认值：memories.maxRolloutAgeDays = 30、minRolloutIdleHours = 12、maxRolloutsPerStartup = 64、threadScanLimit = 300、maxRawMemoriesForGlobal = 200、stage1Concurrency = 8、phase1InputTokenLimit = 4000、fallbackTokenLimit = 16000、summaryInjectionTokenLimit = 5000、rolloutPayloadPercent = 0.7；抽取用 default 角色，整合用 smol；autolearn.enabled 默认 false（实验性），autolearn.autoContinue 默认 false。

mnemopi 的默认值：bank 未设时为 default、scoping = per-project、autoRecall = true、autoRetain = true、retainEveryNTurns = 4、recallLimit = 8、recallContextTurns = 3、recallMaxQueryChars = 4000、injectionTokenLimit = 5000、embeddingVariant = en（可选 multilingual）、llmMode = smol（可选 remote、none），另有 dbPath、embeddingModel、embeddingApiUrl、embeddingApiKey、llmBaseUrl、llmApiKey、llmModel 以及默认关闭的 polyphonicRecall、enhancedRecall、proactiveLinking、noEmbeddings、debug。事实有 12 小时的年龄门与 24 小时的工作记忆生命周期。

hindsight 的默认值：bankId = omp、scoping = per-project-tagged、retainMode = full-session（可选 last-turn）、retainEveryNTurns = 3、retainOverlapTurns = 2、recallBudget = mid、recallMaxTokens = 1024、recallContextTurns = 1、recallMaxQueryChars = 800、recallTypes = ["world","experience"]、mentalModelsEnabled = true、mentalModelAutoSeed = true、mentalModelRefreshIntervalMs = 300000、mentalModelMaxRenderChars = 16000、requestTimeoutMs = 30000、recallTimeoutMs = 30000、retainTimeoutMs = 60000、reflectTimeoutMs = 120000。

文档明确的警告，值得逐条抄下来：

• autoRetain: true 会每 3 个用户轮次以及会话边界把用户和助手的文本发出去（不含工具调用、工具结果和思考）——文本会离开本机。
• 「不要故意让 omp 记住密钥」（do not intentionally ask omp to remember secrets）。
• 手工编辑 local 后端生成的文件不是持久的，整合过程会覆盖它们；mnemopi 的事实表行是只读的。
• /memory clear 在 Hindsight 上不会删除服务端记忆。
• 关掉后端不会删除它的存储；改作用域不会擦除已存知识。
• 召回的记忆是背景上下文，不是指令。
• mnemopi 默认 llmMode: smol，会把抽取任务发给你配置的提供商。

运行模式

文档把「模式」分成两类：启动模式（text / json / rpc / rpc-ui / acp，见上文）和交互式轮次控制。后者有：

模式	开启方式	行为
Plan	/plan [prompt]、Alt+Shift+P	只读地探索并产出一份 Markdown 计划草案（作为会话工件），批准前不动工作区。需要 plan.enabled（默认 true）
Goal	/goal <objective>、/guided-goal、omp --goal "..."	自主多轮 pursuing 一个目标，直到验证完成、被暂停/放弃或预算耗尽。需要 goal.enabled
Vibe	/vibe [prompt]	主会话变成只读的「导演」，驱动持久的 fast / good 两档 worker，自身只保留 read 工具集
Loop	/loop [count|duration] [prompt]	每次让出后自动重提交。正整数限次，时长如 90s、10 min、1h30m
Prewalk	omp --prewalk、/prewalk	计划待办存在后，在第一次 edit/write 时切到快模型（默认 smol 角色）。默认关闭
Fast	/fast [on|off|status]	优先服务档（OpenAI 的 service_tier=priority 或 Anthropic 的 fast speed）。可能更贵

Plan、Goal、Vibe 三者互斥（即使 Goal 处于暂停态也不行），错误提示分别是 Exit plan mode first、Exit goal mode first、Exit vibe mode first，另有 Plan mode is disabled、Goal mode is disabled。文档的建议是：如果 omp 意外拒绝编辑或一轮结束后还在继续，先看状态栏的模式段，用对应的斜杠命令离开或关掉该模式，而不是靠反复提示去跟它较劲。

Plan 模式：审阅界面提供五个选择——Approve and execute、Approve and compact context、Approve and keep context、Refine plan、Save and quit。审阅界面里 ↑/↓ 移动、Enter 确认、Tab/Shift+Tab 换页、Page Up/Page Down、g/G 跳转、a 加批注、d 或 Delete 删批注、u 撤销、c 复制、外部编辑器键、←/→ 切「continue with」选择器、Esc 关闭。当上下文超过执行模型窗口的 95% 时「保留上下文」不可用；内容侧栏需要至少 2 个标题和足够宽的终端。相关配置：plan.enabled（true）、plan.defaultOnStartup（false，仅交互模式生效）、modelRoles.plan（未设，示例 anthropic/claude-opus-4-5:high）。/plan-review 重开最近的计划审阅（仅计划模式激活时可用），错误 No plan to review yet。文档强调：「Planning is read-only for omp, not for you」——计划模式限制的是 omp，不是你自己动手改文件；Esc 在审阅界面只关掉浮层，计划模式仍然激活，且已做的编辑和批注不会回滚。omp --plan <model-id> 只是选 plan 角色的模型，不会进入计划模式；无头自动批准用 --plan-yolo（配 --plan-yolo-into <id>，默认 smol）。

Goal 模式：默认没有 token 上限，统计输入 + 输出 + 缓存写入 token，不含缓存读取。/goal budget 200000 设预算、/goal budget off 取消，另有 /goal set <objective>、/goal show（目标、状态、预算）、/goal pause、/goal resume、/goal drop；/guided-goal <粗略目标> 会先在聊天里做一轮访谈再据此配置 goal。状态有 active、paused、budget-limited、Goal mode completed。配置：goal.enabled（true）、goal.statusInFooter（true）、goal.continuationModes（["interactive"]），在 /settings → Tasks → Modes 下。Esc 中断会保存为 paused。文档原话：「token 预算是安全边界，不是成功的定义」，并且「永远不要把 budget-limited、收尾式回复、沉默或提供商错误当成完成」。没有单独的 /goal stop；暂停的 goal 必须先 resume 才能改预算，不能被静默覆盖；冷启动恢复会把活跃 goal 还原为 paused；不要把 /loop 和 goal 一起用（Loop 优先于 goal 的自动续跑）；生产变更、破坏性操作、凭据相关工作、含糊的产品决策不要无人值守跑 goal。

Vibe 模式：/vibe 切换，退出会停掉所有残留 worker 并精确恢复进入前的工具集，状态栏显示 Vibe。两档 worker：fast（默认路由到内置 sonic，走小模型角色）、good（默认路由到内置 task，走 task 角色或 default 回退）。配置键：modelRoles.fast_worker、modelRoles.good_worker、task.agentModelOverrides.sonic: "@fast_worker"、task.agentModelOverrides.task: "@good_worker"。worker 状态 starting / running / idle / dead，花名册显示档位、轮数、排队工作、解析出的模型和活动。用 /stats 看会话与 worker 的花费（/usage 报的是提供商账号限额）。坑：worker 共享同一个工作树（最好按文件不重叠分工）；worker 是 headless 的、没有逐命令交互确认，所以要用显式的 deny 策略（tools.approval）；Vibe 激活期间新会话 / 分叉 / 移动 / 交接都被阻止；loop.mode: reset 与 Vibe 组合会被拒绝；重置类循环不可用；被中断的轮次不会自动重启；被杀掉的 worker 不能复活；中断「导演」不会关掉 Vibe。

Loop 模式：/loop、/loop <prompt>、/loop <正整数> [prompt]、/loop <时长> [prompt]。示例：/loop 5 Review the next unreviewed migration、/loop 30m Process the next item in the queue、/loop 1h30m Check the next repository and record the result、/loop 10 minutes Re-run the acceptance check。时长单位 s、sec、m、min、h、hr 及复数形式，支持 1h30m 这种组合写法。loop.mode 取 prompt（默认）、compact、reset。状态字符串 Loop waiting、Loop running、Loop paused。迭代中按 Esc 中止本轮，迭代之间按 Esc 暂停或丢弃；要关闭 Loop 必须再执行一次 /loop。 纯散文被当作无限次的行内提示。Plan/Prewalk/Goal/Vibe 的徽章显示优先级高于 Loop。

Prewalk：一次性的会话内模型交接——强模型开始，第一次编辑后交给更快更便宜的目标模型。omp --model @slow --prewalk-into @smol、omp --prewalk、omp --prewalk-into openai/gpt-5-mini、omp --no-prewalk、omp config set prewalk.enabled true、会话内 /prewalk。prewalk.enabled 默认关闭。触发条件是「待办已存在 + 第一次完成的文件编辑（由起始模型做出）」，只读工作不会消耗它。通知文案：Armed、Switched、Nothing to switch（目标已与当前相同，则解除武装）。坑：--no-prewalk 不能与 --prewalk 或 --prewalk-into 同用；持久设置不会给恢复的对话武装；/prewalk 不接受目标参数，永远解析 @smol；切换不会改写已保存的角色设置；错误形如 Warning: prewalk disabled — model … not found、Warning: prewalk disabled — no API key for …；子智能体的 prewalk 单独配置（task.agentPrewalk）。不适合 prewalk 的场景：每次结果都会改变下一个假设的调试、安全敏感的迁移、需要反复做设计决策的工作。

Fast 与强制工具：/fast on|off|status（裸形式切换，toggle 也接受）是会话内持久化的，按 OpenAI / Anthropic / Google 家族分别作用；当前模型可能不支持开启。/extended-context [on|off|status] 切换持久的高级长上下文设置。/force read Inspect package.json and summarize its scripts、/force:read …、/force read（不带提示则作用于下一条消息）强制下一轮用某个工具，该工具必须处于激活状态，配合 /tools 查看。/vision <on|off|auto|status> 设置 inspect_image 委托工具的会话级覆盖。/live 启动 Codex 支持的实时语音模式（仅交互 TUI，再执行一次停止）。

子智能体与 Agent Hub

子智能体是聚焦的子会话，不继承主对话，只看到分派说明、共享上下文、工作区和项目指令。内置的专家（名字大小写敏感）：

名称	定位	默认路由角色
scout	只读的仓库探索	@smol
designer	UI/UX	@designer
reviewer	正确性评审	@slow
security-reviewer	只读漏洞分析	会话模型回退
librarian	外部库调研	@smol
task	通用多步任务	@task
sonic	机械性修改	@smol

三层概念的区分（文档专门讲）：Model 是具体的 provider/model；Role 是路由槽位；Agent 是行为画像（名字、指令、工具、模型 / prewalk / advisor 偏好）。agent 的模型解析优先级：task.agentModelOverrides.<agent-name> → agent frontmatter 里的 model → 父会话模型或回退。task.agentPrewalk / task.agentAdvisor 映射覆盖 frontmatter；task.prewalk（Generic Task Prewalk）影响内置的 task。

Alt+A 打开 Agent Hub（也可 Ctrl+S，或在空编辑器里连按两次 ←，后者是固定行为）。列表里 j/k 移动、Enter 看实时记录、Tab 看检查器、r 唤醒已挂起的 worker、x 结束、t 在树形/平铺间切换、Esc 关闭。状态有 running / idle / parked / aborted：给 running 的 worker 发消息是在安全边界处引导，idle 是追加任务，parked 要先唤醒。相关界面还有 /agents（Agent 控制中心，Ctrl+R 重载，含 New agent 按钮）、/jobs（结束的任务只保留约 5 分钟）、/settings、/hotkeys。

关键默认值（~/.omp/agent/config.yml）：async.enabled = true、task.maxConcurrency = 32（0 为无限）、task.maxRecursionDepth = 2、task.softRequestBudget = 200（1.5 倍时强制部分返回，0 关闭）、task.maxRuntimeMs = 0、task.agentIdleTtlMs = 420000（7 分钟后挂起）、task.isolation.mode = none、task.isolation.apply = true、task.isolation.merge = patch。「Prefer Task Delegation」取 default / preferred / always。输出上限由 PI_TASK_MAX_OUTPUT_BYTES（500000）和 PI_TASK_MAX_OUTPUT_LINES（5000）控制。

工作区隔离要在 /settings → Tasks → Isolation → Isolation Mode 设为 Auto，需要是 Git 仓库，worktree 建在 ~/.omp/wt（worktree.base 或 OMP_WORKTREE_DIR 可改），计划模式下不可用，且文档写明这不是安全沙箱；隔离的 worker 在拆除后不能复活。隔离后端由 pi-iso crate 解析：APFS 克隆、btrfs/zfs reflink、overlayfs、projfs、rcopy。

文档明确的警告：子智能体 headless 运行，没有逐工具的交互审批；每个 worker 是一个独立的模型会话，是成本乘数；同名冲突时项目定义盖过用户和内置定义。

自定义 agent 就是一个带 YAML frontmatter 的 Markdown 文件，正文是长期指令：

markdown
---
name: my-reviewer
description: 用于评审本项目改动的子智能体
tools: read, grep, glob, bash
model: "@slow"
prewalk: false
advisor: "@advisor"
---

这里是长期生效的指令正文。

位置与优先级：<project>/.omp/agents/<name>.md（向上查找最近的一个）→ ~/.omp/agent/agents/<name>.md（profile 下是 ~/.omp/profiles/<profile>/agent/agents/）→ 扩展的 <extension-root>/agents/<name>.md → 插件的 <plugin-root>/agents/<name>.md → 内置。第一个定义生效；.claude/agents、.codex/agents 不会被扫描。

必填字段只有 name 和 description。可选字段：tools（CSV 或列表，省略则继承父级的）、model、thinking-level（inherit|off|auto|minimal|low|medium|high|xhigh|max，也接受 thinking）、spawns（* 表示任意；有 task 工具但没写 spawns 时隐含 *）、autoload-skills、read-summarize（false 表示逐字读取）、output（JSON Schema）、blocking、prewalk、advisor。字段名 camelCase 或 kebab-case 都可以。没有 role 字段，要用角色别名就写进 model。

重载规则：委派时会重新读取 agent 定义；/agents 界面需要 Ctrl+R；插件提供的 agent 需要 /reload-plugins。导出内置定义：omp agents unpack（到 ~/.omp/agent/agents，默认）或 omp agents unpack --project（到 ./.omp/agents），另有 --dir <path>、-f/--force、--json。无效 YAML 会被静默跳过。

代码评审与提交

/review 是只读、带证据的正确性评审，会派生专门的评审子智能体并行审查分支、单个提交或未提交的修改。四种模式：1. Review against a base branch (PR Style)（从 merge base 起的三点 diff）、2. Review uncommitted changes（Git staged + unstaged，或 JJ working-copy diff）、3. Review a specific commit、4. Custom review instructions。

text
/review focus on cancellation and cleanup
/review https://github.com/acme/widgets/pull/418
/review https://github.com/acme/widgets/pull/418 focus on authorization boundaries
/review pr://acme/widgets/418/diff/all focus on migration safety

无头：omp -p "/review focus on authentication regressions"。

产出是按 P0–P3 排序、带 0.0–1.0 置信度评分的问题清单（含标题、解释、文件与行区间），外加 correct / incorrect 的明确结论。锁文件（package-lock.json、Cargo.lock、poetry.lock、flake.lock）、压缩/生成/快照/sourcemap、顶层 dist/、build/、out/、vendored 依赖、图片、字体、PDF、压缩包都会被排除；全被过滤时返回 No reviewable files。并行度按规模分档：<100 行或 ≤2 文件走单遍，<500 行最多 2 片，<2000 行最多 4 片（约每 3 文件 1 片），<5000 行最多 8 片（约每 2 文件 1 片），≥5000 行最多 16 片且不超过文件数；完整 diff 只在 ≤20 个可评审文件且 ≤50000 字符时整体带入。提交选择器显示最近 20 个提交，PR 选择器最多提供 3 个最近的不同引用。

提醒：PR 评审需要 gh 在 PATH 上并已 gh auth login（我的机器上没有 gh，这条路走不通，只能用基线分支 / 未提交 / 指定提交三种模式）；未跟踪文件不在 Git diff 里；issue URL、commit URL、其他托管平台、pr://418（缺 owner/repo）都不是 PR 目标，会被当成 focus 文本；/review 从不编辑、不跑修复、不合并。想自己主导评审用 /annotate code-review 打开 diff，在评审者运行前把批注钉在具体行上；/annotate 也可以针对最新回复、某条会话消息、某个文件或引用文本把批注粘进提示词。相关的还有 /green（盯 CI 直到当前分支变绿的工作流）和 omp cleanse [request]（用加权并行子智能体检测并修复项目诊断问题，-n/--agents <n>、-m/--model <selector>、-t/--tests、-a/--all；会话内是 /cleanse [request] [--all]）。

omp commit 会决定提交边界并写 Conventional Commit 信息：

sh
omp commit                # 生成信息、更新变更日志、提交已 staged 的 diff
omp commit --dry-run      # 预演（注意：仍可能改动索引）
omp commit --push         # 提交后推送
omp commit --no-changelog # 不动变更日志
omp commit -c "上下文说明" -m anthropic/claude-opus-4-5
omp commit --legacy       # 旧行为：无拆分审阅、无兜底
omp commit -h

索引规则：有 staged 就只考虑 staged；什么都没 staged 时行为等同 git add -A（已跟踪的修改与删除 + 未跟踪且未被忽略的文件），被忽略的文件排除；锁文件不参与语义分析但仍会提交（挂到对应 manifest 的那个提交，否则挂最后一个）。每处 staged 改动恰好出现一次，一个文件不能跨提交，存在循环依赖时会在写入任何内容前拒绝。 源码文件权重高于测试、文档和配置，所以第一个提交就是最重要的那个。

它通过 git_overview、git_file_diff、git_hunk 读取工作区。信息格式如 fix(parser): handled empty token streams，类型有 feat、fix、refactor、perf、docs、test、build、ci、chore、style、revert，摘要 ≤72 字符、以过去式动词开头，重复的类型前缀会被剥掉。变更日志找最近的 CHANGELOG.md（向上到仓库根为止），放在拆分后的最后一个提交里，且在交互式拆分确认之前应用。默认的提交 agent 用 smol 角色，主模型作为回退。

文档列的坑值得抄下来：--dry-run 仍可能修改索引；拆分确认时任何非 y/yes 都中止，但非交互 shell 会直接继续不提示；--push 没有额外确认，且没有新提交时会推送已有提交；拒绝拆分后变更日志可能处于已修改/已 staged 状态；非零退出码不一定意味着没有创建提交（有机械兜底提交）；--legacy 没有拆分审阅也没有兜底；避免用 git reset --hard 收拾残局。

想要图形化的 git 操作，本机 v18.16.0 还有一个 omp git 子命令：交互式全屏 git UI，含分栏 diff 查看器、暂存侧栏和提交编辑器。

审批与安全边界

审批模式决定哪一类动作需要确认：

模式	行为
always-ask	写入和执行都要确认（读取从不提示）
always-ask-cached	同上，但记住已批准的选择。本机 omp --help 实测有这个取值，文档站 CLI 页只列了三个
write	写入及以上需要确认，文档推荐的交互模式
yolo	全部自动放行，内置默认值

sh
omp --approval-mode always-ask
omp --approval-mode write "fix the failing test"
omp --approval-mode yolo "apply the reviewed migration"
omp --auto-approve "run the release script"     # 等价 --yolo
omp acp --approval-mode yolo
omp --config ./ci-approvals.yml -p "update generated files and report the diff"
omp config get tools.approvalMode
omp config get tools.approval

持久配置在 ~/.omp/agent/config.yml 或项目 .omp/config.yml（遗留的 .omp/settings.json 也认）：tools.approvalMode 设模式，tools.approval 是按工具名的映射（值 allow / prompt / deny，键如 bash、read、eval、computer、browser、task、mcp__filesystem__delete），bash.patterns 是有序的 match + approval 规则、第一条命中生效。

判定顺序：工具级 deny → 用户级 deny → 工具自带的 allow/prompt 安全性 → 用户级 allow/prompt → 模式对应的能力档（read / write / exec）。层级：运行时 flag → 后面的 --config → 项目 → 全局 → 默认；映射深合并，数组（如 bash.patterns）整体替换。

要记住的边界（文档明写）：

• 审批提示不是沙箱。
• always-ask 从不为读取提示。
• 未知的自定义工具声明会被当作可执行档；MCP 工具通常算写入档。
• 无头运行时遇到需要审批的动作会直接失败，报 requires approval but no interactive UI available——CI 里应该用 deny 而不是指望提示。
• 子智能体按 yolo 运行，继承来的 prompt 会被拒绝。
• yolo 会跳过裸的安全性覆盖（bash 的危险形态），但不跳过显式 deny 和提供商侧检查。
• computer 工具即使在 yolo 下，提供商侧的安全检查也总要交互确认，无头环境失败关闭。
• computer 默认关闭；read_only: true 时算读取档。
• 无效的策略字符串会被忽略。
• bash.patterns 覆盖不到通过 eval 起的 shell。
• 审批只对单次调用有效。
• ACP 会保留客户端对 bash、edit、delete、move 的权限门，除非显式设 tools.approvalMode: yolo。

/security 提供漏洞导向的仓库扫描，security.enabled 默认关闭，需要 omp config set security.enabled true（或 /settings → Tools → Available Tools → Security）。子命令见下文斜杠命令一节。要点：扫描作为后台操作启动，用 /security status 查而不是干等；--path / --exclude 相对于仓库根，且不是保密沙箱（评审者会看到周围代码）；指纹过期会拒绝执行，必须重新 plan；输出目录不能在仓库内，非空目录除非 --archive-existing 否则被拒；取消是协作式的；扫描跑在无扩展、无 MCP、无 shell、无回退、无轮换的会话里；重启无法续跑（会标记为 failed）；关闭开关不删数据；云端 pull 在 Git origin 不匹配时失败关闭；没有 /security cloud cancel；compare 要求后置扫描是 completed；扫描内容会发给当前模型的提供商。阶段流转 queued → preparing → reviewing → publishing → completed，终态另有 partial、cancelled、failed；验证状态从 unvalidated 起，可到 validated/rejected/partial/error；处置状态 open、false_positive、accepted_risk、fixed、wont_fix，除 open 外都必须给理由。产物目录含 scan.json、findings.json、report.md、results.sarif（SARIF 2.1）、provenance.json，POSIX 上目录 0700、文件 0600；归档时旧目录改名为 .archive-<scan-id>。原生扫描的预检要求 Git 仓库 + 活跃模型 + 已存储的 OAuth 登录，API Key（环境变量、models.yml、--api-key、基于 key 的登录）都不够用；云端扫描需要 openai-codex 的 ChatGPT OAuth，且会消耗云扫描额度。

上下文文件与规则

omp 会自动加载一批「始终生效」的 Markdown 指令文件。原生位置：AGENTS.md（<repo>/AGENTS.md、<repo>/.omp/AGENTS.md、~/.omp/agent/AGENTS.md）、RULES.md（<repo>/.omp/RULES.md、~/.omp/agent/RULES.md）、APPEND_SYSTEM.md 和 SYSTEM.md（<启动目录>/.omp/…）。profile 目录是 ~/.omp/profiles/<profile>/agent/。

SYSTEM.md / APPEND_SYSTEM.md 的直接查找顺序：<启动目录>/.omp/ → .claude/ → .codex/ → .gemini/，然后是用户目录（活跃 profile 的 agent/、活跃的 Claude 配置目录、~/.codex/、~/.gemini/）。第一个匹配的文件名生效。

兼容提供商按优先级 1–7：native → claude（.claude/CLAUDE.md）→ agents（.agent/AGENTS.md 或 .agents/AGENTS.md，用户级同理，.agent 胜 .agents）→ codex（~/.codex/AGENTS.md）→ gemini（.gemini/GEMINI.md、~/.gemini/GEMINI.md）→ opencode（~/.config/opencode/AGENTS.md）→ github（.github/copilot-instructions.md、~/.copilot/copilot-instructions.md、COPILOT_HOME）→ agents-md（AGENTS.md）。

文件里可以用 @path 导入其他文件（支持 ~/... 和绝对路径，相对路径按导入方文件解析），最多 5 跳，成环会停，读不到的导入保持为字面 @path；@ 必须在行首或跟在空白后，行内代码和围栏代码块里的不生效。

坑（文档明写）：<repo>/.omp/AGENTS.md 会遮蔽同层的 <repo>/AGENTS.md，原话是「除非这种遮蔽是有意的，否则不要两个都建」；SYSTEM.md 会移除内置的行为与工具指导，APPEND_SYSTEM.md 才是更安全的默认；--system-prompt 和 --append-system-prompt 会覆盖发现的文件（值可以是字面文本或文件路径）；改动后需要 /new 或重启；文件名大小写敏感；扫描会在把 ~/AGENTS.md 当项目上下文之前停止；Cursor/Cline 规则和 *.instructions.md 是作为「规则」发现的，不是上下文文件；--no-rules 在本次运行禁用 RULES.md 和所有发现的规则；--no-context-files 禁用全部上下文文件；COPILOT_CUSTOM_INSTRUCTIONS_DIRS 和 disabledProviders 可以调整范围；在 /extensions 的 Context Files 里能看到实际加载了什么。

**TTSR（时间回溯式流规则）**文件放在 <project>/.omp/rules/<name>.md（或 .mdc）和 ~/.omp/agent/rules/<name>.md（跟随 profile 和 PI_CODING_AGENT_DIR），文件名就是规则名。frontmatter 字段：description、condition（JS 正则，旧名 ttsr_trigger 也接受）、astCondition（ast-grep）、scope、globs、interruptMode（always / prose-only / tool-only / never）、alwaysApply。scope 取值 text、thinking、tool 或 toolcall、tool:<name>（如 tool:bash）、tool:<name>(<glob>)（如 tool:edit(src/**/*.ts)）；正则支持 (?i)、(?m)、(?s) 标志。

全局默认：ttsr.enabled: true、contextMode: discard（可选 keep）、interruptMode: always、repeatMode: once（可选 after-gap）、repeatGap: 10（单位是完成的轮数，不是秒）、builtinRules: true、disabledRules: []。触发时的通知是 Injecting rule: no-box-leak。每条规则每会话只触发一次，触发状态随会话保存。

优先级：ttsr.disabledRules 先剔除 → 项目原生规则胜同名的用户原生规则（第一个发现的生效）→ 有效的 condition/astCondition 胜 alwaysApply: true → 单规则的 interruptMode 胜全局 → 任何会中断的匹配就中断。

命令行测试与管理：

sh
omp ttsr list
omp ttsr test --rule .omp/rules/no-box-leak.md --source tool --tool edit --path src/lib.rs 'let value = Box::leak(Box::new(input));'
omp ttsr test src/lib.rs --verbose --json
omp ttsr scan --rule .omp/rules/no-box-leak.md src/
omp config set ttsr.enabled true
omp config set ttsr.repeatMode after-gap
omp config set ttsr.repeatGap 10
omp config set ttsr.disabledRules '["no-box-leak"]'
omp config get ttsr.builtinRules
omp config get ttsr.contextMode

omp ttsr test 的 --file <path|-> 支持从文件或直接读 stdin，--source text|thinking|tool 指定来源，--max-bytes <n> 设上限（0 表示不限），--no-gitignore 忽略 gitignore，-r/--rule <file> 指定规则文件。

提醒：不要把密钥写进规则正文；避免 (.*)+ 这类灾难性回溯；匹配无法撤销已完成的工具调用；astCondition 只对带可识别扩展名的源码类 edit/write 生效；新增或修改文件/配置后要开新会话；无效的正则或 AST 模式会被忽略而不是致命报错。会话里还可以用 /omfg <抱怨> 把对反复出现行为的抱怨直接转成一条 TTSR 规则。

扩展生态：八个概念别搞混

概念	是什么	放哪里
Agent（子智能体）	行为画像 + 子会话：名字、指令、工具集、模型路由	.omp/agents/<name>.md、~/.omp/agent/agents/<name>.md
Role（角色）	只决定用哪个模型的路由槽位	config.yml 的 modelRoles
Skill（技能）	指令与约定的手册，不增加任何权限或可执行工具	.omp/skills/<name>/SKILL.md、~/.omp/agent/skills/<name>/SKILL.md
Hook（钩子）	订阅事件的可信 TS/JS 模块，观察或改变已有行为	.omp/hooks/pre|post/、~/.omp/agent/hooks/pre|post/（不递归）
Custom Tool（自定义工具）	给模型增加一个可调用的新动作	.omp/tools/<name>/index.ts、<config-dir>/tools/<name>/index.ts
Extension（扩展）	完整的进程内运行时模块，是 hook 的超集，可注册工具/命令/快捷键/UI/提供商	package.json 里 "omp": {"extensions": ["./src/index.ts"]}
Plugin（插件）	可安装的分发单元，把上面这些打包	omp plugin install …，项目级记在 .omp/plugins/installed_plugins.json
Marketplace（市场）	只是插件目录，不是插件、没有中心商店、没有签名或认证	.omp-plugin/marketplace.json（回退 .claude-plugin/marketplace.json）

技能靠 frontmatter 的 description 被广告给模型：会话开始时只提供名字和描述，命中时才加载正文。手动调用 /skill:<name> [arguments]（也可以在散文里内联提及），关掉用 skills.enableSkillCommands: false；被隐藏的技能仍可调用。发现只往下一层。frontmatter 支持 description（对 .omp/自定义/插件/GitHub 来源是必填）、name、hide、disable-model-invocation；globs 和 alwaysApply 会被忽略。omp 也会发现兼容目录：用户级 ~/.agent/skills/、~/.agents/skills/、~/.claude/skills/、~/.codex/skills/、~/.config/opencode/skills/；项目级 .agent/skills/、.agents/skills/、.claude/skills/、.codex/skills/、.opencode/skills/、.github/skills/；自动学到的托管技能在 ~/.omp/agent/managed-skills/。提供商优先级：原生 .omp → OMP/插件 → Claude → Agent/Codex → OpenCode → GitHub → 托管的自动学习技能。配置键 skills: enabled, enableSkillCommands, includeSkills, ignoredSkills, customDirectories，flag omp --no-skills、omp --skills 'git-*,docker'；禁用状态持久化为 disabledExtensions: - skill:<name>。各兼容提供商的开关 enablePiUser/PiProject/AgentsUser/AgentsProject/ClaudeUser/ClaudeProject/CodexUser 都默认 true。用 /extensions 看技能的来源和状态，/reload-plugins 刷新。本机 v18.16.0 还有 omp skill 子命令，可在 Skillshare 注册表（skills.omp.sh）上安装、搜索、发布、管理技能。

钩子的契约是默认导出一个工厂 (pi: ExtensionAPI) => …，用 pi.on("event", (event, ctx) => …) 订阅，从 @oh-my-pi/pi-coding-agent 导入，用 isToolCallEventType("bash", event) 收窄类型。目录不递归，只认直接的 .ts/.js；pre/ 和 post/ 只是组织用的，不是事件选择器。一次性加载用 omp --hook <path> 或 --extension <path>，持久化写在 ~/.omp/agent/config.yml 的 extensions: 列表里。检查是否加载：/extensions 或 omp -p '/extensions'。

行为类事件：resources_discover、input（返回 handled: true 停止链）、user_bash（!/!!）、user_python（$/$$）、tool_call（返回 {block, reason, input}，第一个 block 生效；替换后的 input 会重新校验和审批，但对 computer 工具不生效）、tool_result、context、before_provider_request、before_agent_start、session_before_switch/branch/compact/tree、session.compacting、session_stop（返回 {continue: true, additionalContext}）。通知类事件包括 session_start/switch/branch/compact/tree/shutdown、agent_start/end、turn_start/end、message_start/update/end、tool_execution_start/update/end、tool_approval_requested/resolved、auto_compaction_*、auto_retry_*、retry_fallback_*、ttsr_triggered、todo_reminder、goal_updated、credential_disabled、mcp_notification、after_provider_response。

限制：处理函数按注册顺序 await，总预算 30 秒；tool_call 的超时由 extensionHandlers.toolCallTimeoutMs（默认 30000）控制，且超时失败关闭（阻断该调用）；session_shutdown 并发上限 2 秒。不要用 00- / 99- 这种文件名排序技巧。 打包形式：package.json 里写 "omp": {"extensions": ["./hooks/pre/force-push.ts"]}，然后 omp --hook ./force-push-guard 或 omp install ./force-push-guard（-l 表示项目级）。

自定义工具是可信代码，以你的用户权限运行。路径：项目 .omp/tools/<name>/index.ts（扁平的 .omp/tools/hello.ts 也可以）；用户级 <active-config-dir>/tools/<name>/index.ts（omp config path 查，默认 ~/.omp/agent）；兼容 .claude/tools、.codex/tools 的扁平文件。.md/.json 只作为元数据。发现在会话启动时进行，所以要重启；用 /tools 验证，或一次性跑 omp -p '…'。契约是默认导出 CustomToolFactory，必填 name、label、description、parameters（用 pi.zod / pi.arktype / pi.typebox）、execute(toolCallId, params, onUpdate, ctx, signal)；可选 strict、hidden、loadMode（"discoverable" 默认 | "essential"）、approval（"read"/"write"/"exec"，省略即 "exec"）、onSession、renderCall、renderResult（返回 @oh-my-pi/pi-tui 的 Component）。辅助能力有 pi.cwd、pi.exec(command, args, options?)、pi.ui / pi.hasUI。返回 {content, details?, isError?}，硬失败抛 Error。同名冲突会被拒绝，没有覆盖 flag；加载失败在 ~/.omp/logs/ 里记为 Custom tool load failed。onSession 的触发原因有 start, switch, branch, tree, shutdown, auto_compaction_start/end, auto_retry_start/end, ttsr_triggered, todo_reminder。

扩展是 TS/JS 模块，在进程内加载、不做沙箱，可注册命令、工具、处理函数、UI 和提供商；hook 是它的一个受限子集，plugin 是它的打包分发单元。开发依赖 bun add --dev @oh-my-pi/pi-coding-agent；布局是 package.json + src/index.ts，manifest 写 "omp": {"extensions": ["./src/index.ts"]}（数组，路径相对包根，支持 .ts/.js/.mjs/.cjs，遗留键 pi.extensions 也认）。加载 omp --extension ./hello-extension（-e）；持久化写 ~/.omp/agent/config.yml 或 <project>/.omp/config.yml 的 extensions:（相对路径按启动目录解析）；松散目录 <project>/.omp/extensions/ 和 ~/.omp/agent/extensions/（扫描 .ts/.js 及一层 index.ts|js 子目录）；保持启用可以 omp plugin link ./hello-extension 或 omp install ./hello-extension（符号链接，无热重载）；发布走 npm pack --dry-run → npm publish → omp install @acme/hello-extension 或 omp install github:acme/hello-extension#v1.0.0。工厂签名 export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>，注册要在工厂内做，运行时动作（如 pi.sendMessage()）只能在之后的处理函数里调用。

ExtensionAPI 提供 zod/arktype/typebox、logger、pi、on、events、registerTool、registerCommand、registerShortcut、registerFlag、registerMessageRenderer、registerAssistantThinkingRenderer、registerComposerShape、registerProvider/unregisterProvider、registerFileWriteFallback/registerFileDeleteFallback、sendMessage、sendUserMessage、appendEntry、exec、getActiveTools/getAllTools/setActiveTools、getCommands、setModel、getThinkingLevel/setThinkingLevel、getServiceTiers/setServiceTier、getSessionName/setSessionName、setLabel、getFlag。注意扩展的 execute 签名与自定义工具参数顺序不同：execute(toolCallId, params, signal, onUpdate, ctx)。ToolDefinition 的可选字段还有 defaultInactive、deferrable、mcpServerName、mcpToolName。

扩展包里这些约定目录不需要 manifest 字段：skills/<name>/SKILL.md、commands/*.md、rules/*.{md,mdc}、prompts/*.md、hooks/pre/*、hooks/post/*、tools/*、.mcp.json/mcp.json。

坑：命令名不能与内置冲突；保留组合键不可替换；运行时工厂 ID 是 extension-module:<filename>（index.ts 用父目录名）；检查 disabledExtensions；一个扩展失败不会阻塞其他扩展；日志在 ~/.omp/logs/；改工厂后要重启；UI 相关代码要用 ctx.hasUI 或 ctx.mode === "tui" 保护；用 ctx.setTimeout/setInterval/clearTimer 而不是全局的；ctx.isProjectTrusted() 目前只是兼容性检查（文档原话是「omp currently trusts loaded project inputs」）。

插件与市场的常用命令：

sh
omp plugin list                                    # 裸 omp plugin 也是 list
omp plugin install <target...> [--scope user|project] [--dry-run] [--force]
omp plugin uninstall <name...> [--dry-run]
omp plugin link <path>                             # 符号链接本地插件用于开发
omp plugin doctor [--fix] [--json]
omp plugin features <plugin> [--enable a,b | --disable a,b | --set a,b]
omp plugin config list|get|set|delete <plugin> [<key> [<value>]]
omp plugin config validate
omp plugin enable|disable <name...> [--scope user|project]
omp plugin marketplace add|list|update|remove <source>
omp plugin discover [marketplace]
omp plugin upgrade [name@marketplace] [--scope user|project]
omp install <target...>                            # plugin install/link 的简写
omp update -l                                      # 只更新插件

安装源支持 '@scope/plugin@1.2.3'、'github:org/repo#v1.4.0'、完整 Git URL、本地目录、plugin-name@marketplace-name；Git 简写还有 gitlab:、bitbucket:、codeberg:、sourcehut:、srht:。安装时选特性：'@scope/plugin[search,web]'、'pkg[*]'、'pkg[]'。作用域只对 marketplace 安装有意义，默认 user，project 记在 .omp/plugins/installed_plugins.json，启用的项目插件会遮蔽启用的用户插件。omp plugin config get 的密钥字段在显示输出里会打码。

没有顶层的 omp marketplace / omp discover / omp enable / omp disable / omp upgrade，必须用 omp plugin … 形式；npm/Git 来源没有 omp plugin update，要升级就重装；marketplace 安装不支持 --dry-run。目录清单必需字段是顶层 name、owner.name、plugins[]，每个插件必需 name + source，可选 version、description、category、sha、ref；插件名只能用小写字母、数字、-、.，首尾必须是字母数字，≤64 字符；相对 source 必须以 ./ 开头，外部源用 github/url/git-subdir 对象；npm 源对象能被解析但不可安装。移除目录不等于卸载它的插件；--force 只是重装，不做额外校验。marketplace.autoUpdate 默认 notify（只写 debug 日志），可选 off、auto，用 omp config get|set marketplace.autoUpdate … 改。存储位置：用户级 ~/.omp/plugins/installed_plugins.json，项目级最近的 .omp/plugins/installed_plugins.json。

会话内的对应命令：/marketplace（或 /marketplace install，打开交互式安装浏览器）、/marketplace add <source>（如 anthropics/claude-plugins-official）、/marketplace remove|rm <name>、/marketplace update [name]（只刷新目录）、/marketplace upgrade [name@marketplace]（升级代码）、/marketplace list、/marketplace discover [marketplace]、/marketplace install [--force] [--scope user|project] <name@marketplace>、/marketplace uninstall、/marketplace installed（列出已装插件、作用域和遮蔽状态）、/marketplace help、/plugins [list]、/plugins enable|disable [--scope user|project] <name@marketplace>、/reload-plugins。在 TUI 之外必须显式给出 name@marketplace。

重载规则很重要：/reload-plugins 只刷新发现缓存、技能、Markdown 文件斜杠命令、任务 agent、能力状态和 MCP 连接；改动扩展模块、钩子、可执行命令模块、自定义工具、提示词模板后必须重启 omp，这些初始化过的面不会原地重建。/move 会刷新目录级能力，但要加载改过的模板或可执行代码，开新会话才是可靠办法。

MCP

配置文件位置（优先级从低到高）：根目录 mcp.json / .mcp.json → ~/.omp/agent/mcp.json → .omp/mcp.json；profile 走 ~/.omp/profiles/<name>/agent/mcp.json。schema 地址 https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json。

传输方式：stdio（省略 type 时的默认）、http（Streamable HTTP）、sse（遗留）；command 和 url 不能同时出现，缺 command 会报 stdio server requires "command"。字段有 enabled、timeout（毫秒，默认 30 秒，0 表示禁用超时）、requestIdFormat（默认 "number"）、command、args、env、cwd、url、headers、oauth（clientId、clientSecret、redirectUri、callbackPort、callbackPath、prompt）、auth；disabledServers / enabledServers 控制启停，拒绝列表优先级最高。支持 ${VAR} 和 ${VAR:-default} 展开，值以 ! 开头会当 shell 命令执行；OMP_MCP_TIMEOUT_MS 覆盖所有超时。auth.type: "apikey" 会被接受但不会注入 key。工具在模型侧的名字是 mcp__<server>_<tool>，服务器的 prompt 以 /<server>:<prompt> [name=value…] 调用。

会话内命令：

text
/mcp add                                            # 打开设置向导（仅交互 TUI）
/mcp add <name> [--scope project|user] [--url <url> --transport http|sse] [--token <token>] [-- <command...>]
/mcp list
/mcp test <name>
/mcp remove <name> [--scope project|user]           # 别名 /mcp rm，默认删项目条目
/mcp enable|disable <name>
/mcp reconnect <name>
/mcp reload                                         # 重载配置并重新绑定运行时工具
/mcp reauth <name> | /mcp unauth <name>
/mcp resources | /mcp prompts | /mcp notifications
/mcp smithery-search <keyword> [--scope project|user] [--limit <1-100>] [--semantic]
/mcp smithery-login | /mcp smithery-logout
/mcp help                                           # 裸 /mcp 也是显示帮助

只给名字的 /mcp add <name> 会打开预填的向导；给 --url 或 -- <command…> 则快速添加远程 HTTP/SSE 或本地 stdio 服务器。Smithery 相关环境变量 SMITHERY_URL（https://smithery.ai）、SMITHERY_API_URL（https://api.smithery.ai）、SMITHERY_API_KEY。

omp 会自动导入 Claude Code、Codex、Gemini CLI、OpenCode、Cursor、Windsurf、VS Code、插件和扩展里的 MCP 配置。相关配置键（~/.omp/agent/config.yml）：mcp.enableProjectConfig（默认 true）、mcp.renderMarkdownResults（true）、mcp.notifications（false）、mcp.notificationDebounceMs（500）。想在某次运行排除项目的 .mcp.json，用 --config 指向一个嵌套键的 YAML 覆盖文件——扁平写法 mcp.enableProjectConfig: false 会被忽略：

yaml
mcp:
  enableProjectConfig: false

提醒：同名服务器第一个定义生效、不合并；OAuth 凭据按 profile + URL 作用域存在 agent.db / auth broker 里，所以不受信任的 checkout 只要 URL 相同就能复用你的凭据，隔离办法是用单独的 profile；/mcp test 显示版本、工具数和最多 10 个工具名，不会真的调用工具；Esc 取消测试。

自己写 MCP 服务器时：npm install @modelcontextprotocol/server zod（或 @modelcontextprotocol/node），协议修订版 2025-11-25，核心方法 initialize、notifications/initialized、tools/list（带 nextCursor）、tools/call，服务器可反向请求 ping 和 roots/list（项目以 file: URI 给出），变更通知走 tools.listChanged + notifications/tools/list_changed。HTTP 传输要保留 Mcp-Session-Id、接受 MCP-Protocol-Version: 2025-11-25，示例端点 http://127.0.0.1:3000/mcp，配合 localhostHostValidation()、localhostOriginValidation()、toNodeHandler、createMcpHandler。工具名会被规范化：小写，[a-z_] 之外的字符替换为 _，超过 64 字符则截断并附稳定哈希后缀，冲突时保留一个确定性胜者。返回 content，可选 structuredContent，图片用 data + mimeType，预期内的失败用 isError: true，认证质询用 _meta["mcp/www_authenticate"]。绝不要往 stdout 打日志（stdio 传输下会污染协议）；处理器本身不做认证。调试用 node --check mcp/hello-server.mjs 和 npx @modelcontextprotocol/inspector node ./mcp/hello-server.mjs。

快捷键

/hotkeys 显示当前生效的快捷键列表（不含扩展新增的）。最常用的：

按键	作用
Enter	发送 / 引导当前轮
Shift+Enter、Ctrl+J、Alt+Enter	换行
Ctrl+Q、Ctrl+Enter	排队后续消息
Escape	关闭弹层 / 中断当前操作（不退出）
Ctrl+O	展开或折叠工具输出
Ctrl+Shift+O	隐藏或显示工具活动（只看散文）
Ctrl+R	搜索提示历史
Ctrl+G	用 $VISUAL / $EDITOR 编辑长草稿
Alt+R	重试上一个失败轮次
Alt+Up、Shift+Up	把排队消息取回编辑器
Alt+A	Agent Hub
Alt+M	模型中心（改持久角色）
Alt+P	临时切模型（只影响本会话）
Ctrl+P / Ctrl+Shift+P	在角色模型间前后循环
Shift+Tab	循环思考强度
Ctrl+T	显示 / 隐藏思考块
Alt+L	重置并重绘显示（花屏时用）
Alt+Shift+P	切换 Plan 模式
Ctrl+L	切换实时语音模式
Ctrl+S	观察会话（旧键位，也能开 Agent Hub）
Ctrl+D	退出并保存草稿
Ctrl+C	清空编辑器；半秒内（500 ms）再按一次退出
Ctrl+Z	挂起（Windows 上不可用）
Ctrl+V（Windows 也可 Alt+V）	粘贴剪贴板图片（无图时粘文本）
Ctrl+Shift+V、Alt+Shift+V	原样粘贴文本
Alt+Shift+C	复制当前提示
Alt+Shift+L	复制当前行

编辑器内的 Emacs 风格键位也在：Ctrl+A/Home 行首、Ctrl+E/End 行尾、Ctrl+B/Ctrl+F 左右一字符、Alt+B/Alt+F/Alt+←/Alt+→/Ctrl+←/Ctrl+→ 左右一词、Ctrl+W/Alt+Backspace/Ctrl+Backspace 删前一词、Alt+D/Alt+Delete 删后一词、Ctrl+U 删到行首、Ctrl+K 删到行尾、Ctrl+Y 粘回（yank）、Alt+Y yank-pop、Ctrl+-/Ctrl+_ 撤销、Ctrl+. 拼写建议、Ctrl+]/Ctrl+Alt+] 前后跳转、Page Up/Page Down 翻页。选择器里 Enter 确认、Escape 或 Ctrl+C 取消。

自定义写在 ~/.omp/agent/keybindings.yml（profile 走 ~/.omp/profiles/<name>/agent/keybindings.yml，也可用 $PI_CODING_AGENT_DIR/keybindings.yml；旧的 keybindings.json 会迁移，keybindings.yaml 也接受）。格式是 actionId: chord，例如 app.model.cycleForward: ctrl+p、app.tools.expand: ctrl+o、app.agents.hub: alt+a、app.editor.external: ctrl+g、app.display.reset: alt+l、app.plan.toggle: alt+shift+p、app.history.search: ctrl+r、app.interrupt: escape、app.exit: ctrl+d；app.session.new/.tree/.fork/.resume 默认未绑定，app.stt.toggle 也未绑定（按住 Space 录音）。

规则与坑：重映射会替换整个默认列表，[] 表示禁用该动作，改完要重启 omp；修饰键名是 ctrl、shift、alt、super，esc / return 是别名，支持 f1–f12，不支持多步序列；保留组合键不可替换。Windows 专属：Ctrl+Z 无法挂起 omp；Windows Terminal 不传递独立的 Ctrl+Enter，排队请用 Ctrl+Q；如果 Ctrl+V 被终端捕获，粘贴图片用 Alt+V；换行优先用 Alt+Enter。在空编辑器里连按两次 ← 打开 Agent Hub 是固定行为，不可改。

主题

/settings → Appearance → Dark Theme / Light Theme 选择。默认暗色槽是 titanium、亮色槽是 light，启动回退 dark。配置写在 ~/.omp/agent/config.yml：

yaml
theme:
  dark: titanium
  light: light

终端主题检测顺序：OSC 11 背景色 → COLORFGBG → macOS 外观（Zellij 下）→ 回退 dark。内置主题名包括 dark、light、titanium、dark-terminal。

自定义主题文件放在 ~/.omp/agent/themes/<name>.json（profile 走 ~/.omp/profiles/<profile>/agent/themes/<name>.json，也可 $PI_CODING_AGENT_DIR/themes/<name>.json）。项目本地主题不会被扫描。 JSON 里 name 和 colors 必填，vars、export（pageBg、cardBg、infoBg）、symbols 可选；颜色值可以是 "#RRGGBB"、0–255 的整数、vars 里的名字，或 ""（用终端默认）。除 thinkingMax（回退到 thinkingXhigh）外所有 token 组都必填。symbols.preset 取 unicode、nerd、ascii，可按命名空间覆盖：status.*、nav.*、tree.*、boxRound.*、boxSharp.*、sep.*、icon.*、thinking.*、md.*、lang.*、tab.*、tool.*，另有 spinnerFrames 的 status / activity。

坑：内置主题名与自定义文件同名时内置胜；实时重载只监听当前激活的那个自定义文件（没有重载命令），内置主题不监听；Color Blind Mode 只会把 toolDiffAdded 的绿色往蓝色偏移；全局的 Symbol Preset 会覆盖主题自带的 preset；vars 缺失或成环是错误。

LSP 与调试器

omp --no-lsp 关闭语言服务器特性；/session 里能看到每个服务器的状态 available / connecting / ready / error。设置项（/settings → Files → LSP，或 ~/.omp/agent/config.yml / .omp/config.yml）：lsp.enabled（true）、lsp.lazy（true）、lsp.shared（true）、lsp.formatOnWrite（false）、lsp.diagnosticsOnWrite（true）、lsp.diagnosticsOnEdit（false）、lsp.diagnosticsDeduplicate（true）。

配置文件位置：<project>/.omp/lsp.json、~/.omp/agent/lsp.json、<project>/.omp/lsp.yaml。优先级由低到高：~/lsp.* 与 ~/.lsp.* → 插件 → 用户配置目录（omp agent 目录 + Claude/Codex/Gemini）→ <cwd>/.omp、<cwd>/.claude、<cwd>.codex、<cwd>/.gemini → <cwd>/lsp.* 与 <cwd>/.lsp.*；同一位置内按 lsp.json、.lsp.json、lsp.yaml、.lsp.yaml、lsp.yml、.lsp.yml 的顺序。

新增服务器时必填字段是 command、fileTypes、rootMarkers；可选 args、languageId、initOptions、settings、disabled、warmupTimeoutMs、isLinter、capabilities（flycheck、ssr、expandMacro、runnables、relatedTests，rust-analyzer 用）、workspaceReadyTimings（timeoutMs、pollMs、settleMs、statusRequestTimeoutMs）；顶层 idleTimeoutMs 省略、为 0 或负数表示不禁用空闲关闭；servers 包裹层可选。根标记如 package.json、Cargo.toml、go.mod；项目本地的可执行文件（node_modules/.bin、venv 的 bin、Ruby binstubs、Go 的 bin）优先于 PATH。

坑：发现从不向上遍历父目录；settings、initOptions、capabilities、workspaceReadyTimings 是整体替换（不深合并），条目按名字浅合并；不要混用 servers 包裹和扁平写法；无效 JSON/YAML 静默忽略；改完要开新会话；标了 isLinter 的服务器不提供定义/引用/重命名。

调试器：debug.enabled 默认开（omp config get debug.enabled / omp config set debug.enabled true），但工具只在有合适 DAP 适配器时才出现；一次只有一个根调试会话，多数启动会停在入口。配置在 .omp/dap.json、~/.omp/agent/dap.json、启动目录的 dap.json（优先级高于 .omp/dap.json），也接受 .dap.json、dap.yaml、.dap.yaml、dap.yml、.dap.yml。字段：command（必填）、args、languages、fileTypes（小写、带前导点）、rootMarkers、launchDefaults、attachDefaults（skipAttachRequest: true）、connectMode（stdio 默认 | socket | tcp，会替换 ${port}）、acceptsDirectoryProgram: true（Delve/Go 需要）。排序标记 pyproject.toml、go.mod、Cargo.toml、package.json、CMakeLists.txt；无扩展名的原生可执行文件先试 GDB 再试 LLDB。

安装适配器示例：

sh
uv add --dev debugpy
go install github.com/go-delve/delve/cmd/dlv@latest    # 记得让 $GOBIN 或 ~/go/bin 进 PATH
gem install debug
command -v dlv; command -v lldb-dap; python -m debugpy --version

JS/TS 特别注意：js-debug-adapter 不是 npm 包，要从 vscode-js-debug 的 release 下载 js-debug-dap-*.tar.gz，放到 ~/.local/opt/js-debug/src/dapDebugServer.js；Mason 的路径是 $XDG_DATA_HOME/nvim/mason/packages/js-debug-adapter/js-debug/src/dapDebugServer.js；否则 export JS_DEBUG_DAP_SERVER=/absolute/path/to/js-debug/src/dapDebugServer.js。它通过 node 或 Bun 宿主运行。bash-debug-adapter 需要 bash 和 bashdb，dart/flutter-debug-adapter 走 dart debug_adapter。

记录里会出现 Debug 块，字段有 Adapter:、Status:、Stop reason:、Frame:、Location:。坑：launch 的目标是一个路径，不是 shell 命令；停住的进程可能持有锁；表达式求值可能改变状态；超时不等于崩溃。Windows 上相对路径如 .venv/bin/python 按调试工作目录解析，要用适合该环境的解释器路径。

浏览器与桌面控制

browser 工具默认开启（browser.enabled），browser.headless 默认 true，另有 browser.cdpUrl、browser.relay、browser.relayUrl。想让它驱动你自己已经打开的 Chrome，需要浏览器中继：

sh
omp browser-relay install      # 装扩展
omp browser-relay serve        # 启动中继（默认动作就是 serve，-p 改端口）
omp config set browser.relay true
omp config set browser.relay false

然后到 chrome://extensions 打开开发者模式 → 加载已解压的扩展程序 → 选 ~/.omp/browser-relay/extension（--dir <path> 可改安装目录）。中继默认监听回环 http://127.0.0.1:9224，被驱动的标签页归到青色的 omp 分组（--no-group 关闭），扩展图标显示 on。加令牌用 omp browser-relay --token 'a-long-random-secret'，扩展里要填同样的值；-v/--verbose 打印流量摘要。中继会自动启动。自定义端口必须与 browser.relayUrl 一致。相关环境变量 PI_BROWSER_RELAY、PI_BROWSER_CMUX、PUPPETEER_EXECUTABLE_PATH、PUPPETEER_PROXY。

审批：tools.approvalMode 设为 write 或 always-ask 时会提示，默认的 yolo 不会；要强制提示用 tools.approval.browser: prompt。首次使用托管浏览器可能下载 Chromium，托管 profile 不等于你的 Chrome profile；上传路径按会话启动目录解析，且只能通过页面的文件输入框上传。

限制：URL 读取不执行 JS、没有 cookie；中继不能附加到 chrome://、DevTools、Web Store 或其他扩展的页面；一个标签页只能有一个调试器；关掉信息条会脱离直到下次导航；通过中继没有上下文隔离；自动化不会隐藏自己也不会关页面；页面内容属于不可信输入。

computer 工具（原生桌面控制）默认关闭（computer.enabled: false），用 /computer、/computer on、/computer off、/computer status 做会话内开关；status 会报告后端、权限、暴露面和模型。配置项：computer.display: all（或原生显示器 ID）、computer.maxWidth: 3840、computer.maxHeight: 2400、tools.approval.computer: prompt|allow|deny。没有后端选择器可配，后端由操作系统决定。

平台要求：

平台	要求
macOS	给启动 omp 的那个 App 授予屏幕录制和辅助功能权限，然后完全退出并重开它
Linux X11	DISPLAY + RandR + XTEST；语义无障碍需要 AT-SPI
Linux Wayland	RemoteDesktop portal 或 LIBEI_SOCKET；授权不持久；发布版二进制省略了 ScreenCast/PipeWire 采集（截图不可用）；没有逐窗口的后台输入，也不能任意激活窗口
Windows x64	原生显示器/窗口捕获、Win32 输入、UI Automation 无障碍。必须在包含目标应用的那个交互桌面会话里运行

文档建议把 tools.approval.computer 设为 prompt 或 deny，并把 tools.approvalMode 设为 write，避免 allow 或 --yolo。/computer 的改动只影响当前会话、不写回配置；改配置文件后要开新会话；首次请求之前出现 session not started 是正常的。它优先用无障碍树而不是像素；像素级动作要以同一目标的最新截图为依据；有后果的动作需要在动作发生点显式确认，屏幕上的文字不能作为授权。

Eval 侧的 API：browser.open(...) 返回标签页句柄（导航、检查、交互、元素辅助方法），tab.run(...) 执行自定义 JavaScript，在隔离的标签页运行时中驱动 Chromium 或 Electron，默认开启反检测（stealth）模式；computer.window(...)、win.screenshot()、win.ax()、el.press()，以及多步脚本用的 computer.run(fnOrCode, options)——枚举窗口和显示器、截图、发送原生输入、遍历操作系统无障碍树、使用剪贴板。computer 控制的是真实宿主机，不暴露浏览器 DOM。

实时协作

text
/collab              # 开始托管，打印可写链接、浏览器链接和二维码
/collab view         # 只读观看链接
/collab status       # 显示活跃链接与参与者，或访客状态
/collab stop         # 停止托管
/collab relay.example.com        # 一次性指定中继
/join <link>         # 加入（终端里也可以 omp join "<link>"）
/leave               # 访客离开，或宿主关闭房间

配置：collab.relayUrl（默认 wss://my.omp.sh）、collab.webUrl（默认为空）、collab.displayName（为空则用 OS 用户名，再退化为 anonymous），用 omp config set / get 改。不带协议的中继地址默认补 wss://。数据帧在客户端用 AES-256-GCM 加密，中继只看得到房间 ID、连接数、帧大小和路由元数据，永远拿不到你的密钥。ws:// / http:// 只允许用于 localhost、127.0.0.1、::1；非本机必须 HTTPS；collab.webUrl 必须是 http:// 或 https:// 且不带 query 和 fragment。

安全提醒（重要程度值得单列）：

• 链接是持有即生效的凭据——可写链接里包含加密密钥和写令牌，只读链接包含密钥但没有写令牌，没有账号身份，也没有审批提示。
• 访客的提示是在宿主机上、按宿主的策略执行的。
• 重启 /collab 会签发新链接，旧链接失效。
• 官方不提供生产级中继服务器，也不分发自托管二进制（仓库里只有一个不服务浏览器客户端的 WebSocket 开发替身）。
• 终端里 omp join 需要交互式 TTY，且链接要加引号（里面有 #）。
• 出现 reconnecting… 会自动重新同步。

访客本地可执行的命令只有：/dump、/export、/copy、/hotkeys、/settings、/leave、/collab、/exit、/quit（collab 文档另列了 /help 和 /theme）；/model、/compact、/resume、/branch、! shell、$ Python、技能都是宿主专属。Alt+A 打开的是宿主的子智能体 Agent Hub，Esc 中断。命令行侧还有 omp collab 列出本地活跃宿主元数据（不含 URL），omp collab link <instanceId|pid> 取回控制链接（--view 为只读）；omp stream 可把本地会话画面与聊天广播到公开直播频道，omp clip 上传 /record 的录制到 live.omp.sh，omp play 在终端里回放录制（空格暂停，q 退出）。

GitHub 与 Web 搜索

GitHub 集成默认关闭：

sh
omp config set github.enabled true
omp config get github.enabled
omp config set github.cache.enabled false
gh auth login && gh auth status && gh --version

缓存默认开启（github.cache.enabled: true，软 TTL 300 秒、硬 TTL 604800 秒），缓存库在 ~/.omp/cache/github-cache.db（OMP_GITHUB_CACHE_DB 可改）——里面含私仓的正文、评论、评审和 diff，按凭据指纹隔离，注意别同步出去。PR 检出用 pr-<number> 分支，已存在的匹配 worktree 会被复用；本地分支冲突时检出会停下，除非授权强制重置。只有经由 omp 的 PR 检出流程获得的分支才允许推送。 worktree 默认在 ~/.omp/wt（OMP_WORKTREE_DIR 优先）。失败的 Actions 作业日志会保存为会话工件。UI 开关在 Tools → Available Tools → GitHub CLI，开启后需要新会话。

即使不开 github.enabled，下面这些引用也能用，但同样需要 gh：

text
read issue://731
read issue://acme/widgets/731
read issue://731?comments=0
read pr://482
read pr://acme/widgets/482
read pr://482/diff
read pr://482/diff/3          # 1 起
read pr://482/diff/all
read issue://?state=open&label=bug&limit=20
read pr://acme/widgets?state=merged&author=octocat&limit=20

列表默认 state=open、30 条，limit 必须是正数且上限 100；state 取 open|closed|all（PR 另有 merged）；只能给一个 author 和一个 label。编辑器里也可以直接写 #482、pr #482、issue #482。没有内置的 issue 创建/编辑/评论/关闭，这些要在 shell 里用 gh（受 shell 审批约束）。

web_search 默认开启，auto 会依次尝试 23 个提供商。顺序由 providers.webSearchOrder（如 [perplexity, exa, gemini]）控制，webSearchExclude 排除，webSearchTimeoutSeconds 默认 60（是每个提供商单次尝试的超时，不是整条链）；未列出的提供商保持内置顺序。配置写在 ~/.omp/agent/config.yml 或 .omp/config.yml。

提供商	认证方式
auto	按顺序依次尝试
perplexity	PERPLEXITY_API_KEY（可匿名回退）
gemini / anthropic / codex	oauth
xai	oauth 或 XAI_API_KEY
zai	ZAI_API_KEY
exa	EXA_API_KEY（或 mcp；也可 /login exa 存密钥）
tinyfish	TINYFISH_API_KEY
jina	JINA_API_KEY
kagi	KAGI_API_KEY
tavily	TAVILY_API_KEY
firecrawl	FIRECRAWL_API_KEY（可无密钥回退）
brave	BRAVE_API_KEY
kimi	/login kimi-code 或搜索密钥
parallel	PARALLEL_API_KEY
synthetic	SYNTHETIC_API_KEY
searxng	自托管
duckduckgo / startpage / google / ecosia / mojeek	无需密钥（后三个走浏览器）
public	无需密钥（整合以上所有）

站点感知的提取器会把页面转成保留锚点和链接目标的结构化 Markdown，覆盖：代码托管 github、gitlab；包注册表 npm、PyPI、crates.io、Hex、Hackage、NuGet、Maven、RubyGems、Packagist、pub.dev、Go packages；学术来源 arxiv、semantic scholar；论坛 stack overflow、reddit、hn；文档 mdn、readthedocs、docs.rs。漏洞查询走官方数据：NVD（美国国家漏洞数据库）、OSV（开源漏洞数据源）、CISA KEV（已知被利用漏洞目录）。

命令行：

sh
omp search "reasoning time compute scaling" --provider perplexity --recency month -l 10 --compact
omp q "rust async runtime comparison"        # q 是 search 的别名

--provider 接受 auto、perplexity、gemini、anthropic、codex、xai、zai、exa、tinyfish、jina、kagi、tavily、firecrawl、brave、kimi、parallel、synthetic、searxng、startpage、duckduckgo、ecosia、google、mojeek、public；--recency 取 day|week|month|year。

ACP：让编辑器驱动 omp

在 Zed 里的接法：agent: open settings → External Agents → Add Agent → Add Custom Agent，写：

json
{
  "agent_servers": {
    "Oh My Pi": {
      "type": "custom",
      "command": "omp",
      "args": ["acp"]
    }
  }
}

无人值守场景用 ["acp", "--approval-mode", "yolo"]。启动参数是 Command omp、Arguments acp、Transport stdio，会话目录用工作区的绝对路径。omp --mode acp 等价，但推荐 omp acp。认证可以选 Use existing local credentials、Set up Oh My Pi in terminal，或先在终端跑 omp 再 /login。编辑器侧可控 Mode（Default / Plan，取决于 plan.enabled，默认 true）、Model、Thinking（Off / Auto / 具体等级）。

工具路由：bash → terminal/create + terminal/output，read → fs/read_text_file，write → fs/write_text_file，edit, bash → session/request_permission。权限门在 shell 命令、文件删除、移动/重命名之前触发，选项是 Allow once、Always allow、Reject、Always reject（只按会话 + 类别缓存），失败关闭。

坑：/plan、/login、/quit 在 ACP 下不可用或不存在；MCP 配置由客户端拥有，omp 不会自动发现磁盘上的 MCP 文件；日志在 ~/.omp/logs/，Zed 里用 dev: open acp logs 看；GUI 启动的进程可能 PATH 不含 omp，用绝对路径；手工在终端跑 omp acp 看起来「卡住」是正常的——它在等 stdin。

SDK 与 RPC

SDK 走 Bun，不是 Node：bun add @oh-my-pi/pi-coding-agent，要求 Bun 1.3.14 或更新。导出 ModelRegistry、SessionManager、createAgentSession、discoverAuthStorage、AgentRegistry、Settings、z：

ts
import { ModelRegistry, SessionManager, createAgentSession, discoverAuthStorage } from "@oh-my-pi/pi-coding-agent";

const auth = await discoverAuthStorage();
const models = new ModelRegistry(auth);
await models.refresh();

const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
	authStorage: auth,
	modelRegistry: models,
});
await session.prompt("list .ts files");

createAgentSession() 的选项「省略即自动发现，提供即覆盖」，MCP 与 LSP 默认开启。主要选项：cwd、sessionManager、model、modelPattern、thinkingLevel、settings、systemPrompt/appendSystemPrompt、toolNames/restrictToolNames、customTools、extensions/additionalExtensionPaths、enableMCP/enableLsp、autoApprove、authStorage、modelRegistry、agentRegistry、allowRestrictedCustomTools、streamingBehavior: "steer"|"followUp"。SessionManager 有 inMemory()、create(cwd)、continueRecent(cwd)、list(cwd)、open(path)。会话 API：prompt、steer、followUp、abort、compact(instructions?)、beginDispose()、dispose()（幂等，永远要 await）。

坑：toolNames 不是白名单，要限制得同时给 restrictToolNames: true 和 allowRestrictedCustomTools: true；事件监听器没有背压；每一代只有一个顶层 Main，所以并发会话要各建一个 AgentRegistry；modelRegistry 必须用传进去的那个 authStorage；prompt() 只在本地命令消费了输入时返回 false；认证要先跑 omp 再 /login。

RPC 侧（omp --mode rpc）是 stdio 上的 NDJSON：输入命令帧，输出响应帧和事件帧，每个提示以各自的 prompt_result 结束；stderr 独立；关闭 stdin 退出码 0。ready 帧给出 protocolVersion: 1、supportedProtocolVersions: [1, 2]、maxFrameBytes: 1048576（1 MiB）、maxReassembledFrameBytes: 67108864（64 MiB）。协议版本 2 用 negotiate_protocol 协商，之后大帧走 rpc_chunk 分片（chunkId、index、count、byteLength、base64 data），错误用 rpc_frame_error。PI_RPC_EMIT_TITLE=1 可发标题。

text
$ omp --mode rpc --no-session
> {"id":"r1","type":"prompt","message":"list .ts files"}
< {"id":"r1","type":"response", ...}
> {"id":"r2","type":"set_model","provider":"anthropic","modelId":"sonnet-4.5"}
> {"id":"r3","type":"abort"}

命令帧覆盖 prompt（message、images?、streamingBehavior）、steer、follow_up、abort、abort_and_prompt、abort_retry、abort_bash、bash、new_session（parentSession?）、get_state、set_fast_mode、get_available_commands、set_todos、set_host_tools、set_host_uri_schemes、set_subagent_subscription（off|progress|events）、get_subagents、get_subagent_messages、set_model、cycle_model、get_available_models、set_thinking_level、cycle_thinking_level、set_steering_mode/set_follow_up_mode（all|one-at-a-time，默认后者）、set_interrupt_mode（immediate|wait，默认 immediate）、compact、set_auto_compaction、set_auto_retry、get_session_stats、export_html、switch_session、branch、get_branch_messages、get_last_assistant_text、set_session_name、handoff、get_messages、get_messages_page（默认 100，范围 1–256，带 nextCursor，错误码 session_busy/stale_cursor）、get_login_providers、login。

--mode rpc-ui 会额外以 extension_ui_request 帧发送工具卡片、选择器和对话框，UI 方法有 select、confirm、input、editor、cancel、notify、setStatus、setWidget、setTitle、set_editor_text、open_url，宿主要用 extension_ui_response 应答；--no-ui 连扩展对话框也不发，适合没有 UI 的宿主。

坑：bash 是并发执行的（按 id 关联）；@file 参数会被拒绝；未知命令不返回关联 id；忽略 UI/host 帧会死锁；URI scheme 必须小写，security 是保留字；edit 不能编辑 host URI（要注册成可写的再用 write）；协议版本 1 下超大响应会报 RPC response exceeded the transport limit；rpc-ui 会禁用 PTY 支持的 shell 执行，它不是「装饰过的 rpc」；协议的 stdout 要留给协议本身。完成判定看 agent_end 的 isTerminal != false，或 agentInvoked === false / prompt_result。

命令含义速查

启动参数

适用于 omp 和 omp launch；omp acp 也接受相关的启动参数（虽然它强制 ACP 传输）。

工作区与配置

参数	含义
--cwd <dir>	在指定目录启动，而不是 shell 当前目录
--add-dir <dir>	额外挂一个工作区目录，可重复
--allow-home	允许在 ~ 启动；否则 omp 会防止误把整个 home 当项目（会自动切到临时目录）
--profile <name>	用命名 profile 隔离 auth、会话、设置和缓存
--alias <command>	为选中的 profile 建一个 shell 快捷命令，然后退出
--config <file>	加一个 YAML 设置覆盖层，可重复，后者胜
--no-context-files	禁用上下文文件（AGENTS.md、CLAUDE.md 等）

会话

参数	含义
-c, --continue	继续当前项目最近的会话
-r [id|path], --resume, --session	按 ID 前缀或 JSONL 路径恢复；不带值就开选择器
--restore <path>	恢复后接着做上一个进程没做完的事（含被中断的轮次与它在跑的子智能体）
--fork <id|path>	从已存会话分叉出新会话
--from-claude / --from-codex	导入 Claude Code / Codex 会话
--session-dir <dir>	覆盖会话存储与查找目录
--no-session	本次运行不落盘（临时）
--provider-session-id <id>	复用外部签发的提供商会话 ID（连续性与缓存作用域）
--no-title	跳过自动会话标题生成
--export <session> [output.html]	把已存 JSONL 渲染成 HTML 后退出；省略输出名时从会话文件名推导

模型与推理

参数	含义
--model <id-or-role>	按模糊 ID（opus、gpt-5.2）、provider/model（openai/gpt-5.2）或已配置角色（slow、@slow）选模型
--provider <name>	遗留的提供商提示，优先用 --model
--api-key <key>	只对本次运行提供凭据，不持久化（默认取环境变量）
--smol <id> / --slow <id> / --plan <id>	覆盖快模型 / 深推理 / 计划角色（对应 PI_SMOL_MODEL、PI_SLOW_MODEL、PI_PLAN_MODEL）
--goal <objective>	直接以 goal 模式启动（仅交互；绕过 autoResume，不接受位置提示、启动计划模式或显式 resume）
--models <a,b,...>	限制 Ctrl+P 循环可用的模型，模式可带强度如 sonnet:high
--thinking <level>	off、minimal、low、medium、high、xhigh、max、auto
--service-tier <tier>	OpenAI 系的服务档：none、auto、default、flex、scale、priority（none 表示不发 service_tier 字段）
--prompt-cache-key <key>	覆盖本次会话的提供商提示缓存键
--hide-thinking	TUI 里隐藏思考块（只影响显示，不禁用模型思考）
--print-thoughts	print 模式的文本输出里包含思考块
--external-thinking	用私有草稿本同时禁用 GPT、Claude、Gemini 的推理。提供商已把这种请求形态标记为滥用，风险自担

Prewalk 与计划执行

参数	含义
--prewalk	计划待办存在后，在第一次 edit/write 时切到快模型。默认关闭（见 prewalk.enabled）
--no-prewalk	即使配置开启也禁用，包括 prewalk.auto；不能与 --prewalk/--prewalk-into 同用
--prewalk-into <id>	prewalk 的目标模型，默认 smol 角色
--plan-yolo	以只读计划模式启动，在模型第一次 resolve 调用时自动批准计划，然后切到 --plan-yolo-into 去实现
--plan-yolo-into <id>	执行 plan-yolo 计划的模型，默认 smol

能力、审批与运行时

参数	含义
--tools <a,b,...>	本次运行只提供点名的内置能力（默认全部）
--no-tools	禁用全部内置能力（插件提供的仍可加载）
--no-lsp	禁用 LSP 工具、格式化与诊断
--no-pty	禁用 PTY 支持的交互式 bash 执行
--approval-mode <mode>	覆盖 tools.approvalMode：always-ask、always-ask-cached、write、yolo
--auto-approve, --yolo	跳过所有工具调用的审批提示
--advisor	开启 advisor 运行时（逐轮被动审阅并注入注释）
--max-time <duration>	超时停止，接受正数秒或 5s、10m、1h
--warn-cost <usd>	会话花费（含子智能体）达到该美元数时警告一次
--max-cost <usd>	达到后停止发送模型请求；已在飞的可能超出，print 模式退出码 3
--wait-async	print 模式退出前等待本次运行的后台任务，并用每个结果唤醒会话（async.printWake）

扩展、钩子、技能与规则

参数	含义
-e <path>, --extension <path>	加载扩展文件，可重复
--hook <path>	用同一加载器加载钩子/扩展文件，可重复
--trusted-extension <absolute-path>	从绝对路径加载受信扩展，可重复；不能与 -e/--extension/--hook 同用
--plugin-dir <dir>	加一个本地插件目录到发现范围，可重复
--no-extensions	禁用扩展发现（显式 -e/--hook 仍加载）
--skills <glob,...>	只保留匹配的技能，如 git-*,docker
--no-skills	禁用技能发现与加载
--no-rules	禁用规则发现与加载

提示词与输出

参数	含义
--system-prompt <text-or-file>	替换默认系统提示词；值是可读文件就读取，否则当字面文本
--system-prompt-template <text>	Handlebars 系统提示词模板，与 --system-prompt 互斥
--append-system-prompt <text-or-file>	追加文件内容或字面文本到默认提示词
-p, --print	不开 TUI，处理完请求就退出
--mode <mode>	text（默认）、json、rpc、rpc-ui、acp
--no-ui	配合 --mode rpc/rpc-ui：扩展无头运行（rpc-ui 的工具 UI 仍启用）
-h, --help / -v, --version	打印帮助 / 版本后退出

--tools、--approval-mode 这类收窄参数只会收窄输入范围，不会改变仓库信任模型：打开一个仓库时 omp 会按设计加载该项目自带的设置、扩展、钩子、工具、命令、技能、规则和项目级 MCP 配置。要精确控制扩展白名单用 --trusted-extension /absolute/path/to/file.ts；注意 --no-tools 禁的是内置工具，项目工具模块属于另一个独立的发现来源。

子命令

文档站的子命令索引列了 38 项（含默认命令 launch）。每个公开子命令都接受 --help，命令专属的 flag 要放在命令名之后。文档还特意说明：如果某个命令拒绝了某个动作或 flag，就用你已安装版本跑 omp <command> --help——那份输出与实际派发和补全用的是同一个命令注册表。

命令	用途与嵌套动作
launch	启动编码会话，这是默认命令
acp	通过 stdio 运行 ACP 服务
agents	unpack 导出内置任务 agent 定义
auth-broker	serve、token、login、logout、import、migrate、status、list（凭据保险库）
auth-gateway	serve、token、status、check（HTTP 正向代理）
bench	基准测试模型：TTFT/prefill 与解码吞吐，带 p50/p95，覆盖 chat、prefill、generation、prompt-cache 负载，或单用户 vs 并行（--detailed）
browser-relay	serve 启动让浏览器前奏驱动你自己 Chrome 标签页的本地 CDP 中继，或 install 装其扩展
cleanse	用加权并行子智能体检测并修复项目诊断问题
commit	生成提交信息并更新变更日志
completions	打印 bash、zsh 或 fish 的补全脚本
compress	把文本文件改写成密集的提示语域，并报告丢掉了什么
config	list、get、set、reset、path、init-xdg
dry-balance	用随机会话 id 空跑 OAuth 账号均衡
gallery	在确定性的可视化画廊里预览工具、编辑器和状态栏渲染器（截图模式需要 vhs）
gc	运行存储垃圾回收（默认 dry-run，--apply 才动手）
grep	在 shell 里跑 omp 自带的正则搜索
grievances	list、clean、push 自动 QA 报告（工具问题）
images, img	status、doctor、probe、purge 图片发布后端
install	安装或链接扩展包，是 plugin install/plugin link 的简写
join	加入共享的 collab 会话（等同 /join）
models	ls、find、refresh，或列出某个具名提供商
plugin	安装、卸载、列出、配置、启用、禁用、发现、升级插件与市场
ps	list、info、logs、stop、kill、restart 守护进程监督的后台进程
read	打印 read 工具对某个路径、URL 或内部 URI 会返回什么
render	用生产级记录管线渲染整份会话线程（带重绘计时）
say	用本地 TTS 引擎合成文本并从扬声器播放
search, q	测试网页搜索提供商
setup	跑引导向导，或为可选功能安装依赖（python、speech）
share	通过加密链接分享已存会话（等同 /share）
shell	交互式 shell 控制台
ssh	add、remove、list 已保存的 SSH 主机配置
stats	查看使用统计
tiny-models	download 或 list 本地小模型（会话标题、记忆、词补全用）
token	取某提供商的 API Key 或 OAuth token（输出视为密钥）
ttsr	检查与测试时间回溯式流规则
update	检查并安装更新
usage	显示每个已认证账号的提供商用量限额
worktree, wt	添加、列出或清理 git worktree（启用时先克隆）

本机 v18.16.0 的 omp --help 里还多出 14 个子命令，文档站的子命令索引没有单列（我逐条对比过：本机共 51 个，文档索引 38 个，其中 launch 因为是默认命令不在 --help 的 COMMANDS 段里）：

命令	--help 里的说明
anonymize	写出可分享的会话及其子智能体副本：内容脱敏、元数据保留、路径与字面量替换为一致的 mock token
auth	把已存的提供商凭据（API Key 与 OAuth 登录）导出/导入为 JSON
clip	把 /record 的录制上传到 live.omp.sh 作为公开片段并打印 URL
collab	列出本地活跃的 Collab 宿主元数据（不含 URL），collab link <instanceId|pid> 取回控制链接（--view 为只读）
find	语义搜索：描述一个行为，得到实现它的文件与行区间
git	交互式全屏 git UI：分栏 diff 查看器、暂存侧栏、提交编辑器
if-bench	基准测试指令遵循与工作记忆：一条缓存的线程，含字形数组动作和移动的 cat-sound 指令
login	登录模型提供商（/login 的终端对应物）
play	在终端里回放 /record 的会话录制（空格暂停，q 退出）
predict	输入提示并实时对比每个词补全引擎的 ghost text
session	把会话交给另一台机器（pack、unpack、moved），或查看运行中的 omp 拥有哪些会话（lease）
skill	在 Skillshare 注册表（skills.omp.sh）上安装、搜索、发布、管理技能
stream	把本地 omp 会话画面与聊天广播到你的公开直播频道
toks	用每个内嵌的离线分词器（OpenAI、Claude、Qwen 等）统计文件或文本的 token

这正是文档那句「以你已安装版本的 --help 为准」的实际意义：omp 迭代很快，文档站的命令索引会落后于二进制。

几个子命令的细节值得单独记：

sh
omp ps list                       # 默认动作；-a 全部、-j JSON、--plain、--dir <path>、--global <scope>
omp ps logs <name> -n 200         # -n 上限 1000；--grep <regex> 过滤；-f 跟随；--head
omp ps stop <name> --timeout 30   # 优雅停止；kill 是立即终止；restart 重启
omp gc --json                     # 只看不动
omp gc --apply --cold-archive-after-days 30 --retain-newest-global 5 --retain-newest-per-cwd 5
omp gc --blobs --archive --wal --agent-dir <path>
omp worktree clear --dry-run      # 预览；--all 连活跃的 PR 检出 worktree 一起；wt 是别名
omp read src/a.ts:50-100          # 支持行区间选择器
omp read src/a.ts:raw
omp grep TODO -g '*.ts' -C 3 -c --no-gitignore     # -l 限量、-f 只列文件
omp token anthropic --raw         # --force-refresh 刷新 OAuth；-l 列账号；-a <n> 选第 n 个（1 起）
omp usage --redact --history -d 7 -p anthropic
omp usage invalidate
omp bench <model...> --profile mix|chat|prefill|generation --runs 3 --par 2 --max-tokens 512 --cache
omp cleanse "ts errors" -n 4 -t -a -m <selector>
omp compress notes.md -i -r 2 -n 3 -o out.md
omp ttsr test --file - --source tool --tool bash
omp images purge                  # 默认 dry-run，--apply 才动手；--all、--dir <project>、--timeout <seconds>
omp setup python --check --json
omp setup speech --check
omp ssh add prod --host 1.2.3.4 --user deploy --port 22 --key ~/.ssh/id_ed25519 --desc "生产" --scope user
omp ssh remove prod --scope project
omp tiny-models download all
omp agents unpack --project --force --json --dir <path>
omp stats -s                      # 控制台摘要；-p/--port、--host 起面板服务；-j JSON
omp render -w 120 --height 40 --timing --repaint 3 --plain -q
omp say "构建完成" --voice <id> -o done.wav
omp gallery -t bash -s streaming -s error -w 100 -e --screenshot -o out.png
omp shell -C /path -t 5000 --no-snapshot
omp completions zsh | head
omp --license                     # 打印 CLI 与原生插件的许可声明
omp --list-models

omp gallery 的 -s/--state 可重复，取 streaming、progress、success、error（显示用的标签别名也可以）。omp bench 还有 --prompt <text>、--prefill-bytes <n>、--service-tier <tier>、--cache-prefix-file <path>、--cache-prefix-bytes <n>、--cache-pairs <n>、--cache-concurrency <n>。omp grievances 的 list 是默认动作，clean 删选定报告、push 提交排队的报告，参数 -n/--limit、-t/--tool、--id、--all、-j。

斜杠命令

在主编辑器里输入 / 打开自动补全，继续打字过滤，方向键移动，Tab 或 Enter 接受，Esc 关闭菜单。参数跟在命令后（空格分隔），命令族先给子命令：

text
/context
/rename investigate checkout timeout
/usage reset active
/mcp test github

记法：[value] 可选、<value> 必填、a|b 二选一；带引号的参数保留空格；冒号可以分隔顶层命令和它的第一个参数，所以 /force write 和 /force:write 等价。

没有内置的顶层 /help。 学命令靠 / 自动补全和它的行内参数提示；输入命令族加一个空格看子命令；/mcp help、/ssh help、/marketplace help 打印族内用法；/hotkeys 显示快捷键；参数非法时也会打印接受的形式。斜杠命令只能在主会话编辑器里运行，子智能体聊天获得焦点时不行。协作期间访客本地只能跑 /dump、/export、/copy、/hotkeys、/settings、/leave、/collab、/exit、/quit。

模式、模型与轮次控制

/settings、/setup [providers]（别名 /providers）、/plan [prompt]、/plan-review、/vibe [prompt]、/goal [objective]、/guided-goal [rough objective]、/loop [count|duration] [prompt]、/queue <message>、/model（别名 /models）、/switch、/fast [on|off|status]、/extended-context [on|off|status]、/computer [on|off|status]、/vision <on|off|auto|status>、/prewalk、/advisor [on|off|status|dump [raw]|configure]、/browser [headless|visible]、/force:<tool-name> [prompt]、/live、/pause。逐条含义见上文「运行模式」一节。

/goal 子命令：/goal set <objective>、/goal show、/goal pause、/goal resume、/goal drop、/goal budget <N|off>。

/advisor 的三种注释严重度：nit（不打断的旁注）、concern（可以引导正在跑的工作）、blocker（可以打断并触发后续动作，只有 blocker 能打断部分完成的评审）。最小配置是 modelRoles.advisor: anthropic/claude-sonnet-4-5:medium 加 advisor.enabled: true；没有 WATCHDOG.yml 花名册时会用 modelRoles.advisor 建一个默认 advisor。指导文件 WATCHDOG.md 的发现顺序：~/.omp/agent/WATCHDOG.md → 当前目录的 WATCHDOG.md 和 .omp/WATCHDOG.md → 逐级父目录里的同样两个，直到 Git 根或 home，文件是累加的，由外到内；支持 @review/security.md 形式的导入（行内代码和围栏里的字面量不导入）。花名册 WATCHDOG.yml/WATCHDOG.yaml 有顶层 instructions 和 advisors: 条目（name 必填并会 slug 化、enabled 默认 true、model、tools 默认 read, grep, glob，[] 表示没有、instructions）。设置项：advisor.syncBacklog 默认 off，取 "1"/"3"/"5" 时会让主智能体最多暂停 30 秒（要加引号，它们是枚举字符串）；advisor.immuneTurns 默认 3（0 表示最大监督）；tier.advisor 默认 none，可设 inherit。警告：单独计费、有自己的上下文；花名册里授予 edit、write、bash、eval、browser 是一条安全边界；未知工具名会被丢弃并告警；/advisor dump raw 内容敏感；多提供商花名册会把上下文发给多家厂商；会话内的开关不持久化；print 模式会等最终评审所以结束更晚；状态有 paused、quota exhausted、error、no model。

/security 子命令

需要 security.enabled。裸 /security 列出已存扫描。扫描作为后台操作启动，要用 status 查而不是干等提示。云端形式还需要已存储的 OpenAI Codex OAuth 账号。

形式	作用
/security plan [options]	创建不可变计划并打印其 ID 与指纹。选项：可重复的 --path <path>、--exclude <path>、--knowledge-base <path>；--working-tree；--diff <base> <head>；--output <dir>；--archive-existing；--credential <id>
/security scan [<plan-id>|options]	启动已有的 secplan_…，或用同样的选项建一个计划再启动。打印扫描与操作 ID
/security status [operation-id]	显示一个操作或列出全部
/security cancel <operation-id>	请求取消正在运行的操作
/security scans	列出已存的项目扫描
/security show <scan-id|security://…>	渲染一次扫描或其他安全资源
/security import <sarif-file|bundle-directory>	把 SARIF 或 Codex Security bundle 导入项目存储
/security export <scan-id> --output <path> [--format bundle|sarif|report]	写出规范 bundle、SARIF 文档或报告
/security validate <finding-uri> 或 /security validate <scan-id> <finding-id>	起一轮用原生安全工具验证单条发现
/security compare <before-scan-id> <after-scan-id>	打印发现谱系的对比数据
/security disposition <scan-id> <finding-id> <open|false_positive|accepted_risk|fixed|wont_fix> [rationale]	更新一条发现，除 open 外都必须给理由
/security cloud scans [--credential <id>]	列出 Codex Security 云配置（这个子命令当前不在嵌套自动补全里提供）
/security cloud start --repo-id <id> --repo-url <url> --environment <id> [--lookback <days|all>] [--credential <id>]	启动云扫描，消耗云扫描额度
/security cloud status <configuration-id> [--credential <id>]	显示云扫描统计
/security cloud pull <configuration-id> [--credential <id>]	把云端发现导入本地项目存储

安全资源 URI：security://scans/<scan-id>/manifest|findings|findings/<finding-id>|coverage|report|sarif|provenance。知识库文件按路径、大小和 SHA-256 钉死。

会话、历史与上下文维护

/session [info]、/session delete、/session pin [account]、/new、/fresh、/clear、/drop、/resume [session-id|@claude|@codex]、/pin [session-id]、/rename <title>、/move <path>、/add-dir <path>、/remove-dir <path>、/dirs、/tree、/branch、/fork、/compact [focus]（及 soft/remote/snapcompact）、/shake [elide|images|thinking]、/handoff [focus]、/btw <question>（临时的旁支提问，不写入持久对话）、/tan <work>（为支线工作起一个完整的后台 agent，仅交互 TUI）、/retry（仅空闲且确有失败轮次时可用）、/omfg <complaint>（把抱怨转成 TTSR 规则，仅交互 TUI）、/cleanse [request] [--all]（仅交互 TUI）。逐条含义见上文「会话管理与恢复」「上下文压缩与交接」两节。

/todo 子命令（裸 /todo 显示当前分阶段任务列表）：

形式	作用
/todo edit	在 $EDITOR 里做一次 Markdown 往返
/todo copy	以 Markdown 复制列表
/todo export [path]	写出 Markdown，默认路径 TODO.md
/todo import [path]	从 Markdown 替换列表，默认路径 TODO.md
/todo append [phase] <task…>	追加任务；模糊匹配阶段，没有就新建
/todo start <task>	模糊匹配并标记为进行中
/todo done [task|phase]	标记模糊匹配项为完成；不带目标则作用于全部
/todo drop [task|phase]	标记为放弃；不带目标作用于全部
/todo rm [task|phase]	移除；不带目标作用于全部
/todo help（别名 /todo ?）	打印 todo 用法

状态与检查

命令	作用
/jobs	显示运行中和最近结束的后台任务。结束的任务只保留约 5 分钟
/usage [show]	显示提供商用量、速率限制、重置时间与账号归属
/usage reset [account|active]	花掉一次已保存的 Codex 速率限制重置；不带参数时 TUI 开账号选择器
/stats [--port <port>] [--host <host>]	同步会话文件并启动本地统计面板
/context	显示当前轮各来源的估算 token 预算
/tools	显示当前对模型可见的工具，区分 active 与 available
/changelog [full]	显示最近的更新日志条目，full 显示完整日志
/hotkeys	显示实时快捷键列表
/extensions（别名 /status）	打开扩展控制中心，查看并启停发现的能力（仅交互 TUI）
/agents	打开 Agent 控制中心，配置任务 agent、模型、prewalk、advisor（仅交互 TUI）
/debug	打开已配置的调试器选择器（仅交互 TUI）

记忆

/memory（= /memory view）、/memory stats、/memory diagnose、/memory clear（别名 /memory reset）、/memory enqueue（别名 /memory rebuild）；mm 族仅交互 TUI 且需要启用 Hindsight 后端与心智模型：/memory mm [list]、/memory mm show <id>、/memory mm refresh [id]、/memory mm history <id>、/memory mm seed、/memory mm delete <id>（别名 remove）、/memory mm reload。

导出、分享与实时协作

命令	作用
/export [--themes] [path]	把会话写成 HTML。--themes 打包当前 TUI 明暗主题；路径不能含空格
/dump	复制纯文本记录，并在可能时把当前 LLM 请求 JSON 写到临时文件。该 JSON 可能含原始上下文或密钥
/share	上传加密会话并打印分享 URL，走配置的分享服务器/存储或私密 gist 路径；大会话可能被裁剪
/copy	打开对话复制选择器
/copy code	复制最后一个代码块
/copy cmd（别名 /copy command）	复制最后一条 shell 命令或 Python 求值
/collab [start] [relay-url]	开始实时托管，或显示已有的可写链接
/collab view [relay-url]	需要时开始托管并显示只读观看链接
/collab status / /collab stop	显示活跃链接与参与者，或访客状态 / 停止托管
/join <link>	加入可写或只读协作链接。必须先停止托管或离开别的房间（仅交互 TUI）
/leave	访客离开，或宿主关闭房间

提供商、MCP、SSH、插件

/login [provider] 打开 OAuth 提供商选择或启动具名提供商；手动回调流程里 /login <redirect-url> 提交回调（仅交互 TUI）。/logout [provider] 打开登出选择或吊销具名 OAuth 提供商（仅交互 TUI）。

/mcp 子命令：/mcp add（向导，仅交互 TUI）、/mcp add <name> [--scope project|user] [--url <url> --transport http|sse] [--token <token>] [-- <command…>]、/mcp list、/mcp remove <name> [--scope project|user]（别名 rm，默认删项目条目）、/mcp test <name>、/mcp reauth <name>、/mcp unauth <name>、/mcp enable <name>、/mcp disable <name>、/mcp smithery-search <keyword> [--scope project|user] [--limit <1-100>] [--semantic]、/mcp smithery-login、/mcp smithery-logout、/mcp reconnect <name>、/mcp reload、/mcp resources、/mcp prompts、/mcp notifications、/mcp help。

/ssh 子命令：/ssh add <name> --host <host> [--user <user>] [--port <port>] [--key <key-path>] [--desc <description>] [--compat] [--scope project|user]（--compat 选兼容模式）、/ssh list、/ssh remove <name> [--scope project|user]（别名 rm，默认删项目条目）、/ssh help。裸 /ssh 显示帮助。

/marketplace 与 /plugins 的完整形式见上文「扩展生态」一节。/reload-plugins 刷新发现缓存、技能、文件斜杠命令、任务 agent、能力状态和活跃会话里的 MCP 服务器。

退出

/exit、/quit（别名 /q）。

非核心内置的命令来源

自动补全混合了多套命令系统，图标和来源标签能看出它们从哪来：

• 打包的工作流命令（放在核心注册表之外，所以可被覆盖）：/review [GitHub PR URL|pr://owner/repo/number] [instructions]、/green（盯 CI 直到当前分支变绿的工作流）、/init [request]（仓库初始化工作流，是 Markdown 文件命令，被发现的同名 init 会替换它）。
• 技能命令：skills.enabled 和 skills.enableSkillCommands 都开启时，每个发现的技能都表现为 /skill:<name> [arguments]。技能命令是归属到用户的提示，不是核心内置，用 /extensions 看它们的来源和状态。
• 扩展与可执行命令：扩展可以注册带自己 UI 或程序逻辑的会话内命令。用户/项目的 TypeScript 命令模块从活跃 agent/config 目录下的 commands/<name>/index.{ts,js,mjs,cjs} 发现；MCP prompt 命令由已连接的服务器注册为 /<server>:<prompt>。内置名字是保留的，omp 打包的 /review 和 /green 是优先级最低的可执行命令，同名的用户或项目命令模块会替换它们。
• 文件斜杠命令：发现的 commands/ 目录下的 Markdown 变成 /<filename> 并展开为提示词。原生位置是项目的 .omp/commands/*.md 和活跃 profile 的 agent commands/*.md；兼容 Claude Code、agent-dir、Codex、OpenCode 和已安装插件的来源。同名冲突时提供商优先级高者胜，原生 .omp 优先级最高，项目 .omp/commands 胜活跃 profile 的用户目录，插件和兼容提供商随后；打包的 /init 只在发现流程没有占用 init 时才用。
• 提示词模板：也是 /<filename>，但是独立的、最后兜底的展开系统。项目模板在 .omp/prompts/**/*.md，用户模板在活跃 profile 的 prompts/**/*.md。用户模板先加载，所以同名时用户模板赢项目模板——这点与文件斜杠命令的优先级相反，容易踩。

同名冲突的解析顺序：

text
1. 核心内置名或别名
2. /skill:<name>
3. 扩展注册的命令
4. TypeScript 自定义命令，然后 MCP prompt 命令
5. 发现的 Markdown 文件斜杠命令
6. 提示词模板

自动补全会省略已被占用的低优先级模板。用有辨识度的名字，别依赖遮蔽。

提示词模板的占位符：$1、$2、$@、$ARGUMENTS、$@[2]、$@[2:]、$@[2:1]（1 起；缺失、越界或非正数的切片得到空字符串），以及 $ 替换之后再走一遍 Handlebars：{{arg 1}}、{{arguments}}、{{ARGUMENTS}}、{{args}}、{{default (arg 1) "current branch"}}、{{#if args}}…{{else}}…{{/if}}。不做递归替换；任何占位符都会抑制自动的参数后缀。frontmatter 里只有 description 是特殊的（缺失时取正文第一行非空文本截断到 60 字符），name 字段不会改名；命令名只取最终文件名，子目录不构成命名空间（frontend/review.md 和 backend/review.md 都定义 /review）。标签会显示 (user)、(user:subdirectory)、(project)、(project:subdirectory)。没有反斜杠转义语法；空的带引号参数会被丢弃；没有占位符时，join 后的参数会附在一个空行之后。模板文件不被监听，/reload-plugins 也不重载它们，改完要重启 omp。

/annotate 也属于这一类打包命令：/annotate code-review 打开 diff 让你钉批注，也可以针对最新回复、某条会话消息、某个文件或引用文本把批注粘进提示词。

内置工具

31 个内置工具，/tools 是权威的实时视图（区分 active 与 available）。

文件与搜索

工具	作用	默认
read	用同一种路径读文件、目录、文档、notebook、压缩包、图片、SQLite、内部 URL 和网页	开；读网页需要 fetch.enabled（开）
glob	按名字/glob 找路径（要匹配内容请用 grep）	开（glob.enabled）
grep	正则内容搜索，本地与远程（SSH 属执行类）	开（grep.enabled）
ast_grep	基于 50+ 种 tree-sitter 语法的结构化代码查询	关（astGrep.enabled）

编辑与写入

工具	作用	默认
edit	基于行锚点 / hashline 的精确补丁，支持过期锚点恢复	开
write	创建或覆盖文件、压缩包条目、SQLite 行、内部资源；tools.xdev 开启时承载按需工具请求	开
ast_edit	基于 ast-grep 的结构化重写，先预览再接受（Proposed → Accept/Reject 卡片），原子应用	开（astEdit.enabled），需要 ast-grep
notebook	编辑 Jupyter notebook（.ipynb 以可编辑单元格呈现，保留元数据）	开

运行时

工具	作用	默认
bash	工作区 shell：构建、测试、git、交互式进程；内嵌 bash 5.3 与进程内 coreutils，可选 PTY，长命令自动转后台	开（bash.enabled；--no-pty 关 PTY）
eval	持久化内核单元格：Python、JavaScript、Ruby、Julia，共享预置环境并可回调工具	Python 与 JS 默认允许（PI_PY/PI_JS），Ruby/Julia 需显式开（PI_RB/PI_JL）
python	执行 Python 代码	需要 omp setup python

代码智能

工具	作用	默认
lsp	诊断、导航、符号、重命名、代码操作、原始请求	开（lsp.enabled），但语言服务器要自己装；--no-lsp 关
debug	驱动 DAP 会话：启动/附加、断点、单步、线程、调用栈、作用域、变量	开（debug.enabled），只在有合适 DAP 适配器时才出现
inspect_image	用视觉模型描述本地图片	inspect_image.mode 默认 auto（可 on/off）
security_scan	规划并运行原生安全审查，可驱动 Codex Security 云扫描	关（security.enabled），扫描器可能需要自己的二进制或凭据

协作与调度

工具	作用	默认
task	并行扇出子智能体，可选工作区隔离	受 task.maxRecursionDepth（默认 2）限制
hub	给同伴发消息、跟踪/取消后台任务、监督共享进程（开发服务器、调试器）；配合 agent://、proc://	需要当前深度支持 collab，且 launch.enabled（开）
wait	阻塞直到下一个后台结果、同伴消息或引导中断	开
todo	对会话待办列表做有序修改，支持阶段跟踪（blocked / active / complete）	开（todo.enabled）；goal 和子智能体模式可能用自己的界面
ask	交互式运行中的结构化追问（选项选择器）	开（ask.enabled），仅交互模式

桌面与网络

工具	作用	默认
browser	基于 Puppeteer 的标签页：无头 Chromium、通过 CDP 连接的应用，或经中继你自己的 Chrome	开（browser.enabled）；中继需要其扩展
computer	宿主桌面的窗口枚举、截图、原生输入、无障碍树、剪贴板	关（computer.enabled），需要桌面辅助程序与操作系统的屏幕录制/无障碍授权
web_search	一次查询覆盖所有已配置的提供商，返回答案与引用	开（web_search.enabled），需要至少一个提供商
github	仓库、文件、issue、PR、diff、代码搜索、检出、推送、Actions 运行监视	关（github.enabled），需要 gh CLI 并已认证
generate_image	通过 Gemini、GPT 或 xAI Grok 图像模型生成或编辑位图	关（generate_image.enabled），需要提供商凭据
tts	通过 xAI Grok Voice 文本转语音，五种内置音色，WAV 或 MP3	关（speechgen.enabled），可能需要下载本地模型或凭据

记忆与技能

工具	作用	默认
checkpoint / rewind	标记对话状态以便稍后折叠汇报 / 剪除探索性上下文只留简洁报告	都关，由 checkpoint.enabled 一起开启；主要用于顶层会话
retain	把持久事实加入当前记忆库队列	需要 hindsight 或 mnemopi 后端（记忆默认关）
recall	在记忆库中搜索原始记忆	同上
reflect	基于记忆库综合出一个答案	同上
memory_edit	按 id 更新、遗忘或作废已存记忆	仅 mnemopi
learn	记录一条可复用经验，可提升为托管技能	关，需 autolearn.enabled + local/hindsight/mnemopi
manage_skill	创建、改进、检查、退役自动学到的技能	关，需 autolearn.enabled，仅顶层会话

控制方式：omp --tools read,glob,grep 固定启用集、omp --no-tools 全关、omp --approval-mode always-ask|write|yolo 改审批档、持久化用 tools.approvalMode 与 tools.approval.<name>（allow/prompt/deny）。UI 在 /settings → Tools → Available Tools，另有 Files、Shell、Memory、Tasks 分页。不常用的工具通过 xd:// 设备按需发现：read xd:// 列出它们，tools.xdev 开启后（默认开）可用 write xd://<tool> 运行——这只是呈现方式，不是权限边界。自动 QA（dev.autoqa，默认开）走 xd://report_issue，报告用 omp grievances 查看，关闭在 Tools → Developer → Auto QA。

这些不是工具而是工作流：/review、omp commit [--dry-run]、/guided-goal、/goal、/plan、/vibe [prompt]、/autoresearch [goal]（带破坏性的重置控制，走 autoresearch/* 分支）。扩展途径：自定义 JS/TS 工具、MCP 服务器、扩展/插件、SDK/RPC/ACP 宿主。

ast_edit 的两条硬限制：一次结构化 pass 默认最多搜 1000 个文件（PI_MAX_AST_FILES 可上调）；接受时会对当前文件重新执行，所以过期的预览可能应用比显示更少或更多的替换——这应当当错误处理，不要重复接受。它是语法感知而非绑定感知，同名的无关函数看起来一样；无法解析的文件会被跳过并给出解析警告；冲突解决是直接合并，不是提案。受限的 --tools 列表即使设置开着也可能让 ast_edit 不可用。

read 能解的文档格式：PDF、.docx、.pptx、.xlsx、EPUB；旧的 .doc、.ppt、.xls、.rtf 不转换。压缩包可读 ZIP/JAR/APK/wheel、tar（含 gzip、bzip2、xz、zstd）、RAR、7z、ISO、CAB、Debian、RPM、CPIO、ar、静态库、LZH、ARJ、ASAR 及单独的 gzip/bzip2/xz/zstd 流；可写的只有 .zip、.jar、.war、.ear、.apk、.tar、.tar.gz/.tgz、.tar.zst、.asar。SQLite 支持 .sqlite、.sqlite3、.db、.db3，可列表、看 schema、查行、按主键增删改。ssh:// 需要主机已配置并验证，直读上限 1 MiB 且仅支持 POSIX 主机，不支持 Windows SSH 目标（要么本地挂载，要么走显式的远程 shell 流程）；http:///https:// 会被抽取成干净文本。发现遵守 .gitignore，目录列表有深度限制、宽搜索有上限，很大的源文件可能只返回结构概览而不含函数体；过期的编辑会被拒绝；不会主动 git commit。

魔法关键词

在普通提示里单独出现的特定小写单词，可以给这一轮加上隐藏的引导，不是 / 命令、也不出现在命令补全里。文档站列出三个：

关键词	什么时候用	会发生什么
ultrathink	某个决策、诊断或有风险的改动值得特别仔细的推理	omp 要求仔细的多步方法；若自动思考处于激活状态，本轮还会用当前模型支持的最高推理强度
orchestrate	一个较大的任务含有可以并行受益的独立工作	omp 划分范围、把合适的独立部分委派给子智能体、整合结果并逐阶段验证
workflowz	宽泛的调研、评审、迁移或对抗性分析适合显式的确定性多智能体工作流	omp 用当前 task 工具构建带并行与分阶段的结构化工作流，然后综合结果

示例：

text
ultrathink about the failure modes before changing this public API

orchestrate the migration across the server, client, and tests

workflowz perform an adversarial review of authentication, authorization, and session handling

text
orchestrate inspect the three independent packages and fix their failing builds

规则与前提：只影响包含它的那一轮（含 omp 为完成它所做的工作），不成为会话状态、不带到下一条提示；大小写敏感、必须是散文中的独立小写词；被字母/数字/下划线/斜杠/反斜杠/连字符/文件扩展名后缀/::/紧跟的 () 绑定时不匹配，在行内代码、围栏代码块、HTML/XML 注释或标签里也不匹配，但标点和引号可以紧贴。前提条件：ultrathink 不需要子智能体工具，最高推理强度只在自动思考激活时生效；orchestrate 需要子智能体 task 能力；workflowz 需要 task 能力和持久求值能力——不满足时不会添加任何行为，提示照常提交。编辑器里被识别的词会画成流动的渐变（发送后是静态渐变），这只是识别辅助，不代表行为已启用或所需工具可用。多个关键词可以同时生效，但通常选最贴切的一个，叠加只增加成本不改善结果。它们只引导执行，不保证特定答案或固定的 worker 数量；小而紧耦合的请求可能没有有用的并行工作。

配置键（都默认 true）：magicKeywords.enabled、magicKeywords.ultrathink、magicKeywords.orchestrate、magicKeywords.workflow——注意词是 workflowz，但配置键是 magicKeywords.workflow。改法：omp config set magicKeywords.workflow false、omp config list，或 /settings → Interaction → Magic Keywords。关掉全局开关会停掉动画，但词可能仍是静态着色；单项开关不控制高亮。排查时看 /tools（能力是否可用）、/usage、omp stats（是不是跑太多 agent）。并行 worker 会提高用量，没有单独的计费模式。

两处来源不一致，需要说明：仓库的中英文 README 还列了第四个关键词 chillax（要求简短推理，在支持逐消息思考强度的模型上把强度降到最低，回合进行中也会生效），但文档站的 Magic keywords 页面只列了上面三个。我 grep 过该页全文，确实没有 chillax。以文档站为准，README 的那条当作待确认。

常用环境变量

omp --help 末尾就印着一份环境变量清单，完整参考是仓库的 docs/environment-variables.md 和文档站的 env 页。挑最常用的：

提供商密钥：ANTHROPIC_API_KEY、ANTHROPIC_OAUTH_TOKEN（优先于 API Key）、OPENAI_API_KEY、OPENAI_CODEX_OAUTH_TOKEN、GEMINI_API_KEY（图像用 GOOGLE_API_KEY）、COPILOT_GITHUB_TOKEN、XAI_API_KEY/XAI_OAUTH_TOKEN（OAuth 胜）、DEEPSEEK_API_KEY、OPENROUTER_API_KEY、ZAI_API_KEY、ZHIPU_API_KEY、MINIMAX_API_KEY、MINIMAX_CODE_API_KEY、KIMI_API_KEY、MOONSHOT_API_KEY、QWEN_OAUTH_TOKEN、ALIBABA_CODING_PLAN_API_KEY、ALIBABA_TOKEN_PLAN_API_KEY、SILICONFLOW_API_KEY、SILICONFLOW_CN_API_KEY、GITLAB_TOKEN、CURSOR_ACCESS_TOKEN、AZURE_OPENAI_API_KEY、GROQ_API_KEY、CEREBRAS_API_KEY、MISTRAL_API_KEY、XIAOMI_API_KEY、UMANS_AI_CODING_PLAN_API_KEY、AWS_PROFILE（或 AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY）、GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION、GOOGLE_APPLICATION_CREDENTIALS、HUGGINGFACE_HUB_TOKEN、NVIDIA_API_KEY、FIREWORKS_API_KEY、TOGETHER_API_KEY、BASETEN_API_KEY、LITELLM_API_KEY、OLLAMA_API_KEY、VLLM_API_KEY、LM_STUDIO_API_KEY、LLAMA_CPP_API_KEY 等。

端点覆盖：OPENAI_BASE_URL、ANTHROPIC_BASE_URL（默认 https://api.anthropic.com）、XAI_BASE_URL、MOONSHOT_BASE_URL（https://api.moonshot.ai/v1）、LITELLM_BASE_URL（http://localhost:4000/v1）、OLLAMA_BASE_URL、LLAMA_CPP_BASE_URL、LM_STUDIO_BASE_URL、AZURE_OPENAI_BASE_URL、FIRECRAWL_BASE_URL、SEARXNG_ENDPOINT。企业网关与 mTLS：CLAUDE_CODE_USE_FOUNDRY、FOUNDRY_BASE_URL、ANTHROPIC_FOUNDRY_API_KEY、ANTHROPIC_CUSTOM_HEADERS、NODE_EXTRA_CA_CERTS、CLAUDE_CODE_CLIENT_CERT、CLAUDE_CODE_CLIENT_KEY；网关拒绝预发布字段时用 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 省略它们。

搜索：PERPLEXITY_API_KEY（可选，有匿名回退）、PERPLEXITY_COOKIES、EXA_API_KEY、BRAVE_API_KEY、TAVILY_API_KEY、FIRECRAWL_API_KEY、JINA_API_KEY、KAGI_API_KEY、TINYFISH_API_KEY、PARALLEL_API_KEY、SYNTHETIC_API_KEY、SEARXNG_TOKEN、ANTHROPIC_SEARCH_API_KEY、ANTHROPIC_SEARCH_BASE_URL、ANTHROPIC_SEARCH_MODEL（默认 claude-haiku-4-5）、TYPESAFE_API_KEY。

配置与行为：

变量	作用
OMP_PROFILE	命名 profile 选择器，等同 --profile；优先于 PI_PROFILE，即使显式为空；空、空白或 default 选默认 profile。名字要匹配 [a-z0-9][a-z0-9._-]{0,63}，不能是 ./..、不能以 . 结尾、不能是 Windows 保留设备名
PI_CODING_AGENT_DIR	会话存储目录，默认 ~/.omp/agent
PI_CODING_AGENT_SESSION_DIR	单独覆盖会话目录
PI_CONFIG_DIR	项目配置目录名，默认 .omp
PI_CONFIG_FILES	YAML 覆盖层路径列表，Unix 用 : 分隔，Windows 用 ;；在项目设置之后、--config 之前加载
PI_SMOL_MODEL / PI_SLOW_MODEL / PI_PLAN_MODEL	覆盖对应角色模型（同名 flag 优先）
PI_NO_PTY	禁用 PTY 交互式 bash
PI_DISABLE_UUTILS_BUILTINS	禁用进程内 coreutils
PI_SHELL_PREFIX / CLAUDE_CODE_SHELL_PREFIX	shell 命令前缀
PI_BASH_NO_CI / PI_BASH_NO_LOGIN	去掉 bash 的 -i / 把 -l -c 改成 -c
PI_MAX_AST_FILES	ast_edit 单次 pass 的文件数上限，默认 1000
PI_TASK_MAX_OUTPUT_BYTES / PI_TASK_MAX_OUTPUT_LINES	子智能体输出上限，默认 500000 / 5000
PI_WALK_WORKERS	遍历并发数，默认 4，0 为自动
PI_EDIT_VARIANT	编辑格式：patch、replace、hashline、apply_patch
PI_STRICT_EDIT_MODE / PI_INTENT_TRACING	严格编辑模式 / 意图追踪
OMP_MCP_TIMEOUT_MS	覆盖所有 MCP 超时，0 禁用
OMP_WORKTREE_DIR	覆盖 worktree 目录（默认 ~/.omp/wt）
OMP_GITHUB_CACHE_DB	覆盖 GitHub 缓存库（默认 ~/.omp/cache/github-cache.db）
OMP_SKIP_SETUP	跳过启动向导
OMP_NO_WEBP / OMP_NATIVE_LIBRARY_PATH	禁用 WebP / 指定原生库路径（后者仅 Linux）
VISUAL / EDITOR	Ctrl+G 外部编辑用
JS_DEBUG_DAP_SERVER	指定 js-debug DAP 服务器的绝对路径
PUPPETEER_EXECUTABLE_PATH / PUPPETEER_PROXY	指定浏览器可执行文件 / 代理
PI_TINY_DEVICE / PI_TINY_DTYPE	本地小模型的设备（cpu、gpu、metal、webgpu、auto、cuda、dml、coreml、wasm、webnn*）与量化类型（出厂 q4，可选 auto、fp32、fp16、q8、int8、uint8、bnb4、q4f16、q2、q2f16、q1、q1f16）
PI_NO_TITLE / PI_CACHE_RETENTION	禁用标题生成 / 提示缓存保留策略（long、short、none）
HINDSIGHT_API_URL / HINDSIGHT_API_TOKEN 等	Hindsight 记忆后端全套覆盖
MNEMOPI_EMBEDDING_MODEL 等	Mnemopi 记忆后端
XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME	XDG 布局
CLAUDE_CONFIG_DIR / COPILOT_HOME / COPILOT_CUSTOM_INSTRUCTIONS_DIRS	兼容提供商的配置目录
OTEL_EXPORTER_OTLP_ENDPOINT 等	OpenTelemetry 导出（协议只支持 http/protobuf）

代理链路：先看 NO_PROXY/no_proxy，然后 PI_PROXY_<PROVIDER>（如 PI_PROXY_GITHUB_COPILOT）→ PI_PROXY → HTTPS_PROXY/https_proxy/HTTP_PROXY/http_proxy → ALL_PROXY/all_proxy；回环、链路本地和 RFC1918 地址自动绕过。

终端与图像相关（排查显示问题时用）：PI_FORCE_IMAGE_PROTOCOL（kitty、iterm2/iterm、sixel，off/none/0/false 关闭）、PI_ALLOW_SIXEL_PASSTHROUGH、PI_KITTY_PLACEHOLDERS/PI_NO_KITTY_PLACEHOLDERS、PI_TUI_SYNC_OUTPUT/PI_NO_SYNC_OUTPUT/PI_FORCE_SYNC_OUTPUT、PI_NO_DECCARA、PI_HARDWARE_CURSOR、PI_DEBUG_REDRAW、PI_TUI_RESIZE_SCROLLBACK（preserve）、PI_NOTIFICATIONS、PI_TUI_WRITE_LOG、PI_TUI_RAW_BACKSPACE_IS_CTRL。自动检测的有 COLORTERM、TERM、COLORFGBG、TERM_PROGRAM、TERM_PROGRAM_VERSION、TERMINAL_EMULATOR、WT_SESSION、TMUX_PANE、KITTY_WINDOW_ID、WEZTERM_PANE、ZELLIJ_PANE_ID、NO_COLOR、DISPLAY、WAYLAND_DISPLAY、WSL_DISTRO_NAME、WSL_INTEROP、TERMUX_VERSION。

诊断类：PI_TIMING（full/x）、PI_DEBUG_STARTUP、PI_CODEX_DEBUG、PI_AUTO_QA、PI_AUTO_QA_PUSH、DEBUG、PI_STREAM_FIRST_EVENT_TIMEOUT_MS、PI_STREAM_IDLE_TIMEOUT_MS、PI_CODEX_WEBSOCKET_*（空闲超时默认 300000、ping 间隔 10000、pong 超时 60000、队列容量 4096、重试预算 5、重试延迟 500）。

规则：环境变量 ≠ YAML ≠ flag，flag 最大（--slow 盖过 PI_SLOW_MODEL）；启动时按「继承的环境 → $PWD/.env → ~/.omp/agent/.env → ~/.omp/.env → ~/.env」加载，Bun 还可能预载 .env.local、.env.<NODE_ENV>、.env.<NODE_ENV>.local；真值是 1、y、true、yes、on；改完要重启。坑：.env 不热重载；继承来的值盖过所有 .env；GITHUB_TOKEN/GH_TOKEN 不等于 Copilot 凭据；OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 可能把提示词暴露到遥测里；密钥泄露就去吊销轮换，并 chmod 600 ~/.omp/.env；Windows 上路径列表用 ;、有 omp.cmd、profile 名不能用保留设备名。

内部协议速查

read、write、grep 这些工具都认内部 URI，常见的：

协议	用途
pr://482、pr://owner/repo/482、pr://482/diff、pr://482/diff/3、pr://482/diff/all	GitHub PR 及其 diff（需要 gh）
issue://731、issue://?state=open&label=bug&limit=20	GitHub issue 与查询
conflict://N、conflict://*	合并冲突；写入 @theirs/@ours/@base 解决，* 批量。ID 是会话局部的，读过完整 Git 冲突标记块之后才存在，不可跨会话复用
agent://<id>/findings.0.path	按路径从子智能体的结构化输出里取字段
proc://	控制后台任务、给同伴发消息
skill://	引用技能
security://scans/<scan-id>/findings	安全扫描资源
xd://、xd://<tool>、xd://resolve、xd://report_issue	按需工具目录、接受暂存的 AST 编辑、上报工具问题
artifact://…	压缩产生的可恢复工件
blob:sha256:<64hex>	会话里外置的大对象
ssh://	已配置的远程 POSIX 主机（直读上限 1 MiB）

常见问题

using 文档给了一张「卡住了怎么办」的对照表，很实用，照抄如下：

你看到的现象	恢复办法
按键在移动列表而不是编辑提示	有选择器、自动补全菜单或问题对话框获得了焦点。读它的页脚，或按 Esc 关掉
排队的消息不对	按 Alt+Up 或 Shift+Up，编辑取回的文本，重新提交
智能体走错了方向	用 Enter 发一条具体的引导消息。如果继续下去有害，按 Esc，审阅已经改了什么，再给出纠正
你不小心停掉了一个好的轮次	发送 . 或 c 继续之前的意图
一次响应失败了	读错误卡片，然后按 Alt+R 重试，或用 /model 换模型
工具输出或 diff 看起来不完整	按 Ctrl+O 展开
缩放或重连后终端显示乱了	按 Alt+L 重置并重绘
omp 只调查不编辑	检查是否处于 Plan 模式，以及屏幕上显示的审批提示或策略。批准该动作、退出 Plan，或有意地调整 Interaction → Approvals
上下文占用接近上限	把当前想法收尾，然后跑 /compact
终端断连或 omp 退出了	回到项目目录跑 omp -c；如果那不是最近的项目会话，用 omp -r
想不起某个快捷键	跑 /hotkeys，再看 Keybindings 文档的完整动作与重映射语法

再补几条本文核实过的：

问题	说明
文档站的命令和实际不一致	以 omp <command> --help 为准。本机 v18.16.0 有 51 个子命令，文档索引只列了 38 个
设了环境变量但还在用旧账号	已存储的 OAuth 优先级高于环境变量，先 /logout <provider>
想让写入前弹确认	默认是 yolo，改 omp --approval-mode write 或 omp config set tools.approvalMode write
改了配置文件不生效	没有 /reload-settings，重启 omp；改模板、扩展模块、钩子、自定义工具也必须重启（/reload-plugins 不管这些）
记忆没工作	memory.backend 默认 off，要显式设成 local / mnemopi / hindsight
PR 评审用不了	需要 gh 在 PATH 且 gh auth login；GitHub 工具本身还要 github.enabled: true
调试工具不出现	debug.enabled 默认开，但只在检测到合适的 DAP 适配器时才出现；JS/TS 要手工装 js-debug-adapter
子智能体没有弹审批	设计如此：子智能体 headless 运行、按 yolo 跑。要限制就用 tools.approval.<name>: deny 或收窄 agent 的 tools
想控制花费	--warn-cost、--max-cost、--max-time、/usage、omp stats、/stats
会话文件能直接编辑吗	不要。omp 在迁移或可写操作时可能重写文件；要分析就用 jq 只读，要分享用 omp anonymize 或 /export

参考链接

• 官网：https://omp.sh/
• 文档首页：https://omp.sh/docs
• 快速开始：https://omp.sh/docs/quickstart
• 日常使用：https://omp.sh/docs/using
• CLI 参考：https://omp.sh/docs/cli
• 斜杠命令：https://omp.sh/docs/slash
• 快捷键：https://omp.sh/docs/keybindings
• 设置：https://omp.sh/docs/settings
• 环境变量：https://omp.sh/docs/env
• 提供商：https://omp.sh/docs/providers
• 自定义模型与提供商：https://omp.sh/docs/custom-models
• 模型角色：https://omp.sh/docs/roles
• 工具参考：https://omp.sh/docs/tools
• 运行模式：https://omp.sh/docs/modes
• 计划模式：https://omp.sh/docs/plan
• 目标模式：https://omp.sh/docs/goal
• Vibe 模式：https://omp.sh/docs/vibe
• Prewalk：https://omp.sh/docs/prewalk
• 子智能体：https://omp.sh/docs/subagents
• 编写子智能体：https://omp.sh/docs/subagent-authoring
• 记忆与压缩：https://omp.sh/docs/memory、https://omp.sh/docs/compaction
• 会话：https://omp.sh/docs/sessions、https://omp.sh/docs/session-tree、https://omp.sh/docs/session-format
• 交接：https://omp.sh/docs/handoff
• 文件与编辑：https://omp.sh/docs/files、https://omp.sh/docs/editing
• 评审与提交：https://omp.sh/docs/review、https://omp.sh/docs/commit
• 审批与安全：https://omp.sh/docs/approvals、https://omp.sh/docs/security、https://omp.sh/docs/secrets
• 上下文文件：https://omp.sh/docs/context-files
• 流规则：https://omp.sh/docs/ttsr
• 魔法关键词：https://omp.sh/docs/magic-keywords
• 提示词模板：https://omp.sh/docs/prompt-templates
• 技能、钩子、自定义工具、扩展、插件、市场：https://omp.sh/docs/skills、https://omp.sh/docs/hooks、https://omp.sh/docs/custom-tools、https://omp.sh/docs/extension-authoring、https://omp.sh/docs/plugins、https://omp.sh/docs/marketplace
• MCP：https://omp.sh/docs/mcp、https://omp.sh/docs/mcp-authoring
• 代码智能与调试：https://omp.sh/docs/code-intelligence、https://omp.sh/docs/debugging
• 浏览器与桌面：https://omp.sh/docs/web、https://omp.sh/docs/computer
• GitHub：https://omp.sh/docs/github
• 协作：https://omp.sh/docs/collab
• Advisor：https://omp.sh/docs/advisor
• SDK、RPC、ACP：https://omp.sh/docs/sdk、https://omp.sh/docs/rpc、https://omp.sh/docs/acp
• 主题：https://omp.sh/docs/themes
• 仓库：https://github.com/can1357/oh-my-pi（含中文 README README.zh-CN.md）
• 变更日志：https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/CHANGELOG.md
• npm：https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent
• 关于 harness 的博文（编辑成功率数据的来源）：https://blog.can.ac/2026-02-12/the-harness-problem/
• Stencil Labs：https://stencil.so

---

本文所有命令、参数、默认值、路径与限制均来自 omp.sh 官方文档（2026-11-05 抓取的 55 个文档页）与仓库的官方中英文 README；版本号、Release 资产大小与校验和来自 GitHub API 与 npm registry；标注「本机实测」的部分是在 Windows + Scoop 安装的 omp v18.16.0 上实际运行得到的输出。文档与二进制不一致的地方（子命令数量、--approval-mode 取值、chillax 关键词、/branch 行为）都在正文中标出，请以你已安装版本的 omp --help 为准。