【2026 最新】Omnara 教學：筆電離線後 Agent 怎麼接續？自架、雙機與中斷驗收

你讓 AI 幫你整理程式，合上筆電，隔天打開卻不知道它到底停在哪裡。這篇 Omnara 教學，帶你拆清三件事：對話有沒有保存、調度員能不能重新接手，以及另一台電腦上究竟有沒有工作檔案。

本文專為第一次接觸 Agent 部署的讀者寫：先用白話看懂架構，再依官方指令啟動測試服務、連接執行機，最後用兩種中斷留下可核對的紀錄。動手需要已備好的 Docker Compose、Git、Node.js 22 以上，以及可用的模型提供者與測試額度；只想理解原理，可以先讀前兩節。

以下核對至 2026 年 10 月 25 日，官方原始碼固定於 9a5fe25。本篇依官方文件與測試程式設計操作練習，本站未部署雙機環境；文中的驗收欄位是你要觀察的項目，不是已量得的成功結果。

先說結論：接續＝紀錄留得住＋有人接手＋工作現場備齊

Agent 像一本工單；worker 是輪班調度員；machine 是有工具和檔案的工作桌。換調度員、換工作桌、把桌上的東西搬過去，是三件分開驗收的事。

• 控制平面保存 Agent 與事件；執行機透過 omnarad 連回來，負責跑命令。
• 筆電離線後，Agent 的紀錄仍可存在；需要那台筆電的工具工作，則要等待、處理錯誤或改用已具備條件的另一台。
• 先在同一個 Agent 配好兩台機器，再核對 machine_id、工作目錄與檔案內容，才有資格說工作接上了。

一、Omnara 教學先看五個零件：誰記得、誰思考、誰動手？

Omnara 是可自架的 Agent 平台。Agent（能呼叫工具完成工作的 AI 助手）背後仍需要模型與執行層；若這兩層還容易混淆，可先看 Agent Harness 入門。Omnara 這一題的重點，是把執行層再拆成調度服務與真正執行命令的電腦。

• ① API「收件櫃台」：網頁、CLI（終端機指令工具）與你的應用都透過它送任務、讀事件。關掉一個瀏覽器分頁，與關掉整個後端，是不同事件。
• ② Postgres「正式紀錄本」：保存 Agent、事件、機器等持久資料。已保存的輸入、模型輸出與工具結果，構成可讀回的時間線。
• ③ worker「輪班調度員」：取得工作、組合模型需要的上下文、呼叫模型並安排工具。官方將它設計為無狀態程序；這裡的無狀態，是可依外部紀錄接手，不是整套系統都不存資料。
• ④ omnarad「工作桌旁的接線員」：安裝在 macOS／Linux 機器上，主動對外連接控制平面，讓命令在那台電腦執行。
• ⑤ 其他服務與儲存「倉庫及值班管理」：web 提供介面；maintenance 清理過期鎖與處理維護；Redis 傳通知與限流；物件儲存放附件和工具輸出；共享記憶檔案系統保存 memory 檔案。

依 官方架構文件，自架的四個長駐 Omnara 服務是 web、api、worker、maintenance，另外有一次性的 migrate 資料庫遷移工作與前述基礎儲存。白話說，這是一套要維護的服務組合；把它放在同一台筆電，筆電關機仍會一起停。要讓筆電離線後調度服務繼續存在，控制平面就得放在另有供電與網路的主機上。

二、Omnara 教學上手：先讓一台測試機完成最小工作

①「先備空桌」：環境、版本和權限各自確認

在獨立測試主機先查 docker compose version、git --version、node --version。準備可撤銷的模型測試憑證，限制帳務額度；執行機用可拋棄 VM（虛擬機器）與低權限帳號，別把含私人檔案、SSH 私鑰或正式環境憑證的個人電腦當第一張工作桌。omnarad 是能在安裝帳號下執行命令的服務，單靠提示詞「只讀」不會把整台機器變成沙箱。

②「裝好辦公室」：取得原始碼，再啟動服務

依 官方部署文件，在全新目錄依序執行下列指令。這裡選固定提交並從原始碼建置，讓本文設定與程式版本可對帳；首次建置與下載會用到磁碟、網路和時間。

git clone https://github.com/omnara-ai/omnara.git
cd omnara
git checkout 9a5fe25398bdb931a22c5ed8867ca06648a2a0a9
docker compose --profile app up -d --build
docker compose --profile app ps

在同一台主機開 http://localhost:8000 註冊；本機驗證連結可在 docker compose logs api 找到。再到介面新增模型提供者與模型，分享給測試專案。自架新實例的模型與機器要自己配置，不要把雲端範例的預設資源名稱直接當成自架已有的資源。

這組 Compose 的開發預設含弱密碼與不安全開發設定，先限定在隔離測試環境。跨主機連線前，依 設定文件完成祕密加密金鑰、認證、網路存取限制與 HTTPS 入口；設定正確的 OMNARA_PUBLIC_URL，並讓其他機器能連到該入口。第二台機器上的 localhost 指的是它自己，不能拿來指第一台主機。

③「接第一張工作桌」：登入、註冊、分享

CLI 先指向你的測試實例；以下網址僅適用於 CLI 就在控制平面主機上的本機階段。接著登入並選對組織與專案。

npx omnara config --api-url http://localhost:8000/api/v1 --issuer-url http://localhost:8000
npx omnara login
npx omnara config select

依 Connect a machine，可在 All projects → Machines → Connect machine 建立 lab-a，在 Share with 勾選測試專案，再於可拋棄執行機跑該畫面產生的安裝指令。核對指令的安裝來源是你的自架 API origin；不要把雲端的安裝範例盲貼到自架流程。機器 token 只顯示一次，應存入私密儲存，不放入截圖、Git 或公開錯誤紀錄。

安裝器會在 ~/.omnarad 安裝 daemon，能使用時註冊為 systemd／launchd 使用者服務；缺少相應服務管理器時則在前景執行。以 omnarad status 與介面上的 online 核對連線，再查 project grant（分享給專案的使用權）。看到機器存在，和這個專案有權使用它，仍是兩關。

④「先交一件小事」：讀假資料，逐次批准命令

在執行機上由你手動建立全新的 /tmp/omnara-lab，放一份只寫 lab-a-only 的 marker.txt。在 Agent 的 YAML 使用實際配置的提供者／模型名稱，先只接 lab-a：

version: v1
instruction: |
  只處理測試目錄。先列出機器 ID，回報工作目錄並讀 marker.txt。
  不安裝套件、不修改檔案、不連外；遇到缺檔先回報。
model:
  provider_config: YOUR_PROVIDER_NAME
  name: YOUR_CONFIGURED_MODEL_NAME
tools:
  run_command:
    permission:
      mode: always_ask
  write_process:
    enabled: false
  storage_upload:
    enabled: false
  storage_download:
    enabled: false
machine_sources:
  - machine_name: lab-a
    cwd: /tmp/omnara-lab

always_ask 只控制 run_command；機器設定也會自動加入其他程序與檔案工具，因此首輪明確停用 write_process、storage_upload 和 storage_download。後面若練習檔案搬移，再另外啟用所需工具。把兩個 YOUR_… 換成介面中已分享給專案的真實名稱，存為 agent.yaml。執行 npx omnara agents launch --file agent.yaml --name "Offline lab" --message "先列機器，再回報 pwd 並讀 marker.txt"。依 權限文件，always_ask 會暫停等待批准；逐次核對機器、目錄與命令，只批准這輪預期的唯讀操作。

保存回傳的 agt_… Agent ID，用 npx omnara agents chat <agent-id> 或網頁追蹤同一段對話。第一次成功的驗收是：工具紀錄指向正確 mch_…、目錄正確、讀到你放的標記，而不只是 AI 用文字說「完成」。

三、接第二台：同一個 Agent，兩張不同的工作桌

在第二台可拋棄機器重做連線，命名為 lab-b，分享給同一專案，建立同路徑但內容為 lab-b-only 的標記檔。兩台都能到達已完成安全設定的控制平面入口後，複製前面的 YAML，在 machine_sources 加入第二項 machine_name: lab-b 與它的 cwd，啟動一個新的雙機練習 Agent。接下來兩種中斷都用這個 Agent ID，避免把新建對話誤認為接續。

先要求 Agent 呼叫 list_machines，再對兩個 ID 分別呼叫 inspect_machine。依 Machines 說明，lifecycle_state 是機器生命週期，connection_state 是連線狀態；active 仍可能同時 offline。executable 還會考慮綁定、專案授權與是否能連線或喚醒。

接著分別指定兩個 machine_id 執行 pwd 與 cat marker.txt。工具文件要求多機時以公開 ID 選機器；請保存工具參數中的 ID、回傳的 process_id、輸出與退出碼。兩邊標記刻意不同，是為了讓你看見：同一段對話可以碰到不同的檔案現場。

四、離線後到底接上什麼？分兩輪做中斷驗收

第一輪：只停 worker，保留控制平面儲存與執行機

先完成一個唯讀回合並記下最後事件，再在這套隔離測試堆疊執行 docker compose --profile app stop worker。送一則要求再次讀標記的輸入，核對同一 Agent 的歷史與活動；之後執行 docker compose --profile app start worker，觀察待處理工作與後續工具結果。這是有序停機演練，與程序遭硬中止的崩潰條件不同。不要同時停止資料庫或刪除 volume，否則你測到的已是另一種故障。

官方 崩潰復原測試程式另有一條更窄的證據：中止正在等待模擬模型回應的 worker、人為令租約過期，再由 maintenance 安排重試，讓第二個 worker 完成下一次嘗試。它使用模擬提供者與人工調整的租約，不是本文量出的恢復時間，也不能用來保證真實外部操作只發生一次。

第二輪：只讓 lab-a 離線，控制平面與 lab-b 保持可用

先確認兩台都在線，再在 A 執行 omnarad stop。要求同一 Agent 明確查 A 的狀態，再嘗試讀 A 的標記，記下拒絕、可重試錯誤或等待的實際結果。官方 Machines 文件說，離線機器上的新命令會失敗並帶可重試資訊；等待既有程序的工具呼叫，經寬限期後可得到可重試的 machine_unreachable。既有程序可能仍在機器上跑，不能把「失聯」直接翻譯成「程序已終止」。

接著給明確下一步：「A 離線時，請查 B 是否可執行；只在 B 讀取 marker.txt，回報機器 ID 與內容，缺檔就停。」批准前核對目標為 B。成功讀到 lab-b-only，證明命令改在 B 執行；它還沒有證明 A 的檔案已搬到 B。再於 A 執行 omnarad start，核對重新上線與兩張桌上的標記。

每次至少留七欄：Agent ID、事件序號、tool_call_id、machine_id、cwd、process_id／結果、檔案版本。事件文件把已保存事件與即時串流分開：tool_call_update 和逐字 delta 並非持久事件。重連後要讀時間線及目前工具狀態，不能只靠畫面曾經閃過的一行進度判定完成。

五、把檔案接上：Git checkpoint、memory 與附件各管哪一層？

假設 A 已修改一份程式，B 仍在昨天的版本。換機前，先在兩個工作目錄分別查 git rev-parse HEAD 與 git status --porcelain：前者是目前提交編號，後者讓你看見尚未提交的變更。這裡說的 Git checkpoint，是你自行選定並保存的一個提交；官方事件中的 context_checkpoint 則是對話摘要，兩者不要共用一個「存檔成功」判斷。

若要做程式接續，先在專用練習 repository 中，明確檢查並提交需要的測試檔，再推到兩台都有權存取的遠端。讓 B 取得該提交，核對提交 ID、工作樹狀態與測試檔內容；依賴、環境變數和權限也另查。相同提交 ID 仍要搭配乾淨工作樹，因為未提交檔與忽略檔可以不同。這一輪只用假資料，也不批准將整個個人目錄加入 Git。

小型成果可使用官方的 storage_upload 明確從指定機器送到 /artifacts，再用 storage_download 下載到另一台機器的指定位置；memory store 則適合附掛給 Agent 的持久筆記。它們各有檔案大小與權限條件，可沿 檔案工具說明核對。先選你需要搬的東西，再選搬法；不要從「Agent 還在」推論整個工作目錄已經同步。

六、常見問題：八個直接答案

1. 關掉瀏覽器，等於把 Agent 關掉？

不是同一件事。瀏覽器是客戶端；要查後端與 worker 是否仍運作，以及該 Agent 的事件和活動狀態。

2. 筆電離線，工作一定能在別處繼續？

不一定。控制平面要可用，另一台機器也要有綁定、授權、檔案與依賴；需要人批准的工作還會等待批准。

3. retryable 就代表系統一定會自動成功？

不代表。它標示這類錯誤可重試，成功仍取決於後續調度、模型決定與資源是否恢復。把實際結果和事件保存下來。

4. Postgres 有備份，就等於所有檔案都備份？

要分開查。架構另外使用物件儲存與 memory 檔案系統；官方部署頁也要求 memory 目錄連同 Postgres 備份。執行機的工作目錄另有自己的備份需求。

5. 裝好 daemon，就會隔離我的檔案？

不能這樣判定。命令由執行機帳號與系統權限約束；第一輪用可拋棄、低權限環境，逐次批准命令。

6. 可以保證重試不會重複寄信或寫資料？

這篇證據不足以做這個保證。先只測唯讀工作；日後接外部寫入時，用接收端的冪等機制與可查詢的業務編號避免重複效果。

7. 自架軟體免費，代表維運沒有費用？

不代表。官方程式採 Apache 2.0；模型用量、常駐主機、儲存、備份與執行機資源仍要各自支付或提供。

8. 完全不熟部署，先做哪一步？

先畫出控制平面與兩台工作桌，填出每一份資料住在哪裡。已有 Docker 環境的人，再完成一台機器的唯讀標記任務；成功後才加入第二台。

給新手的三個重點

• 先分角色：工單不住在工作桌裡，換調度員和換執行機是兩種接續。
• 再分證據：事件歷史、工具執行目標與檔案版本各留一份，從 ID 和內容核對。
• 最後分故障：一次只停一個元件，先測唯讀工作；每輪都有恢復步驟，才看得出接上的是哪一層。