【2026 最新】Nodeterm 教學：用 Worktree 管理 Claude Code、Codex 的 6 步流程

你同時開著 Claude Code、Codex 和三個 Terminal：一個正在改登入頁，一個卡在權限確認，另一個早已跑完測試。等你切回第一個視窗，才發現兩個 Agent 都碰了同一個 helper。這篇 Nodeterm 教學要解的不是「怎麼多開終端」，而是怎麼看見狀態、隔離工作、留下交接，最後安全合併。

本文專為剛開始使用 Coding Agent、只懂基本 Git 的讀者寫。以下以截至 2026 年 8 月 25 日的 Nodeterm v0.3.2 正式版、官方文件與固定版本原始碼為基準；不預設它一定比 tmux 快，而是給你一套可重跑的驗收方法。

Nodeterm 教學先說結論：它是視覺工作台，不是自動指揮官

Nodeterm 是把真實 Terminal 放到無限畫布上的桌面工作台。Claude Code、Codex 等 CLI 仍在自己的終端內執行；Nodeterm 額外提供 Canvas、Agent 狀態、通知、Git Worktree、Source Control、Context Link 與 Kanban。你可以把它想成「把 tmux 包成一間有白板、門牌與進度燈的控制室」。

全篇最重要的操作單位是：一個可控任務＝一張有驗收條件的卡片＋一個 Worktree＋一個 Agent 終端＋一份 diff／test／handoff 紀錄。畫布改善的是注意力與可觀測性；真正避免事故的仍是任務邊界、最小權限、測試與人工審查。想先補 Agent 的底層概念，可讀 AI Agent Harness 是什麼；要看實作結構，再接著讀 如何打造 AI Agent Harness。

Nodeterm 到底管理了什麼？先拆成 5 個零件

① Canvas：「把每個工作現場攤在桌上」

一個專案是一張 Canvas。你可以放 Terminal、Agent、Editor、Diff、Browser 與 Sticky Note 節點，再用群組框整理同一任務。官方 Quickstart 的基本路徑是開啟資料夾、加入 Terminal 或 Agent、替節點命名，再用縮放與分組整理畫布。

換句話說，Canvas 不會替你決定下一步；它只是讓「誰在改哪裡」不再藏在十個分頁後面。

② Agent 節點：「有門牌的真實終端」

Nodeterm 不代替 Claude Code 或 Codex。它會從登入 shell 的 PATH 找到你已安裝、已登入的 CLI，然後用真正的互動式終端啟動。兩者的能力也不完全相同：v0.3.2 的 Claude 節點有較多專屬視覺功能；Codex 仍以終端、hook 狀態與支援的工作台整合為主。若你還在選工具，先看 Claude Code vs Codex 完整比較。

③ Worktree 群組：「同一倉庫的獨立工作桌」

Git Worktree 讓同一個 repository 同時擁有多個工作目錄、HEAD 與 index，但共享 objects、refs 與多數 Git 設定。Nodeterm 可以把 Worktree 綁到群組框，框內新增的 Terminal、Agent 與 Editor 會繼承那個目錄。

Worktree 隔離檔案，不隔離一切。兩個任務仍可能共用 port、開發資料庫、migration、cache、外部 API 或架構契約。若兩個 Agent 都要改 schema、lockfile 或核心 helper，就算畫面完全分開，合併時仍可能語意衝突。

④ 狀態與通知：「誰需要你回來」

官方 狀態文件說明，Nodeterm 透過各 Agent 的 hook 把 working、waiting、blocked、done 正規化成畫面上的狀態，並可在應用程式未聚焦時發出需先允許的 OS 通知。因此正確表述是「hook 正常送達時可協助定位」，不是「通知永遠不漏」。

⑤ Context Link 與 Kanban：「拉取交接，不是自動灌腦」

Context Link 是拉取式通道：接收方需要時才讀取另一節點的上下文，不是把完整對話持續塞進每個 Agent。Kanban 則把 live session 變成卡片，讓你從 To Do、In Progress 到 Done 移動，並留下優先級、到期日與留言。它們適合交接，不代表 Agent 會自行協商責任邊界。

Nodeterm 教學第一步：選 Desktop 還是 Server Edition？

第一次使用，先選 Desktop。截至查核日，官方桌面版支援 macOS Apple Silicon／Intel 與 Linux x64；官方 FAQ 明確標示 Windows 尚未支援。Server Edition 則是把 Git、tmux、專案與 Agent CLI 都放在你自架的 Linux 主機上，再從瀏覽器連入，適合已會維護 TLS、VPN 與伺服器的人。

Desktop 安裝

最穩妥的方法是從 官方 Releases 下載符合晶片的 macOS 安裝檔，或 Linux AppImage／deb。macOS 也可使用官方 Homebrew tap：

brew tap nodeterm/tap
brew trust nodeterm/tap
brew install --cask nodeterm

brew trust 適用於 Homebrew 6 以上；若你的版本沒有這個指令，改走官方下載頁，不要用關閉系統安全檢查來硬繞。Linux 需讓 tmux 在 PATH；Claude Code、Codex 也要另外依 Anthropic 與 OpenAI 官方文件安裝並登入，可先用 claude auth status 與 codex login status 確認。

Server Edition 安裝

若你真的需要瀏覽器連入，請先固定正式版再建立 image；以下把 host port 只綁在本機，之後再用 HTTPS reverse proxy 或 VPN 轉入：

git clone --branch v0.3.2 --depth 1 https://github.com/eneskirca/nodeterm.git
cd nodeterm
docker build -t nodeterm-server .
docker run -d -p 127.0.0.1:8443:8443 \
  -e NODETERM_SERVER_PASSWORD='choose-a-strong-one' \
  -v nodeterm-data:/data \
  nodeterm-server

Server Edition 官方文件說明這是單一使用者設計，plain HTTP 是給 loopback 用；不要把 8443 直接公開到 Internet。Docker image 不內建 Agent CLI，container 重建也會終止當下 process；/data 保存的是資料與快照，不是讓 OS process 永生。瀏覽器版的 Chat node 與部分 canvas-control 能力仍未接線，不能當成桌面版的完整鏡像。

6 步建立「一任務一 Worktree、一 Agent 一終端」

第 1 步：從乾淨基線開始

先在主工作目錄跑過 baseline tests，確認 git status 乾淨並提交現有變更。未提交的變更混入 merge 時，Git 官方文件警告 git merge --abort 不一定能完整重建原狀。這一步看似慢，實際上是在替每個 Agent 建共同起跑線。

第 2 步：先寫任務卡，再建立 Worktree 群組

任務卡至少寫四件事：允許修改的範圍、禁止碰觸的檔案、驗收命令、交接格式。接著在 Canvas 建立 Worktree 並綁到 group frame，例如 feat-login-claude、test-login-codex。官方 Worktree v1 文件明示：SSH project 目前不支援這套 UI；Explorer 與 ⌘K 索引仍以主 project root 為準，查看綁定 Worktree 請用框內的 Terminal／Editor。

第 3 步：在群組內開 Agent，保留最小權限

在 group frame 內加入 Claude Code 或 Codex，然後先問它回報 pwd、目前 branch 與預計修改檔案。依 OpenAI 安全文檔，Codex 可維持 workspace-write／on-request 這類沙箱與按需批准；Claude 的 permission mode 與 sandbox 也是兩個不同控制層。畫布沒有替你提供 OS 沙箱，Worktree 也不會隔離憑證。更完整的控制觀念可搭配 AI Agent Runtime Controls 教學。

第 4 步：用狀態與通知抓回注意力

開啟 OS 通知後，故意讓一個 Agent 等待選項、一個執行測試、一個完成，確認 Canvas、sidebar 與通知是否一致。通知只在 Nodeterm 未聚焦時發送，所以前景與背景都要測。若狀態沒有更新，先檢查 hook 與 CLI 版本；不要因為一個綠點就假設 process 一定健康。

第 5 步：用 Context Link 做窄交接

只連結真正有依賴的兩個節點，並在 prompt 明確要求「先讀取 A 的公開介面與測試結果，不要改 A 的檔案」。截至 2026 年 8 月 25 日，v0.3.2 曾在 Codex 預設網路沙箱下出現 loopback 被擋的官方回報；修正於 8 月 23 日合併到 main，但晚於最新正式版。若你仍用 v0.3.2，先以手動貼上 handoff 代替，不要為了單一連線功能全域開啟 danger-full-access。

第 6 步：Kanban 只負責派工，Git 才負責合併

按 ⌘⇧B 切到 Board，把 session 移到 In Progress 或 Done。完成卡必須附上：變更檔案、測試命令與結果、尚未驗證的假設、資料庫／設定變動、建議合併順序。合併前人工看 diff、重跑測試，再按依賴順序整合；先合併提供介面或 schema 的 branch，再讓依賴方更新基線。

衝突怎麼復原？先保存，再決定合併或中止

在可丟棄的 toy repo 讓兩個 Worktree 修改同一行並各自 commit，是最好的故障注入。執行期間，兩邊不應互相覆寫；合併時，Git 應明確顯示 conflict。遇到衝突先停下來：

git status
git diff --name-only --diff-filter=U

# 若決定回到 merge 前，而且起始工作區原本乾淨
git merge --abort

# Worktree 路徑失聯時先檢查，不要直接強制刪除
git worktree list
git worktree repair

不要先刪 Worktree，也不要讓 Agent 自動選「接受全部 ours／theirs」。先保存 commit 或 patch，確認 base branch 未被意外改動，再人工解衝突、重跑 tests。若多 Agent 的價值仍讓你疑惑，可參考 三個 Agent 是否真的勝過一個；平行數量本身不是品質保證。

Nodeterm vs tmux：你真正要比較的是注意力成本

選 Nodeterm：你同時使用多種 CLI、經常漏看等待輸入、希望用畫布與 Kanban 管理交接，而且願意接受較新的產品與較大的整合面。

留在 tmux：你通常只有 2–3 個 session、熟悉 window 命名與 shell、自動化需求高，或遠端 SSH、跨平台與低依賴比圖形介面更重要。

兩者混用：這其實最自然。Nodeterm 的終端持續性本來就建立在 tmux 上；你可以讓它負責視覺掃描，必要時仍用 tmux ls、Git 指令與測試做底層核對。

用 A/B 驗收，而不是靠「看起來更有效率」

準備一個不含 secrets、可隨時刪除的 toy repo。A 組使用 Nodeterm，B 組使用 tmux＋手動 Worktree；兩組固定相同電腦、Agent 版本、權限與三個小任務。記錄建立 session 的時間、錯誤目錄次數、漏看等待狀態、衝突是否被明確攔下、重啟後的恢復時間。沒有固定控制條件，就不能把任務差異誤認成工具優勢。

如果只有兩個 session，而且 B 組同樣不漏通知、不走錯目錄、恢復更快，那就誠實留在 tmux。Nodeterm 的價值是降低你自己的注意力切換，不是保證每個人都能得到同一個效率數字。

版本、授權與安全：上手前一定要知道的 4 件事

1. 正式版與 main 分開看：截至查核日最新 release 是 2026 年 8 月 17 日的 v0.3.2；8 月 24 日的 main 已多出數百個 commits。Issue 關閉不等於你下載的 binary 已含修正。
2. 持續性不等於 process 永生：依終端持續性文件，關閉視窗後 tmux session 可繼續；電腦 reboot 或 container redeploy 仍會終止 process。Nodeterm 最多還原 scrollback 並嘗試 resume Agent session。
3. BUSL-1.1 不是傳統開源授權：正式版 LICENSE 顯示它目前是 source-available。Additional Use Grant 允許一般 production use，但禁止提供與 Nodeterm／授權人產品競爭的 hosted、embedded 或 standalone 商業產品；每個版本在發布四年後各自轉 MIT。商業代管或嵌入前應直接確認授權。
4. 工作台擴大了信任面：除了 Agent provider，你也在信任 Electron app、hooks、tmux，以及選用的 relay／server。安裝前後應備份並 diff CLI 設定，確認原有安全 hook 仍會觸發。

Nodeterm 常見問題 FAQ

1. 完全不會程式也能用嗎？

不建議直接多 Agent 開跑。你至少要看得懂 branch、commit、diff、test 與 conflict；Nodeterm 降低的是管理門檻，不會替你判斷程式是否正確。

2. Nodeterm 可以完全取代 tmux 嗎？

不一定，也沒有必要。它的終端持續性本來就使用 tmux；圖形工作台與底層工具可以同時存在。

3. 一任務一 Worktree 就不會衝突嗎？

不能保證。它避免執行時直接覆寫同一工作目錄，但 DB、port、migration、依賴版本與設計契約仍可碰撞。

4. Claude Code 與 Codex 在裡面功能一樣嗎？

不一樣。兩者都能作為真實 CLI 節點執行，但 v0.3.2 的進階視覺與工作台能力並非全部對等，權限旗標也不同。

5. Context Link 失敗時要關掉 Codex 沙箱嗎？

不要全域關閉。先確認版本與錯誤是否來自 loopback 限制；保留手動 handoff，或只批准精確命令。修正進入正式 release 後再重新驗收。

6. Windows 可以安裝 Nodeterm Desktop 嗎？

截至 2026 年 8 月 25 日，官方 FAQ 標示不支援。不要把 Claude Code 或 Codex 本身支援 Windows，誤解成 Nodeterm Desktop 也已支援。

7. Server Edition 可以直接開 port 給團隊嗎？

不行。它是單一使用者密碼設計，plain HTTP 只適合 loopback；外部存取至少要有 TLS reverse proxy 或 VPN，也不能把它當成角色權限系統。

8. Nodeterm 是免費開源軟體嗎？

「原始碼可看」不等於目前採 OSI 開源授權。Nodeterm 使用 BUSL-1.1，個別版本四年後才轉 MIT；商業競爭用途另有限制。

給新手的 6 個重點

1. 先從兩個任務開始，不要一上來就開十個 Agent。
2. 每張卡都要綁定 Worktree、驗收命令與 handoff。
3. Worktree 只隔離檔案；port、DB、secret、cache 要自己命名分流。
4. 狀態燈與通知是提示，不是健康證明。
5. 任何合併都要人工看 diff、重跑 test，先處理依賴順序。
6. 用 toy repo 做 A/B；如果 tmux 已經夠好，就不必為了新工具改流程。