【2026 最新】OpenResearch 教學：Claude Code、Codex 三路研究怎麼留下可驗收收據？

OpenResearch 教學最容易教錯的地方，是把「同時開三個 Agent」當成完成。你真正要解決的，是三路研究結束後，還能回答：它們是否從同一題出發？改了哪些檔案？用了哪個版本與環境？哪一條超支、哪一條遇到反證？最後憑什麼選它，而不是因為文字最有氣勢？

這篇會帶你用 OpenResearch，把同一研究問題拆成 Claude Code、Codex 與 OpenCode 三條受控路徑；從安裝、worktree（同一個 Git repository 的獨立工作目錄）、experiment tree、固定 run command，一路做到 log、diff、artifact（執行產物）與 SHA-256 收據。讀完後，你會得到一份可直接改寫的三路 manifest、一套停手規則，以及矛盾結果與超支分支的處理流程。

範圍先說清楚：本文在 2026 年 9 月 14 日核對 OpenResearch v0.2.1，並用不呼叫付費模型的決定性 fixture 實跑本機 CLI、dashboard、baseline 與三個 sibling experiment。這能驗證編排與收據管線，不是 Claude Code、Codex 或 OpenCode 的品質評比，也不代表大型語言模型每次會產生逐字相同答案。

先懂 6 個詞：project 是一個研究 repository；session 是一次 Agent 對話；worktree 是隔離檔案修改的 Git checkout；experiment node 是一個有 parent 的假設節點；run 是針對已記錄 commit 的一次執行；receipt 是把題目、commit、環境、命令、log 與 artifact 串起來的研究收據。

先說結論：可靠平行研究不是三票表決

可驗收的平行研究 ≈ 隔離假設 × 固定契約 × 不可變收據

這是一個操作口訣，不是統計公式。隔離假設，避免三個 Agent 互相抄同一條路；固定契約，讓時間、來源上限、輸出格式與成功條件可比；不可變收據，則讓你知道每個結果實際對應哪個 commit。任一項缺失，三個答案就只是三段文字，不是一場受控比較。

也要把「可重跑」與「必然相同」分開。OpenResearch 能把 run 綁到 committed source snapshot，保存 lineage、log、diff 與 artifact；但依賴版本、資料快照、硬體、隨機種子、外部 API、模型版本與權限仍要另外凍結。它提高的是可追溯性，不會自動把非決定性的 LLM 變成逐 bit 重現的程式。

OpenResearch 是什麼？把 Agent 對話接到 Git 實驗樹

OpenResearch 官方 repository把產品定位為 local-first 的研究 Agent 工作區。你可以在同一個 dashboard 開 Claude Code、Codex、OpenCode 等 harness，讓每個 session 使用自己的 worktree；研究程式則以有 parent／child 關係的 experiment node 表示，執行後把 commit、狀態、log 與產物留在同一條 lineage。

如果你還不熟 harness，可以先讀AI Agent Harness 是什麼。OpenResearch 不替模型「增加智力」，它提供的是外部控制面：專案、工作目錄、執行節點、compute backend 與證據紀錄。這也解釋了為何它和單純比較Claude Code vs Codex不同：這次不是先選一個冠軍，而是讓不同執行器在同一契約下接受驗收。

• session／worktree：隔開各 Agent 的 checkout 與未提交修改，降低互相覆寫。
• experiment tree：把 baseline、假設分支、修復分支與重跑關係畫成可追蹤樹狀結構。
• run archive：依 experiment 記錄的 commit 打包來源；未 commit 的檔案不會進入該 run snapshot。
• logs／diff／artifacts：保留執行輸出與結果檔，讓裁決依據不只是一段聊天摘要。
• compute backend：目前 CLI 可把 experiment 送到 local、SSH、Slurm、Kubernetes、Ray、Hugging Face Jobs、Modal、Tinker 或 OpenResearch managed compute；各路的帳號、費用與環境責任不同。

截至本文核對時，最新正式版是 v0.2.1，發布於 2026 年 9 月 12 日。功能變動很快，照本文操作前仍應先看 release notes，尤其不要把舊版 README 的安全描述直接當成新版行為。

AlphaLab 實測：先驗證管線，不假裝測了三個模型

AlphaLab 在 Apple Silicon Mac 下載官方 v0.2.1 asset，核對發布頁提供的 SHA-256，再以停用 telemetry、另開本機 port 的方式啟動 dashboard。測試 repository 只有一個固定 shell command 與一個 variant 設定；我們先建立 baseline，再建立「來源鏈優先、反證優先、重跑優先」三個 sibling node，分別 commit 後用 local backend 執行。

這次 smoke test 確認三件事：project 預設 run command 能被節點繼承；每個完成的 run 都對應一個已提交 commit；dashboard 能回到該節點查看 Code 與 Logs。它沒有驗證 Claude Code 或 OpenCode 登入，也沒有花模型費用跑完整研究題。因此，下文的三 Agent 做法是依官方 v0.2.1 介面與程式碼建立的操作流程，模型效果仍要由你的真實題目另做驗收。

OpenResearch 教學第一步：安裝固定版本並啟動本機 dashboard

開始前準備 Git，以及你真的要用的 harness。Claude Code、Codex、OpenCode 都要各自安裝並完成它們原本的登入或 provider 設定；OpenResearch 不會替你附送模型權限。研究 repository 也要先能正常 commit，因為未提交內容不會進入 experiment run 的來源快照。

官方首頁提供會跟著 latest 移動的安裝命令；為了讓教學可追查，下面先把 installer 固定在本文核對的 release。正式團隊還應下載平台 asset 與同名 .sha256，在安裝前自行核對：

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/alphaXiv/OpenResearch/releases/download/v0.2.1/openresearch-cli-installer.sh | sh

orx version
orx telemetry status
orx telemetry off        # 選用：關閉官方 release 的匿名 usage analytics
orx up --no-browser

預設 dashboard 在 http://127.0.0.1:4791。127.0.0.1 代表 listener 只綁本機 loopback，不代表 harness 全程離線：Claude、Codex、雲端 OpenCode provider、Git 操作、搜尋工具與遠端 compute 仍可能連網。若你要完全本機模型，官方的 local models 文件要求經由 OpenCode 接可用 endpoint；「本機模型」也不能自動保證工作流沒有其他網路工具。

Windows 使用者先停一下：官方文件仍標示 beta，需要 Git for Windows，且列出 unsigned binary、長路徑、self-update 與部分遠端能力等限制。先用無敏感資料的短路徑 repository 做 smoke test，不要直接把 Unix 教學當成 Windows 等價保證。

第二步：接上 Claude Code、Codex、OpenCode 三個 harness

進 dashboard 後選 project，再開三個 New Chat，分別選 Claude Code、Codex、OpenCode。每個 chat 的 harness 建立後便固定；要換工具就另開 chat。也可以先執行 orx install-skills，把 OpenResearch 的實驗樹、證據、Git 與 compute 工作法安裝到支援的 Agent 環境，再逐一確認三個 CLI 自己能登入與回應。

orx install-skills
orx projects
orx project view <PROJECT_ID>

OpenResearch 會替 session 建 worktree，但不要把這句話理解成「三個安全沙箱」。Git objects、refs、remote、OpenResearch database、同步環境變數與某些 project artifact 仍可能共用。Claude Code 與 Codex 也各有自己的原生 worktree 功能，可參考Claude Code worktree 文件與Codex worktree 文件；但 OpenResearch 建立的是自己的 worktree，不能直接借用原生模式的所有權限保證。

三路需要共享的是題目與契約，不是彼此的推理過程。若要管理共同背景，可以先用Context Repo的思路凍結術語、資料字典與共同限制；但每路的假設卡、來源筆記與結果目錄要分開，避免第二路看見第一路答案後只做同義改寫。

第三步：把同一問題拆成三個可否證、可裁決的假設

假設不能只寫成「請用不同角度研究」。以「同一份分析在兩台機器得到不同結論，主因在哪裡？」為例，可以預先定義三個優先歸因：

• H1｜來源鏈破裂：兩次 run 使用的輸入、引用或 prompt 不同；由 Claude Code 專查 provenance 與 hash。
• H2｜程式／設定漂移：輸入一致，但 commit、config 或 run command 不同；由 Codex 專查 diff 與測試。
• H3｜環境／外部狀態漂移：來源與 commit 一致，差異來自依賴、硬體、隨機種子、模型或外部 API；由 OpenCode 做乾淨環境重跑。

現實中多個原因可以同時存在，所以「互斥」必須由裁決規則建立：依 H1 → H2 → H3 的順序找第一個足以解釋差異、且反例測試通過的主因；若兩條同時命中或證據不足，答案就是 inconclusive，不是硬湊一個勝者。這比請三個 Agent 自由辯論更容易驗收。

把下列 manifest 放進 repository，先由人類簽核，再分給三個 session。它是本文的操作模板，不是 OpenResearch 內建 schema：

question_id: ORX-DEMO-01
baseline_commit: "填入 40 字元 Git SHA"
prompt_sha256: "填入共同題目檔的 SHA-256"
fixed_run_command: "bash scripts/verify.sh"
decision_order: [H1, H2, H3, inconclusive]

shared_limits:
  wall_clock_minutes: 30
  max_primary_sources: 12
  allowed_tools: [official_docs, repository, local_shell]
  max_output_chars: 12000
  stop_when:
    - contract_test_failed
    - required_source_unavailable
    - any_limit_reached

lanes:
  H1: {harness: claude-code, output_dir: artifacts/H1}
  H2: {harness: codex,       output_dir: artifacts/H2}
  H3: {harness: opencode,    output_dir: artifacts/H3}

重要限制：shared_limits 是你的實驗契約，不是 v0.2.1 的跨 harness 硬預算鎖。截至 2026 年 9 月 14 日核對該版 CLI、dashboard 與原始碼，官方介面未提供一個能同時替 Claude Code、Codex、OpenCode 強制美元或 token 上限的通用控制；畫面上的 context usage 只反映最近一次 API request，不是累積帳單。需要硬上限時，要另外使用 provider quota、獨立低權限憑證、支援 backend 的 job timeout 或外部 supervisor，並實際做一次超支中止測試。

第四步：建立 baseline 與三個 sibling experiment

先把共同題目、驗收腳本、依賴 lockfile 與 baseline 結果 commit。接著設定 project 的固定 run command，建立一個 baseline，再讓三個假設都以它為 parent。ID 由 CLI 回傳，不要手打猜測：

orx projects
orx project edit <PROJECT_ID> --run-command 'bash scripts/verify.sh'

orx create-experiment <PROJECT_ID> \
  --title 'Baseline' --baseline

orx create-experiment <PROJECT_ID> \
  --title 'H1 provenance break' --parent <BASELINE_ID>
orx create-experiment <PROJECT_ID> \
  --title 'H2 code drift' --parent <BASELINE_ID>
orx create-experiment <PROJECT_ID> \
  --title 'H3 environment drift' --parent <BASELINE_ID>

每個 Agent 只在自己的 branch／worktree 改動被允許的 config、測試與假設報告；不要為了配合結果改 run command 或環境變數。修改完成後先 review diff、commit，再 launch。OpenResearch 的 run archive 取自節點記錄的 commit，未提交 scratch 不在快照裡；刪除 session 也可能丟掉未提交內容。

git status --short
git diff --check
git add hypotheses configs scripts artifacts
git commit -m 'test H1 provenance break'

orx exp run <EXPERIMENT_ID> --backend local
orx exp wait --project <PROJECT_ID>
orx runs <PROJECT_ID>
orx logs <RUN_ID>

orx exp wait --project 在第一個 terminal run 出現時就返回，它是「有一個 slot 空出來」的訊號，不是「全部完成」。每次返回都重新執行 orx runs <PROJECT_ID>，直到沒有 in-flight run。orx logs 讀的是 experiment stdout／stderr，不是 Agent 對話；預設只取尾端的一段內容，長 log 要改用 --head、--bytes 或 --range start:end，不能把截斷後沒看到當成事件不存在。

如果你偏好由一個 session 分派，也可用 orx agent spawn --harness <HARNESS> --model <MODEL>。helper 會從空 transcript 開始，因此 task 必須是完整、自包含 brief；不要假設它知道父 session 的限制。新手第一次做，三個 dashboard chat 通常更容易逐路看清權限與停止狀態。

OpenResearch 教學的核心：補齊每路研究收據

OpenResearch 已替你保留 experiment lineage、commit snapshot、run 狀態與 log，但完整重跑仍需要外部欄位。每個分支至少產生一份 receipt.json：

{
  "question_id": "ORX-DEMO-01",
  "hypothesis_id": "H1",
  "parent_commit": "...",
  "run_commit": "...",
  "prompt_sha256": "...",
  "harness": {"name": "claude-code", "version": "...", "model": "..."},
  "command": "bash scripts/verify.sh",
  "environment": {"lock_sha256": "...", "data_sha256": "..."},
  "limits": {"minutes": 30, "sources": 12, "output_chars": 12000},
  "run": {"id": "...", "exit_status": 0, "log_range": "0:65536"},
  "artifacts": [{"path": "artifacts/H1/report.json", "sha256": "..."}],
  "failed_checks": [],
  "unresolved_uncertainty": []
}

三個 session 要用不同的 artifact 目錄。worktree 能隔開 checkout，卻不能保證 shared project file tree 或外部儲存不被覆寫；最安全的做法是把 H1/H2/H3 與 run ID 放進路徑，完成後再計算 hash。若你還要建立來源卡與 citation gate，可接著參考本機 Deep Research 七步實戰；本文只處理三路編排，不重講檢索管線。

第五步：注入矛盾與超支，確認系統真的會停

沒有故障演練的停止條件，只是一句願望。正式研究前做兩次故意失敗：

1. 矛盾注入：在測試 fixture 放入一份與主要來源相反、但日期或適用版本不同的文件。合格結果應標出衝突、版本範圍與待重驗項，不得用「二比一」抹掉反證。
2. 超支注入：把某一路的來源上限設為 2 或時間上限設得很短。到線時應輸出 stopped_limit_reached 與現有收據，不得偷偷提高 ceiling，再把多做的那一路當勝者。

要注意，dashboard 的 Stop／Escape 是中斷當前 harness turn 並清除該 chat queue，不會回滾已寫檔案；orx exp cancel <EXPERIMENT_ID> 則是對 in-flight experiment 提出取消，不能假設瞬間停止。每次中止後都要檢查 process、Git status、run state 與 artifact，再決定：

• repair：沒有回答、命令壞掉或收據缺欄，修成 child node，不覆寫已回答節點。
• refill：證據不足但方向仍可測，新增一個更窄的 child。
• promote：契約通過且反例測試沒有推翻，才把該 commit 合併到候選結論。
• stop：問題已回答、上限已到，或連續嘗試沒有增量，就保留失敗證據並停手。

OpenResearch 官方 experiment-tree 技能的關鍵規則，是已經有 run 回答的 node 不再原地改寫；新假設、新修復都建立 child。這讓失敗不會被成功版本覆蓋。至於何時算「連續沒有增量」，要在 manifest 事先寫成你的題目可驗證的數字，不要把 Agent 提示中的經驗法則誤稱為系統硬限制。

第六步：用證據矩陣裁決，不比較文筆與自信

收齊三份 receipt 後，依固定順序裁決：

1. 身分門：question、prompt hash、parent commit 是否相同？不相同就不是同一場比較。
2. 完整門：harness 版本、環境、命令、exit status、artifact hash、失敗與疑點是否齊全？缺欄先 repair。
3. 契約門：有沒有超過時間、來源、工具、輸出或付費上限？超支分支保留，但排除勝選資格。
4. 可比門：三路的主指標與容許誤差是否同義？若 Agent 各自改 metric，不得直接排序。
5. 反證門：哪個結果能解釋矛盾 fixture，且在乾淨 child run 仍成立？
6. 裁決：輸出 promote、refill、repair、stop 或 inconclusive；不要只輸出「H2 勝」。

如果你的需求只是讓同一個 Agent 先模擬多位專家的問題拆解，Claude STORM 研究法會更輕量；如果你需要三個真正分離的執行路徑、可比較 commit 與故障演練，才值得承擔 OpenResearch 的操作成本。

安全邊界：local-first、worktree、remote 各自不保證什麼

OpenResearch dashboard 能讀寫 project、啟動 shell、管理環境值、開 Agent 與 compute，因此它不是一個可以隨意公開的靜態網頁。最低限度做法是：

• 本機：維持 loopback binding，不做公開 port forward；用專用、無敏感資料的 repository 先測。
• 憑證：不要把所有 provider key 當成方便的全域同步值。v0.2.1 會把同步環境值提供給各 harness child，這不是 per-agent secret isolation。
• 權限：worktree 只隔離 checkout；共享 Git refs、remote、OpenResearch state、外部服務與 artifact path 仍需 branch ownership、唯一目錄與最小權限。
• 敏感研究：使用專用 OS account、container／VM、唯讀資料掛載、窄權限 service credential 與 egress 規則；prompt 裡的「不要讀」不是安全邊界。

遠端模式尤其要保守。v0.2.1 程式碼已實作 loopback SSH tunnel、attachment bearer token 與 authenticated route，但同版 README仍寫著沒有 application-level authentication、同主機其他使用者可能存取，兩者互相矛盾。在維護者澄清並完成「第二個 OS 使用者無法連入」的實測前，不要把 remote shared host 當成多租戶身分隔離；優先使用專用主機或專用帳號。

另外，OpenResearch 整合下的 permission mode 不必然等於 Claude Code／Codex 單獨啟動時的預設 sandbox。每條高風險 shell、網路與寫入權限都應在實際版本做 smoke test；不要因為畫面顯示 Plan、Auto 或 worktree，就推論資料一定唯讀或無法外傳。

OpenResearch 教學常見問題

1. OpenResearch 會取代 Claude Code 或 Codex 嗎？

不會。它是研究工作區與編排層，仍需你另外安裝、登入並承擔各 harness 或 provider 的限制與費用。

2. 三個 Agent 得到同一答案，就比較可信嗎？

不一定。它們可能共享相同錯誤來源、context 或 benchmark。先看來源獨立性、反證測試與 receipt，再看是否同意。

3. immutable run archive 就等於不可刪、完全重現嗎？

不是。它是以 recorded commit 建立並驗 hash 的內容快照，不是法規意義的 WORM 儲存；本機資料仍可能被刪，環境與外部服務也要另行凍結。

4. worktree 能防止三個 Agent 互相影響嗎？

只能防一部分。checkout 檔案分開，但 Git refs、remote、OpenResearch database、憑證、compute 與外部 artifact 仍可能共用。

5. local-first 代表資料不會離開電腦嗎？

不代表。dashboard state 可以留在本機，但雲端模型、搜尋、Git remote、telemetry 與 compute 都可能連網；要逐項檢查資料路徑。

6. OpenResearch 能自動守住每路相同美元預算嗎？

截至 2026 年 9 月 14 日核對的 v0.2.1 官方介面，未提供跨三個 harness 的通用硬上限。用 manifest 對齊時間／來源／工具限制，再由 provider quota、backend timeout 或外部 supervisor 執行真正的硬限制。

7. 只有一個 Agent，也值得用嗎？

若你需要 experiment lineage 與 run receipts，就值得評估。若只是一次性問答，Git branch 加固定驗收腳本可能更簡單。

8. Windows 可以照做嗎？

可以試，但目前仍是 beta。先裝 Git for Windows、用短路徑與非敏感 fixture 驗證本機 workflow，再逐項確認遠端與 cleanup 行為。

給新手的 7 個重點

1. 三路並行的價值不是多數決，而是讓互斥解釋接受同一證據門。
2. 先凍結 question、prompt hash、parent commit、run command 與裁決順序，再開 Agent。
3. 每路用獨立 worktree、branch 與 artifact 目錄；共享 Git 與憑證仍要另設邊界。
4. 一定要 commit 後才 launch，因為未提交內容不在 run source snapshot。
5. 把模型、harness、依賴、資料、log range、exit status、hash 與疑點寫進 receipt。
6. 用矛盾與超支 fixture 驗證 stop rule；Stop 不等於 rollback，cancel 也不保證瞬停。
7. 缺證據就輸出 repair、refill 或 inconclusive；不讓最會寫的 Agent 自動成為勝者。

如果你想先補齊 Git、程式驗收與 AI Agent 的實作底層，再回來搭三路研究樹，可以從 AlphaLab 的線上課程依自己的程度選擇下一步。