omp 使用指南（新手版）

omp 是在終端機執行的 AI 寫程式助理（coding agent）：你描述需求，它讀檔、改檔、跑指令與測試再回報。它不綁定單一模型，可同時接 Claude、Codex、OpenCode Go 等已訂閱的服務。

環境資料產生於 2026-10-07 18:55　·　omp/18.8.0

先看這裡

標記只用在有爭議或不確定的說法：實測 在本機跑過；文件 出自 omp 文件、未實測；未驗證 不確定。

你目前的預設（自動產生，與實際設定一致）

最常用的 8 件事

啟動 omp

cd ~/GitHub/我的專案
omp                         # 開啟互動式對話
omp "修掉 build 錯誤"         # 帶第一句話啟動
omp @spec.md "照這份規格做"   # 附加檔案或圖片（@路徑）
omp -c                      # 接續上一個對話
omp -r                      # 從清單挑一個舊對話
omp --version               # 版本
omp update                  # 更新 omp

• 啟動的資料夾就是工作目錄，專案層設定與指令檔（.omp/、AGENTS.md）從這裡找；在家目錄 ~ 啟動時改用暫存資料夾。
• 第一次用某家模型要登入：omp login（對話中 /login）。已登入的 provider 見 §21。

畫面與輸入

畫面由上而下：對話與工具輸出、子 agent 區塊、輸入框與狀態列（可在 /settings 調整）。

輸入框

第一個任務

1. 確認工作樹乾淨

   cd 到專案執行 git status，之後 git diff 就只有 omp 的改動。

2. 啟動並貼上需求

   輸入 omp，例如：「README 的安裝步驟少了 Python 版本需求，請補上，並確認 `python3 --version` 的最低版本。」

3. 看它做事

   讀檔、建 todo、改檔；Ctrl+O 看工具輸出。

4. 自己看 diff

   另開終端機跑 git diff。完成報告是 omp 的說法，不是驗證。

5. 修正或提交

   不滿意就說「這裡改成…」；滿意就 git commit，或用 omp commit 產生訊息。

對話（session）

每次啟動 omp 就是一個 session，自動存在 ~/.omp/agent/sessions/（依專案資料夾分類）。

安全與審批

工具分三種風險，由 tools.approvalMode 決定要不要先問你：

• 這次要詢問：omp --approval-mode write；永久：omp config set tools.approvalMode write。
• 工作樹不是沙箱：開始前 git status 確認乾淨，出事才能用 git 還原。
• 認證、金流、資料、權限、部署別交給便宜模型決定。

模型與角色

三個層次

• provider：服務來源，如 anthropic、openai-codex、opencode-go；登入以它為單位。
• model：寫成 provider/模型id，如 anthropic/claude-sonnet-5-5；omp models 列出全部。
• role（角色）：「這類工作交給哪個模型」，由 modelRoles 對應。

內建角色

角色名稱是固定的鍵，不能改名，但可另建別名指向它（§17）。實測

在對話中換模型

思考強度（thinking level）

由低到高：off、minimal、low、medium、high、xhigh、max，另有 auto（由 omp 依任務判斷）。

• 越高越慢、輸出越多，不一定越準：MAF 的 DeepSeek 基準上 low 一次通過率與更高等級相近、成本較低（僅兩題）。
• 切換：Shift+Tab；啟動時 --thinking high；或在模型後加冒號，例如 anthropic/claude-sonnet-5-5:medium。
• Ctrl+T 只切換思考內容的顯示。

context 與 token：為什麼長對話會變貴

• token：計費與額度單位，約為字的片段。
• context window：一次能看的上限；Sonnet 5.5 約 100 萬 token，Codex GPT-6 系列約 27 萬（omp models --json）。
• 每一輪都重送整段對話歷史，對話越長每輪越貴。
• prompt cache：重複的前綴以低價讀取，Sonnet 5.5 約為新輸入的 1/10，所以 omp stats 裡多是「快取讀取」。
• compaction：快滿時自動摘要舊內容；主動 /new 通常更好。

看用量

omp usage                   # 各家訂閱的 5 小時／每週／每月額度（百分比）
omp stats --summary         # 各模型的請求數、token、API 等價金額
omp usage clients --days 7  # 依 client 拆分 token

「API 等價金額」依牌價換算，不是訂閱實扣額度；Claude 7 天額度刻度只有 1%，單一任務看不出差異。實測

指令檔：AGENTS.md

指令檔在對話開始時載入、每一輪都會送出，所以要短：只寫「何時做、為什麼」。

~/.omp/agent/AGENTS.md 存在時，會取代 ~/.claude/CLAUDE.md 成為使用者層級指令。文件 你的規則全文見 §21。

工具與編輯方式

畫面上的每一個動作都是一次工具呼叫。

hashline 編輯（你的 edit.mode）：每行帶內容雜湊作為錨點；檔案讀後被改動，編輯會失敗要求重讀，不會改錯位置。

設定的層級

• 陣列型設定（例如 disabledProviders）是整個取代，不是合併。文件
• 看值 omp config get 設定鍵（如 omp config get modelRoles）；改值 omp config set 設定鍵 值 或 /settings。
• 專案 .omp/config.yml 寫 prewalk: {enabled: false}，在該目錄 omp config get prewalk.enabled 得 false，全域仍是 true。實測
• omp config get 不反映 --config 覆蓋，只能實際跑一次確認。實測

Plan mode 與 todo

• plan mode（Alt+Shift+P）：只探索、提問（ask）、寫計畫檔（local://…-plan.md），你核准後才實作，適合大功能。edit 只能寫入「writable roots」且禁止刪除搬移；writable roots 的範圍文件未定義。文件
• plan 角色是 Codex GPT-6 Astra，但 --plan-yolo（無人值守）實驗中是 Sonnet 規劃；互動式是否用 Astra 未測。未驗證
• todo：agent 用 todo 維護待辦清單，也是 prewalk 開閘的條件。

Skills

Skill 是 skills/<名稱>/SKILL.md 的說明書，平時只常駐描述，需要時才讀全文；也可 /skill:名稱 呼叫。omp 也讀 Claude、Codex、.agents 裝的 skill（如 ~/.agents/skills）。

子 agent

子 agent 從乾淨的 context 獨立工作，只把摘要交回主對話：它讀的檔案不會撐大主對話，也能用較便宜的模型。

• 派不派由主對話決定；明說「先派 scout 找出訂單匯出相關的檔案」最可靠，沒明說時它很少自己派。實測
• Alt+A 開 Agent Hub：看狀態、模型、用量，讀逐字稿、插話、復活或終止。閒置約 7 分鐘休眠，追問它比開新的省。
• 省略 agent 欄位：受限 agent（如 reviewer）派工沒寫名稱，會落到父 agent 允許清單第一項，實驗中因此派出 scout。派工一律寫明名稱。實測
• 保護機制：同時上限、遞迴深度、請求軟上限，數值見 §21。
• 並行寫入預設沒有隔離，改同一檔案會衝突；task.isolation.enabled 可改用獨立工作區。未驗證

Prewalk：規劃用強的、實作用便宜的

• 一次性交接：在含第一次 edit／write 結果的那一輪結束時發生，不論成敗。實測
• 要先成功呼叫 todo 才開閘（todo 工具啟用時），不看任務難度。交接後 DeepSeek 做到你切換為止，並收到「完成前檢查清單」。
• Claude 只寫計畫、驗收標準與介面，測試由 DeepSeek 寫。要 Claude 寫測試：先 --no-prewalk，寫完再 /prewalk。未驗證

實驗（附錄 A）：Claude 原始 token 約 0.19×，所有模型合計約 23×。

Advisor：旁路審查

另一個模型（你的是 Codex GPT-6.1 Sol）旁觀主 agent，把建議插進對話。它不能批准或改檔，只給 nit、concern、blocker 三級建議。

• 只在 agent 結束時審一次，實驗中每組 4 次 Codex 請求、約 15 秒。實測
• 指令：/advisor（開關）、/advisor status（看狀態與成本）、/advisor off。
• reviewer 則是主動派出的子 agent。進階：WATCHDOG.md 補審查重點、WATCHDOG.yml 設多個審查者（未用）。

別名與自訂 agent

角色別名

值要加引號，@ 代表「某個角色」：

modelRoles:
  deep: "@slow"      # 你的別名：難題用
  worker: "@smol"    # 你的別名：便宜的實作者
task:
  agentModelOverrides:
    scout: "@worker" # agent 用別名指定模型

別名可串接，--model deep 可用 實測；/model 是否列出別名 未驗證。

scout、task、sonic 不是角色

它們是子 agent 的類型名稱，不能改名。要新名稱得在 ~/.omp/agent/agents/名稱.md（或專案 .omp/agents/）寫 agent 定義，frontmatter 含 name、description、model。未驗證

其他

• /modelpreset save 名稱／switch 名稱：存取整組角色設定；目前沒有（omp config get modelPresets 為 {}）。
• A/B 對照組：omp --config ~/.omp/agent/solo.yml，全部指向 Claude，關閉 advisor 與 prewalk。

無頭模式與腳本

omp -p "總結最後一個 commit"                 # 印出結果就結束
omp -p --mode json "列出所有 TODO"            # JSON 事件串流，方便程式處理
omp -p --max-time 10m "…"                    # 限時
omp -p --plan-yolo "…"                       # 自動核准規劃並實作（風險自負）
omp -p --no-session "…"                      # 不存檔
echo "review this diff" | omp -p             # 從標準輸入給提示

旗標見 omp --help。無頭模式無法詢問，審批直接依 approvalMode。

魔法關鍵字

提示詞出現這些小寫、獨立的詞時，omp 為那一輪加一段指示：

你目前沒啟用的功能

你目前的環境設定

omp 版本 omp/18.8.0。

角色（modelRoles）

子 agent 的模型（task.agentModelOverrides）

功能設定

可用的 provider

列出表示已登入或免金鑰；實際用不用看角色與 agent 設定。

設定檔

# Delegation rules

Goal: keep Claude's context and output small without lowering quality. Claude plans and judges; other models explore, implement, and review.

- Unsure where to change? Spawn `scout` first; keep file dumps out of this context.
- Before the first edit (the session hands off to a cheaper model there), write down the acceptance criteria, the interfaces, and the test command. The implementer writes the tests against that list.
- Brief every delegate with: goal, files it may change, constraints, acceptance command. No implementation design. Always name the `agent`; an omitted name falls to the parent's first allowed agent.
- Hand over a whole module in one task, not small pieces. Parallel agents must not edit the same file.
- Do these here, never delegate: small edits, ambiguous requirements, cross-module judgment, auth/payment/data/permission/deploy changes. Large or multi-decision work: plan mode first.
- While developing, run only the tests for changed modules; run the full suite once at the end.
- Same failure after two fixes: stop and report, then change approach or take over. Do not retry unchanged.
- After delegating, read the result and the diff; do not reread what the delegate already read.
- Before the first edit, record the base SHA (`git rev-parse HEAD`). Before declaring done: commit, then paste the test command and its result for that commit. Spawn `reviewer` on `BASE..HEAD`, giving it both SHAs (a committed tree has an empty working diff). Act only on findings provable in the code; treat the rest as notes. Any fix is a new commit: rerun the tests and the review on the new SHA.
- If the repo has `AGENT_LEARNINGS.md`, read only entries relevant to the task (`rg`).

# A/B baseline: every role and subagent runs on Claude, advisor and prewalk disabled.
# Use: omp --config ~/.omp/agent/solo.yml
modelRoles:
  default: anthropic/claude-sonnet-5-5:medium
  slow: anthropic/claude-opus-5-5:high
  plan: anthropic/claude-sonnet-5-5:high
  smol: anthropic/claude-sonnet-5-5:low
  commit: anthropic/claude-sonnet-5-5:low
task:
  agentModelOverrides:
    scout: "@default"
    task: "@default"
    sonic: "@default"
    reviewer: "@default"
advisor:
  enabled: false
prewalk:
  enabled: false

你的終端機：Warp 加 Herdr

omp 跑在 Warp 裡的 Herdr 面板中，按鍵要穿過三層：

omp 沒有自訂快捷鍵（~/.omp/agent/keybindings.yml 不存在），Alt+P 是預設綁定。失效時逐層檢查：

10 秒判斷

處理順序

1. Warp

   Settings 搜尋 Meta 或 Option，開啟 Option as Meta；在 Keyboard shortcuts 查 Option+P 有無衝突（橘框）。已知問題：warpdotdev/warp #8583、#9517。

2. Herdr

   config.toml 沒有自訂按鍵（只有 onboarding = false），預設是 tmux 式 prefix 加 Cmd 直按鍵，不太會吃掉 Alt+P。

3. 不靠按鍵的替代

   /model、/prewalk restart、omp --model deep、omp --no-prewalk、/agents、/advisor、/usage。

4. 最後手段：在 omp 改綁

   建立 ~/.omp/agent/keybindings.yml（不是 config.yml），重開後用 /hotkeys 確認：

   app.model.selectTemporary: Ctrl+Shift+U   # 原本 Alt+P
   app.model.select: Ctrl+Shift+Y            # 原本 Alt+M

情境食譜

故障排除

附錄 A：實驗記錄（ytdl 下載器，2026-10-07）

附錄 B：驗證狀態

附錄 C：更新紀錄

附錄 D：如何維護這份文件

原始檔在 ~/Documents/omp-guide/：

python3 ~/Documents/omp-guide/build.py            # 重新產生文件（改過設定後執行）
python3 ~/Documents/omp-guide/build.py --check    # 文件的「環境」章節是否落後？落後會 exit 1

快照記錄全域設定：build.py 在指南資料夾查詢 omp，專案內的 .omp/config.yml 不會被誤記成全域（從有 prewalk.enabled: false 的專案執行，仍記錄 true）；專案層覆蓋要在該專案用 omp config get 看。

請 agent 更新時說「更新 omp 指南」並簡述變更：它會改模板、在 changelog.txt 加一行、執行 build.py。舊版備份為 omp-guide.v1.html。

附錄 E：名詞表