NemoClaw 企業級 AI Agent 沙盒參考堆疊教學手冊(實戰與維運)

一句話定位:NVIDIA NemoClaw 是一套「把受支援的 AI Agent 裝進 NVIDIA OpenShell 沙盒」的開源參考技術堆疊。它提供引導式安裝(onboarding)、版本化 Blueprint、託管推理路由、網路政策 preset、狀態保存與生命週期指令;真正執行隔離、攔截網路、保管憑證的是底下的 OpenShell。NemoClaw 讓你「少做整合工作」,不會讓 Agent「自動變安全」。

適用對象:資深工程師、架構師、DevOps/DevSecOps、資安與維運人員、AI 平台管理者。PM、SA、SD 可依「閱讀路徑」選讀。內容偏實戰與維運,假設讀者熟悉 Linux、Docker、Git,以及至少一種 AI Coding 工具。

版本基準:

項目內容
NemoClaw 版本v0.0.139(tag commit a08ae7a,2026-10-26);官方文件站 latest 已對應此版
安裝程式預設版本官方安裝程式預設追蹤 lkg(last known good)標籤,研究當日指向 v0.0.137(f00fb1d,2026-10-21);要用 v0.0.139 必須明確指定 NEMOCLAW_INSTALL_TAG=v0.0.139(第 4 章)
搭配的 OpenShell0.0.116(Blueprint 的 min_openshell_version 與 max_openshell_version 都是 0.0.116;@nvidia/openshell-sdk 也釘 0.0.116)
支援的 AgentOpenClaw(預設)、Hermes、LangChain Deep Agents Code(dcode 0.1.71);三者在官方平台矩陣皆為 Tested,但 Hermes 官方註明「尚未宣稱與 OpenClaw 的正式環境同等」
專案階段alpha/Early preview(官方平台矩陣:自 2026-03-16 起),維護者以 best effort 回應、無 SLA
原始碼核對NVIDIA/NemoClaw tag v0.0.139:docs/(官方文件原始檔)、install.sh、scripts/install-openshell.sh、nemoclaw-blueprint/(Blueprint 與政策)、agents/*/(各 Agent 的 manifest 與政策)、src/lib/(CLI 實作)
研究基準日期2026-10-27;main 追蹤至 bafe6cc(2026-10-26,領先 v0.0.139 共 18 個 commit);另有 Rust 重寫的 v1 分支(見 1.7)。1.1 版於同日再核對:沒有新 tag,lkg 仍指向 v0.0.137,main 仍為 bafe6cc(18.11)
實測狀態未在實機安裝 NemoClaw 或 OpenShell。所有 NemoClaw/OpenShell 指令都對照 v0.0.139 官方文件與原始碼,標 📖;需要實際環境才能確認的內容標 🧪 並附驗證步驟。手冊內附的 5 支企業自訂審查工具(政策 lint、交付報告比對、架構依賴檢查、逆向工程引用檢查、測試弱化檢查)、安全公告版本下限腳本與 ArchUnit 範例,已在撰寫環境以合成資料實測,標 ✅
撰寫環境Windows 11 Pro 10.0.26300、Python 3.12.8、PyYAML 6.0.3、OpenJDK 21.0.4、Maven 3.9.9、Node.js 24.16.0(僅用於撰寫與驗證審查工具)
手冊版本1.1(2026-10-27;1.0 於同日初版;版本紀錄見 18.13)

文件性質:企業內部教育訓練與開發規範。內容為重新整理、分析與教學化撰寫,不是官方文件翻譯。範例中的主機名稱、帳號、Token、IP、專案與客戶資料均為虛構(使用 example.com、corp.example、10.x 等保留或私有範圍)。


重要聲明(請務必先讀)

  1. NemoClaw 不等於 OpenShell。 NemoClaw 是「參考堆疊」:主機端 CLI(nemoclaw/nemohermes/nemo-deepagents)、Agent 整合層、版本化 Blueprint、政策 preset 與生命週期流程。OpenShell 是「執行環境」:Gateway、沙盒、L7 代理、政策執行、憑證保管。NemoClaw 呼叫 OpenShell 的 API 與 CLI 來建立並設定沙盒,兩者的版本、責任與故障點都不同(第 1、2 章)。
  2. NemoClaw v0.0.139 搭配的是 OpenShell 0.0.116,不是 OpenShell 最新版 v0.1.5。 同目錄《OpenShell 教學手冊》以 v0.1.5 為基準;兩個版本線在推理路由(inference.local 在 OpenShell 0.1.0 移除,但 NemoClaw 0.0.139 仍會用到)、CLI 參數與政策行為上有差異。在 NemoClaw 管理的環境裡,不要套用 OpenShell v0.1.x 的指令或自行升級 OpenShell;官方明確要求用 nemoclaw onboard 管理 Gateway 與沙盒,避免直接執行 openshell self-update 或 openshell sandbox create(第 1.9、12 章)。
  3. 這是 alpha 專案。 官方平台矩陣標示 Stage: alpha、Label: Early preview,介面可能在版本間變動,沒有 SLA。官方「Enterprise Readiness」頁明說:NemoClaw 是「單一主機、單一受信任操作者」的參考工作流程,不是多租戶企業控制平面、沒有操作者 RBAC、沒有 SSO 整合、不支援離線(air-gapped)安裝。本手冊所有企業建議都以「隔離的非正式環境+明確風險接受」為前提(第 13、14 章)。
  4. 沙盒不是絕對安全。 官方安全頁的原則是:每一個放行的端點都是可能的資料外洩路徑。沙盒能限制 Agent 碰得到的檔案、程序與網路,但不會判斷 Agent 產出的程式碼是否正確,也不會阻止 Agent 透過已放行的端點(例如 Deep Agents 預設就放行的 github.com)把資料送出去(第 6 章)。
  5. 安裝程式預設會送出匿名遙測。 官方文件寫明:安裝程式與 CLI 預設會嘗試把匿名的操作完成遙測送到 NVIDIA 的固定接收端;要停用,必須在每一個執行 NemoClaw 的 shell 先 export NEMOCLAW_DISABLE_TELEMETRY=1。企業環境應把這一行寫進標準作業程序(第 4 章)。
  6. curl … | bash 必須先下載審查、再固定版本執行。 官方安裝程式會下載並執行來自 GitHub 的腳本,可能安裝 Node.js、Docker(以 sudo 執行 Docker 官方便利腳本)並把使用者加入 docker 群組。docker 群組成員對 Docker daemon 有等同 root 的影響力。不得要求同仁盲目執行(第 4.3 節)。
  7. AI 說「完成了」不是證據。 本手冊每個開發、逆向、升級流程都要求可重跑的驗證:政策用 lint 與拒絕測試驗證、程式碼用測試與人工審查驗證、交付報告用 git diff 比對驗證(第 6、7、8、9、10 章)。
  8. 下一版 NemoClaw 很可能改綁 OpenShell 0.1.5。 main 上的 PR #12603(研究日狀態 OPEN,PR 自述 Not ready for approval or merge)要把 OpenShell runtime 與 SDK 從 0.0.116 升到 0.1.5。發布後,推理路由、Gateway 設定、volume 與復原流程都會改變,舊沙盒的 volume 也不會自動複製。核准新版之前,一律照 12.11 在測試主機演練(第 12 章)。
  9. 舊版本有已公告的高風險漏洞。 NVIDIA 在 2026-08-25 發布 Security Bulletin 5872,一次公告 18 個 NemoClaw/OpenShell CVE,最高為 CVSS 9.9 的沙盒逃逸。本手冊的基準版本(v0.0.139/OpenShell 0.0.116)已在修補範圍之後,但企業要盤點每台主機的實際版本,並訂閱後續公告(6.17)。

標記圖例

標記意義
📖已對照 v0.0.139 官方文件或原始碼,但作者未在實機執行
🧪尚待實際環境驗證:官方文件未明確說明、或結果取決於你的主機與映像檔;附驗證步驟
⚠️官方文件之間有落差、版本差異大,或屬實驗性(Experimental)功能
🏢本手冊的企業建議或自行設計的流程,不是 NemoClaw/OpenShell 原生功能
⛔禁止事項、官方不支援或已淘汰的功能
✅ 已實測作者已在撰寫環境以合成資料實際執行(只限手冊中的審查工具與範例程式,不含 NemoClaw 本身)

執行位置標記(每個指令區塊前都會標示):

標記執行位置
🖥️ Host執行 NemoClaw 的主機終端機:Linux(Ubuntu 24.04 為主要驗證路徑)、Apple Silicon macOS,或 Windows 上的 WSL 2 Ubuntu
🐧 WSLWindows 上的 WSL 2 Ubuntu 內部;NemoClaw 在 Windows 上的所有指令都在這裡執行(與 🖥️ Host 相同,特別標示時代表 Windows 情境)
🪟 PowerShellWindows 原生 PowerShell(只用於 WSL 2、Docker Desktop 的前置準備)
📦 Sandbox沙盒內部(nemoclaw <名稱> connect 進入後的 shell,或 nemoclaw <名稱> exec -- 執行的指令)
🔧 CICI/CD Runner(GitHub Actions、GitLab CI、Jenkins 等),在沙盒外執行

審查方塊(教你檢查 AI 產出時使用):

標記意義
❌ 壞例AI 常見的錯誤產出,只用於審查訓練,不得複製使用
🔍檢查方法:用指令或腳本找出問題
▶️驗證指令與預期結果

⚠️ 警告:會造成安全風險、資料遺失或權限擴大的事項。

✅ 建議:本手冊推薦的做法。

📌 註記:補充說明、版本差異或來源。

指令中的名稱慣例

  • 官方 CLI 有三個入口:nemoclaw(預設 OpenClaw)、nemohermes(預設 Hermes)、nemo-deepagents(預設 LangChain Deep Agents Code)。三者共用同一套子指令,只是預設 Agent 不同。本手冊以 nemoclaw 示範;Deep Agents 專屬內容改用 nemo-deepagents。
  • 沙盒操作採「沙盒名稱在前」的文法:nemoclaw <沙盒名稱> <動作>,例如 nemoclaw my-assistant status。全域指令不帶名稱,例如 nemoclaw status、nemoclaw doctor。
  • 範例沙盒名稱:my-assistant(OpenClaw)、dev-order(Deep Agents,開發用)、re-legacy(Deep Agents,逆向工程用)。名稱規則見 4.5。

閱讀路徑

角色必讀選讀可略過
初學者(第一次接觸)1、2、3、4、175、1114、15
資深工程師(要實作)1.7~1.9、4~9、11、1610、1215
架構師(做技術決策)1、2、6、7.1~7.3、149、10、124.8~4.11 細節
資安/DevSecOps1.4~1.6、2.4、3.6、6、1310、11、147~9 的 Prompt 細節
維運人員3、4、5、11、126.12~6.147~9
主管/治理重要聲明、1.5~1.8、13、14.11~14.12、15104~9 的指令

目錄

第1章 NemoClaw 概論

本章回答四個問題:NemoClaw 是什麼、它和 OpenShell/Agent/模型是什麼關係、它能替企業解決什麼、以及它還不能做什麼。讀完本章,你應該能用三句話向主管說明 NemoClaw 的定位,並判斷你的情境適不適合導入。

1.1 設計目的與核心價值

官方 README 的定義是:an open source reference stack for running supported AI agents more safely inside NVIDIA OpenShell sandboxes(在 OpenShell 沙盒中更安全地執行受支援 AI Agent 的開源參考堆疊)。拆開來看,有三個關鍵字:

關鍵字意思對企業的意義
reference stack(參考堆疊)NVIDIA 把「哪個映像檔、哪些預設政策、怎麼接推理服務、怎麼升級」整理成一套可重複的組合不用每個團隊自己拼 Docker、政策 YAML、憑證注入;但也代表你接受它的預設設計
supported agents(受支援的 Agent)只有 OpenClaw、Hermes、LangChain Deep Agents Code 有整合層Claude Code、Codex、Copilot CLI 等不在 NemoClaw 的支援清單內(OpenShell 本身可以跑,但那是「OpenShell 路徑」,見 1.8)
more safely(更安全地)相對於「直接在主機跑 Agent」更安全,不是「保證安全」仍需企業的行政規範、人工審查與 CI 驗證

NemoClaw 提供的能力,官方歸納為六類:

能力具體內容狀態
執行受支援的 Agent依 Agent 建立專屬的沙盒映像檔與設定Tested
推理路由把模型呼叫交給 OpenShell 管理的路由,憑證留在沙盒外Tested
沙盒存取控制透過 OpenShell 套用網路、檔案系統、程序與推理政策Sandboxed execution 為 Tested with limitations
生命週期主機就緒檢查、建立/更新、狀態與日誌、保留原生 home 的重建與復原Tested
託管 MCP以 HTTPS Streamable HTTP 連接需驗證的 MCP Server,憑證由 OpenShell 在出口替換Tested
Agent Skills 與文件提供給 Coding Agent 讀的 Markdown 文件與 skill(.agents/skills/)Tested

來源:NemoClaw README、Overview、Platform Support — Capabilities

1.2 NemoClaw、OpenShell、Agent、LLM、推理服務與工具的關係

很多導入失敗,來自把這幾層混為一談。下表用「誰負責什麼」來區分:

層代表元件負責不負責
操作者你(開發者/維運)選 Agent、選模型、核准網路請求、放寬政策、輪替憑證—
參考堆疊NemoClaw 主機 CLI、Blueprint、整合層、preset安裝、onboarding、驗證 Provider、記錄狀態、重建與升級流程隔離本身、政策執行、模型推理
執行環境OpenShell Gateway、沙盒、L7 代理網路命名空間隔離、CONNECT 代理、政策執行、TLS 終結、憑證替換、推理路由判斷 Agent 行為是否合理
AgentOpenClaw、Hermes、Deep Agents Code(dcode)Agent 迴圈、工具呼叫、skill、記憶、沙盒內設定定義沙盒或 Gateway
模型Nemotron、GPT、Claude、Gemini、Qwen 等 LLM依提示產生文字與工具呼叫遵守企業規範(它只會「傾向」遵守)
推理服務NVIDIA Endpoints、OpenAI、Anthropic、OpenRouter、Ollama、vLLM、NIM執行模型、計費、限流、資料處理政策沙盒內的任何控制
工具Git、Maven、npm、MCP Server、瀏覽器、Shell實際讀寫檔案、連網、建置判斷操作是否被授權(由 OpenShell 政策決定)
flowchart TB
    OP["操作者<br/>選擇與核准"]
    NC["NemoClaw<br/>主機 CLI、Blueprint、preset"]
    OS["OpenShell 0.0.116<br/>Gateway、L7 代理、政策、憑證"]
    SB["沙盒<br/>Agent 與工具"]
    INF["推理服務<br/>NVIDIA、OpenAI、本地 vLLM 等"]
    EXT["外部服務<br/>Git、套件庫、MCP"]
    OP -->|"onboard、policy、rebuild"| NC
    NC -->|"呼叫 API 與 CLI"| OS
    OS -->|"建立並隔離"| SB
    SB -->|"所有請求"| OS
    OS -->|"核准的推理請求<br/>出口替換憑證"| INF
    OS -->|"核准的端點"| EXT
    OP -.->|"openshell term 核准或拒絕"| OS

📌 註記:官方 Ecosystem 頁的說法是「NemoClaw sits above OpenShell in the operator workflow」——NemoClaw 在操作流程上位於 OpenShell 之上,呼叫 OpenShell 的 API 與 CLI 來建立和設定沙盒。模型與端點則位於 OpenShell 的推理路由之後。

1.3 為什麼自主 Agent 需要檔案、網路、程序與憑證限制

官方 Overview 的原文是:自主 Agent 可以發出任意網路請求、存取主機檔案系統、呼叫任何推理端點;沒有控制時,風險會隨 Agent 無人看管的時間而累積。換成企業語言,四類限制各自防的是:

限制沒有限制時的典型事故NemoClaw/OpenShell 的對應控制
檔案Agent 讀到 ~/.ssh/、~/.aws/、其他專案原始碼;誤刪主機檔案沙盒只看得到自己的 /sandbox;系統路徑唯讀;Landlock 核心層限制(核心 5.13 以上)
網路被 Prompt Injection 誘導,把程式碼 POST 到攻擊者網站;下載惡意套件Deny-by-default 出口、依程式身分(binary)放行主機/方法/路徑;未知請求需操作者核准
程序以 root 提權、利用 setuid、fork bomb 拖垮主機非 root sandbox 使用者、no-new-privileges、seccomp、ulimit -u 512(best effort)
憑證API Key 被寫進對話、記憶檔或 commit;被外洩後持續盜用推理與 MCP 憑證存在 OpenShell Gateway,沙盒內只有 placeholder,於核准端點出口才替換

⚠️ 警告:這四類控制都不處理「Agent 產出的內容」。Agent 在 /sandbox 內寫出含有後門的程式碼、或在已核准的 github.com 上開一個公開 repo 推送程式碼,這些都在沙盒的允許範圍內。內容層的風險要靠第 10、13 章的人工審查與 CI 驗證。

1.4 NemoClaw 與直接在主機執行 Agent 的差異

比較面向直接在主機執行 Agent使用 NemoClaw / OpenShell
執行環境以開發者帳號直接執行,與 IDE、瀏覽器、其他專案共用同一個作業系統環境每個 Agent 在獨立的 OpenShell 沙盒(容器)中,以 sandbox 使用者執行;映像檔以 @sha256 digest 固定,移除了 gcc、make、netcat 等工具
檔案存取看得到開發者能看的所有檔案(家目錄、憑證檔、其他 repo);只能靠 Agent 自身的權限設定或提示自律只能寫 /sandbox、/tmp 等少數路徑;/usr、/etc 等唯讀;Landlock 在核心層執行(OpenClaw 為 best_effort,Deep Agents 為 strict);主機目錄只能以 --host-mount 唯讀掛入
網路存取繼承主機所有網路能力;企業通常只能靠 Proxy 或防火牆做粗粒度控制Deny-by-default;政策以「主機+連接埠+HTTP 方法+路徑+發起程式」放行;未列出的請求被攔截並出現在 openshell term 等候核准;另有 SSRF 防護封鎖迴環、link-local、雲端 metadata
憑證管理API Key 放在環境變數或設定檔,Agent 可直接讀取、可能寫入記錄或 commit推理、MCP、Web Search、訊息通道憑證存於 OpenShell Gateway;沙盒內只看到 placeholder;NemoClaw 會從建立沙盒的指令中過濾敏感環境變數
模型推理Agent 直接呼叫任意模型端點,誰的 Key、哪個端點、花多少錢都在 Agent 手上由 onboarding 驗證 Provider 與模型後建立受控路由;附掛式 Provider 只允許特定主機、路徑與程式(例如 NVIDIA Endpoints 只允許 GET /v1/models、POST /v1/chat/completions)
狀態管理對話、記憶、設定散落在家目錄,升級 Agent 時可能遺失或互相污染Agent 原生 home/workspace 由 OpenShell 保存;重建(rebuild)時 NemoClaw 會封存、完整性檢查並還原整棵樹;憑證不在封存範圍內
維運與稽核幾乎沒有統一的狀態、日誌與健康檢查;事後很難重建「Agent 做過什麼」host probe、status、logs、doctor、debug 提供一致的檢查入口;openshell term 顯示即時網路活動;但沒有集中式 SIEM 匯出與多主機管理(官方列為手動或規劃中)

📌 註記:表中「使用 NemoClaw / OpenShell」欄的每一項,都依賴主機是否支援對應機制。例如 macOS 的 Docker VM 核心若不支援 Landlock,檔案系統限制會靜默降級為只靠容器掛載(官方 Troubleshooting「Landlock filesystem restrictions silently degraded」)。不要把這張表當成所有平台都成立的保證。

1.5 優點、限制、導入成本與適用邊界

優點:

  • 少寫整合:一條 nemoclaw onboard 就完成 Gateway、Provider、映像檔、政策與沙盒;不需要自己維護 OpenShell 政策檔與憑證注入。
  • 預設就比自己拼的嚴格:Blueprint 在 OpenShell community 沙盒之上再收斂政策、移除工具鏈、固定映像檔 digest、過濾敏感環境變數。
  • 生命週期有交易保護:重建前先封存並驗證原生 home,失敗可續作(--resume)。
  • 政策可審查:preset 是 YAML、可版本控管、套用前會預覽將開放的端點。

限制(官方明列,非本手冊推測):

限制官方狀態影響
單一主機、單一受信任操作者Product Scope不能當成多人共用的平台;多使用者主機被視為風險
無操作者 RBACOut of scope誰能在主機上執行 nemoclaw,誰就能改政策、看日誌
無 SSO/OIDC/SAMLRoadmap-onlyDashboard 與 Agent Gateway 用裝置配對或 bearer token
無多租戶隔離Out of scope不同客戶、不同敏感等級的專案不應共用同一台主機
無集中稽核與 SIEM 匯出Manual or admin-only需自行匯出 OpenClaw session JSONL 或 Hermes state
無成本控管Platform or partner-owned預算與限流要在推理服務端設定
不支援離線安裝Unsupportedonboarding 需要連外下載套件、映像檔與驗證 Provider
只支援 Ubuntu/Debian 系 LinuxUnsupported(其他發行版)安裝程式假設 apt-get;RHEL 系、Fedora 未驗證
不支援原生 Kubernetes/OpenShiftUnsupported沙盒以 Docker 容器執行,不是 K8s Pod

導入成本(🏢 本手冊估計的面向,不是官方數據):

成本項目說明
主機資源每台至少 4 vCPU/8 GB RAM/20 GB 磁碟(建議 16 GB/40 GB);本地模型另計 GPU 與記憶體
推理費用雲端推理依 token 計費,無人看管的 Agent 會持續累積(官方 Provider Trust Tiers 也提醒此風險)
網路治理每個新端點都要走白名單申請與審查(第 13.4 節)
版本追蹤官方約每週發布,且 OpenShell 版本被 NemoClaw 釘住;需要專人追蹤 release notes
教育訓練同仁要學會 sandbox-first CLI、政策審查、openshell term 核准流程

1.6 Alpha 階段對企業導入、相容性與維運的影響

面向Alpha 代表什麼企業因應(🏢)
介面穩定性官方 Enterprise Readiness:interfaces can change between releases;例如 nemoclaw setup、setup-spark、全域 start/stop 已標示淘汰把 NemoClaw 版本固定在已驗證的 tag;升級前在測試主機演練(第 12 章)
版本相容性每個 NemoClaw 版本只接受特定 OpenShell 版本範圍(v0.0.139 是 0.0.116~0.0.116)禁止單獨升級 OpenShell;以 NemoClaw 安裝程式整組升級
支援best effort、無回應時限、無 SLA內部指定窗口;問題先查官方 Troubleshooting 與 GitHub Issues
功能成熟度同一功能在不同 Agent/平台成熟度不同(Tested/Tested with limitations/Experimental/Deferred)對外或對主管描述能力時,引用平台矩陣的原文狀態,Tested with limitations 不等於 Tested
資料安全DGX Spark Playbook 明言「只在乾淨環境執行,不放個資、機密或敏感憑證」只用合成資料與非正式專案試行(第 14、16 章)

1.7 兩條產品線:v0.0.x(現行)與 v1(開發中)

研究時 NemoClaw 儲存庫同時存在兩條互不相干的程式線(git 比對顯示兩者沒有共同祖先):

項目v0.0.x 線(本手冊主體)v1 線(預覽)
分支/標籤main;正式標籤 v0.0.120~v0.0.139v1 分支;標籤 v0.1.0-rc1~rc9、v1.0.0-rc1
實作TypeScript/Node.js CLIRust CLI 與 Rust SDK,內嵌 OpenTofu
操作模型互動式 onboarding 精靈+sandbox-first 指令宣告式 desired-state YAML:plan、apply、export、destroy
搭配 OpenShell0.0.116versions.json 記錄 0.1.4
官方定位文件站 latest、安裝程式預設README:「This branch documents v1 development using source-built bundles」;docs/overview.md:「v1 has no support policy or enterprise deployment qualification yet」
銜接nemoclaw config export <沙盒> 可把現有沙盒匯出成 nemoclaw.nvidia.com/v1alpha1 的 NemoClawConfig YAML(不含憑證值)讀取上述 YAML

⚠️ 警告:網路上看到 nemoclaw plan、nemoclaw apply 或 v1.0.0-rc1 的教學,屬於 v1 預覽線,指令與本手冊的 v0.0.x 不相容。v1 的 CLI 沒有 Agent 呼叫、訊息通道管理與快照指令(v1 docs/overview.md)。本手冊不教 v1 操作,只在第 12 章說明如何為未來遷移保留設定。

v1 線仍在密集開發:研究當日 v1 分支(c2a71f8)還有新提交,內容包括 Kubernetes/OpenShift 部署指南的補充,以及 Rust 依賴的安全修補。開發活躍不代表可以上線,官方定位仍是「沒有支援政策」。

自己確認 v1 的狀態(🖥️ Host,唯讀;✅ 研究日實際執行):

# v1 分支最新提交與預覽標籤
git ls-remote https://github.com/NVIDIA/NemoClaw.git refs/heads/v1 'refs/tags/v1*'
# 官方定位是否仍是「沒有支援政策」
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/v1/docs/overview.md \
  | grep -io "v1 has no support policy[^.]*"
輸出判讀
grep 印出 v1 has no support policy or enterprise deployment qualification yet仍是預覽,企業不導入
grep 沒有輸出官方用語變了:讀新版 overview.md,再重新評估是否值得試行
出現 refs/tags/v1.0.0(沒有 -rc)第一個正式標籤出現,平台管理者應排入評估

1.8 適合與不適合使用的情境

適合:

情境理由
在隔離的開發主機評估 AI Agent 能力官方 Use Case「Controlled agent evaluation」:先用明確的檔案與網路邊界測試 Agent 行為
讓 Coding Agent(Deep Agents Code)在受控環境閱讀與修改非正式專案程式碼與憑證被隔離,網路只開必要端點
逆向工程舊系統(原始碼唯讀掛入)--host-mount 只提供唯讀,Agent 無法改到原始檔
需要託管 MCP、但不想把 Token 放進 Agent 設定託管 MCP 只存憑證名稱,值由 OpenShell 在出口替換
在遠端 Linux 主機以 SSH 操作的無頭伺服器官方 Headless Linux server 路徑(Tested with limitations)

不適合:

情境理由替代方案(🏢)
正式環境、處理真實客戶資料的工作負載alpha、無 SLA、無 RBAC/SSO/多租戶等待正式版與企業驗證;先在非正式環境累積證據
多位同仁共用一台主機官方不支援多使用者主機共用一人一台(或一人一個 VM)
需要 Claude Code、Codex、Copilot CLI 等 AgentNemoClaw 只整合三個 Agent改走「OpenShell 路徑」,參考同目錄《OpenShell 教學手冊》
完全離線的機房官方不支援 air-gapped改用內部私有模型+其他隔離方案
RHEL、Rocky、Fedora 主機安裝程式假設 apt-get使用 Ubuntu 24.04 VM
K8s/OpenShift 叢集內統一部署官方不支援評估 OpenShell 的 K8s 部署(需自行整合)

1.9 與《OpenShell 教學手冊》的分工與版本差異

同目錄的《OpenShell 教學手冊》以 OpenShell v0.1.5 為基準,講的是「自己用 OpenShell 跑任何 Agent」的路徑。本手冊講的是「用 NemoClaw 跑三個受支援 Agent」的路徑,搭配 OpenShell 0.0.116。兩者的差異會直接影響指令能不能用:

主題OpenShell v0.1.5(OpenShell 手冊)NemoClaw v0.0.139 環境(OpenShell 0.0.116)
inference.local0.1.0 起移除仍存在,部分推理選項使用共享路由 inference.local(2.6)
建立沙盒openshell sandbox create一律用 nemoclaw onboard;直接用 OpenShell 建立的沙盒不受 NemoClaw 管理
升級 OpenShell依 OpenShell 發行說明⛔ 不可單獨升級;超出 max_openshell_version 時 onboarding 直接失敗
政策檔直接編輯並 openshell policy set優先用 nemoclaw <名稱> policy add(preset);openshell policy set 只在 preset 無法表達時使用,而且是整份替換(6.13)
網路核准openshell term相同,openshell term 仍是核准介面

✅ 建議:讀 OpenShell 手冊是為了理解底層原理(Landlock、L7 代理、Provider);在 NemoClaw 主機上操作時,以本手冊與 NemoClaw 官方文件為準。遇到兩本手冊說法不同時,以 NemoClaw v0.0.139 文件與 OpenShell 0.0.116 行為為準。

📌 註記:如果 NemoClaw 改綁 OpenShell 0.1.5(PR #12603),上表兩欄的差距會變小,但「從 0.0.116 遷移到 0.1.5」本身就是高風險變更。新版發布後,先讀 12.11 的影響分析,再決定什麼時候換。

1.10 本章實務案例與注意事項

案例:主管問「我們可以讓全部門用 NemoClaw 寫正式系統嗎?」

建議回答(三句話):

  1. NemoClaw 是 NVIDIA 的 alpha 參考堆疊,能把 AI Agent 關在 OpenShell 沙盒裡,限制它碰得到的檔案、網路與憑證,但它不審查 Agent 寫出來的程式碼。
  2. 官方定位是「單一主機、單一受信任操作者」,沒有 RBAC、SSO、多租戶與 SLA,所以現階段只適合隔離的非正式環境試行。
  3. 建議依第 14 章五階段計畫,先由 2~3 位資深同仁在獨立主機以合成資料驗證,用第 15 章的指標決定是否擴大。

注意事項:

  • 描述 NemoClaw 能力時,引用官方平台矩陣的狀態字樣(Tested/Tested with limitations/Experimental),不要自行升級成「已支援」。
  • NemoClaw 版本、lkg 標籤、OpenShell 釘選版本會變動;每次引用前先核對第 12.2 節的版本盤點結果。
  • 「沙盒安全」是相對的:它降低誤操作與被誘導的爆炸半徑,不消除風險。

第2章 系統架構與元件關係

本章把 NemoClaw 主機上實際跑起來的東西逐一拆開:誰是控制面、誰是資料面、信任邊界畫在哪裡、哪個元件壞了會影響什麼。官方架構頁有一句話最能說明分工:OpenShell … has no opinions about what runs inside. NemoClaw is an opinionated reference stack built on OpenShell(OpenShell 不管沙盒裡跑什麼;NemoClaw 是建在 OpenShell 上、帶有明確主張的參考堆疊)。

2.1 元件總覽

#元件所屬執行位置責任
1開發人員工作站企業筆電/桌機(可能是 Windows)撰寫需求、審查產出、透過 SSH 或 WSL 操作 NemoClaw 主機
2NemoClaw 主機 CLINemoClaw🖥️ Host(Node.js 程式,bin/nemoclaw.js)onboarding 精靈、Provider 驗證、Blueprint 解析、記錄狀態、呼叫 openshell
3Blueprint 與 runnerNemoClaw🖥️ Host(nemoclaw-blueprint/)定義映像檔 digest、政策、推理 profile;runner 依 resolve → verify → plan → apply 執行
4OpenShell GatewayOpenShell🖥️ Host 程序(預設連接埠 8080;Linux 以 systemctl --user 的 openshell-gateway 服務管理)憑證儲存、推理代理、政策引擎、裝置驗證、沙盒生命週期
5openshell CLI 與 TUIOpenShell🖥️ Host低階操作;openshell term 是網路請求的核准介面
6沙盒容器OpenShellDocker daemon(或合格的 rootless Podman)Landlock+seccomp+網路命名空間;以 sandbox 使用者執行 Agent
7Agent RuntimeAgent 上游📦 SandboxOpenClaw/Hermes/dcode 的迴圈、工具、記憶
8NemoClaw 整合層NemoClaw📦 SandboxOpenClaw:TypeScript plugin 與 /nemoclaw 指令;Hermes:/sandbox/.hermes/config.yaml;Deep Agents:/sandbox/.deepagents/config.toml 與 .mcp.json
9推理服務供應商/自建雲端或本機(Ollama、vLLM、NIM、llama.cpp)模型推理、計費、限流
10外部整合第三方/內部網際網路或內網Git、套件庫、MCP Server、訊息平台
11主機端狀態NemoClaw🖥️ Host ~/.nemoclaw/、~/.local/state/沙盒登錄(sandboxes.json)、onboarding 進度、重建備份;不含憑證值

2.2 圖一:系統元件與資料流架構圖

flowchart LR
    DEV["開發人員工作站<br/>IDE、瀏覽器、SSH"]
    subgraph HOST["NemoClaw 主機(Ubuntu 24.04/WSL 2/macOS Apple Silicon)"]
        direction TB
        subgraph NCL["NemoClaw(參考堆疊)"]
            CLI["nemoclaw CLI<br/>onboard、status、policy、rebuild"]
            BP["Blueprint<br/>映像檔 digest、政策、preset"]
            ST["主機狀態<br/>~/.nemoclaw/ 登錄與備份"]
        end
        subgraph OSL["OpenShell 0.0.116(執行環境)"]
            GW["Gateway<br/>憑證庫、政策引擎、推理代理"]
            TERM["openshell term<br/>核准介面"]
            subgraph SBX["沙盒容器"]
                AG["Agent Runtime<br/>OpenClaw/Hermes/dcode"]
                INT["NemoClaw 整合層"]
                WS["/sandbox 工作區"]
            end
        end
    end
    NATIVE["附掛式原生 Provider<br/>NVIDIA、OpenAI、Anthropic 等"]
    SHARED["共享路由 inference.local<br/>本地 NIM、未附掛的相容端點"]
    EXT["核准的外部端點<br/>內部 Git、Nexus、MCP"]
    DEV -->|"SSH 或 WSL 終端機"| CLI
    DEV -->|"SSH 轉埠看 Dashboard"| AG
    CLI -->|"呼叫 openshell"| GW
    BP -->|"定義沙盒與政策"| SBX
    CLI -->|"記錄狀態"| ST
    GW -->|"建立與控制"| SBX
    AG -->|"placeholder 憑證<br/>受限路徑"| NATIVE
    AG -->|"inference.local"| GW
    GW -->|"注入憑證"| SHARED
    AG -.->|"經 L7 代理<br/>依政策放行"| EXT
    TERM -.->|"核准或拒絕"| GW

資料流向:Agent 的所有出站請求都經過 OpenShell 的代理與政策引擎;原生 Provider 路徑由沙盒附掛的 Provider 在出口改寫 placeholder;共享路由路徑由 Gateway 注入憑證。

控制流向:操作者 → nemoclaw CLI → openshell CLI/API → Gateway → 沙盒。Agent 本身不能反向修改政策或憑證。

2.3 圖二:Agent 執行任務時的請求流程

以「開發者請 Deep Agents Code 依規格新增一支 API,Agent 需要讀程式碼、呼叫模型、從內部 Nexus 下載依賴」為例:

sequenceDiagram
    autonumber
    actor Dev as 開發者
    participant CLI as nemo-deepagents CLI
    participant GW as OpenShell Gateway
    participant AG as dcode(沙盒內)
    participant LLM as 推理服務
    participant NX as 內部 Nexus
    participant UK as 未核准主機
    Dev->>CLI: nemo-deepagents launch dev-order
    CLI->>GW: 檢查就緒、修復轉埠
    CLI->>AG: 啟動 dcode TUI
    Dev->>AG: 輸入任務 Prompt
    AG->>AG: 讀 /sandbox/work 內的規格與程式碼
    AG->>LLM: 推理請求(placeholder 憑證)
    Note over AG,LLM: 經 OpenShell 代理;出口替換為真實憑證
    LLM-->>AG: 回應與工具呼叫建議
    AG->>Dev: 要求核准 shell 指令(互動模式)
    Dev-->>AG: 核准 mvn -q test
    AG->>NX: GET /repository/maven-public/...
    Note over AG,NX: 符合 corp-maven-readonly preset,放行
    AG->>UK: POST https://paste.example.net
    GW-->>AG: CONNECT 403(拒絕)
    GW->>Dev: openshell term 顯示待核准請求
    Dev-->>GW: 按 x 拒絕
    AG-->>Dev: 回報修改清單與測試結果

📌 註記:步驟 7 的「要求核准 shell 指令」是 Deep Agents Code 互動模式的預設行為(human-in-the-loop)。無頭模式 dcode -n 會自動核准非 shell 工具(包含檔案寫入與編輯),但同時停用 shell 執行(官方 Run Deep Agents Code 頁)。這個差異會影響第 7 章的工作流程設計。

2.4 責任邊界與信任邊界

官方 Trusted Computing Base 頁把元件分成「受信任」與「不受信任」兩群:

受信任(TCB 內)不受信任
操作者Agent 程序
NemoClaw 主機 CLIAgent 可寫入的設定與狀態
OpenShell 控制面可變的環境變數
容器 Runtime沙盒使用者寫出的狀態檔
不可變的映像檔內容網路回應(包含模型回應、網頁、套件)
flowchart TB
    subgraph T1["信任區:主機與控制面"]
        OPR["操作者帳號"]
        NCLI["nemoclaw CLI"]
        OSGW["OpenShell Gateway<br/>憑證庫"]
        RT["Docker/Podman"]
    end
    subgraph T2["受限區:沙盒"]
        AGT["Agent 程序"]
        CFG["Agent 可寫設定<br/>openclaw.json、config.toml"]
        WSP["/sandbox 工作區"]
    end
    subgraph T3["外部:不受信任輸入"]
        MDL["模型回應"]
        WEB["網頁、文件、套件"]
        REPO["待分析的原始碼"]
    end
    OPR --> NCLI --> OSGW --> RT --> AGT
    AGT --> CFG
    AGT --> WSP
    MDL --> AGT
    WEB --> AGT
    REPO --> WSP

三個常被忽略的邊界事實:

  1. 同一個 UID:在 OpenShell 管理的拓撲中,沙盒內的 supervisor、Agent Gateway 與 Agent 都以同一個 sandbox UID 執行。官方說明:OpenShell 隔離了沙盒,但同 UID 的惡意 Agent 可以對同伴程序送信號或冒充;NemoClaw 的健康檢查證明的是「服務可用」,不是「程序來源」。
  2. 繞過受管入口就沒有保護:官方 Known Limitations:若 Agent Runtime 不是從 NemoClaw 管理的 Gateway 路徑啟動,網路政策與推理驗證不會生效。不要用 docker exec 或自己啟動的容器跑 Agent。
  3. Agent 設定不保證不可變:官方 TCB 頁明言 NemoClaw 不提供「佈建後的設定與狀態不可變」。Agent 可以改自己的 openclaw.json,但這些設定無法放寬 OpenShell 網路政策或建立憑證綁定。

2.5 Blueprint:版本化的沙盒定義

Blueprint 是 nemoclaw-blueprint/ 下的一組 YAML,v0.0.139 的 blueprint.yaml 重點如下(📖 摘自原始碼):

version: "0.1.0"
# Requires OpenShell MCP/JSON-RPC L7 policy support from NVIDIA/OpenShell#1865.
min_openshell_version: "0.0.116"
max_openshell_version: "0.0.116"
min_openclaw_version: "2026.3.11"
digest: "sha256:b3d832b5...a3a9a"
profiles: [default, ncp, nim-local, vllm, routed]
components:
  sandbox:
    image: "ghcr.io/nvidia/openshell-community/sandboxes/openclaw@sha256:b3d832b5...a3a9a"
    forward_ports: [18789]
  inference:
    profiles:
      default:
        provider_type: "nvidia"
        endpoint: "https://integrate.api.nvidia.com/v1"
        model: "nvidia/nemotron-3-super-120b-a12b"
  policy:
    base: "sandboxes/openclaw/policy.yaml"

Runner 的生命週期是:

flowchart LR
    R["resolve<br/>找到 Blueprint、檢查版本範圍"] --> V["verify<br/>比對 digest"]
    V --> P["plan<br/>決定要建立或更新的資源"]
    P --> A["apply<br/>呼叫 openshell CLI"]
    A --> S["status<br/>回報結果"]

📌 註記:digest 欄位與映像檔的 @sha256 必須同時更新(原始碼註解引用 issue #1438)。這讓「registry 被竄改或有人誤推 :latest」無法悄悄換掉沙盒映像檔。企業若自建映像檔(--from <Dockerfile>),這層保護就要由企業自己的映像檔簽章與掃描補上(6.9)。

2.6 推理路由:附掛式 Provider 與共享路由

NemoClaw v0.0.139 有兩條推理路徑,取決於你選的 Provider(📖 Architecture、About Inference Routing):

路徑適用資料流憑證
附掛式原生 Provider(sandbox-attached)NVIDIA Endpoints、OpenAI、Anthropic、Google Gemini、OpenRouter、Hermes Provider;Personal 層以外新建的託管相容端點;合格的新本地 Ollama/vLLM/llama.cppAgent → 供應商原生主機名(例如 integrate.api.nvidia.com)→ 經 OpenShell 附掛政策限制主機、路徑、方法與程式沙盒內是 placeholder,出口改寫
共享路由 inference.local自有的本地 NVIDIA NIM、沒有附掛的相容端點、Model Router、保留的共享選擇、Personal 層新建的託管相容端點Agent → inference.local → OpenShell Gateway → Provider 端點Gateway 在 L7 代理注入
Bedrock透過「Other Anthropic-compatible endpoint」輸入 Bedrock Runtime URL主機本地 adapterAWS 憑證留在主機 adapter

以 NVIDIA Endpoints 為例,附掛的 nemoclaw-nvidia-prod-v1 Provider 只允許 GET /v1/models 與 POST /v1/chat/completions(不允許 embeddings),而且只限列出的 Agent 程式。

⚠️ 警告:舊版沙盒(例如較早建立、沒有附掛 Provider 的 OpenClaw Ollama 沙盒)可以繼續切換模型,但不能 --resume 或 rebuild;官方要求先備份,再以 --fresh --name <名稱> --recreate-sandbox 重新 onboarding。升級前要先確認每個沙盒走哪條路(12.2)。

2.7 狀態保存、日誌與生命週期

操作結果會不會動到 Agent 原生 home
Inspect:host probe、status、logs只讀不會
Configure:inference set、policy add、mcp add更新對應資源不會(但部分變更觸發重建,見 6.14)
Stop/Start停止/啟動同一個沙盒不會,狀態留在 OpenShell 儲存
Recover修復停止或降級的 Agent 與轉埠不會
Rebuild封存整棵原生 home/workspace → 刪除舊沙盒 → 以新映像檔重建 → 還原會搬移,但內容保留;憑證不在封存內
Destroy刪除沙盒與其持久化狀態會刪除,無法復原
Uninstall移除主機安裝;預設保留 rebuild-backups/、backups/、sandboxes.json依旗標而定

日誌與監控入口:

需求指令位置
沙盒生命週期與 Gateway 輸出nemoclaw <名稱> logs [--follow]🖥️ Host
即時網路活動與核准openshell term🖥️ Host
單一沙盒健康檢查nemoclaw <名稱> doctor🖥️ Host
問題回報用的診斷包nemoclaw debug --sandbox <名稱> --output <檔案>🖥️ Host
OpenClaw 對話紀錄nemoclaw <名稱> sessions export🖥️ Host(匯出到主機)

2.8 故障影響分析

故障元件症狀影響範圍資料風險第一步
Docker daemondocker info 失敗;所有沙盒不可用主機上全部沙盒低(狀態在 volume)啟動 Docker,nemoclaw <名稱> start
OpenShell Gatewayconnect 退出、status 顯示 Gateway down全部沙盒的推理與網路低Linux:systemctl --user restart openshell-gateway,再 recover
Agent 內部 Gateway(OpenClaw/Hermes)Dashboard 打不開、Agent 不回應單一沙盒低nemoclaw <名稱> recover 或 gateway restart
推理服務status 的 Inference 行為 unauthorized 或逾時使用該 Provider 的沙盒無檢查 Key、端點、政策(11.3)
網路政策CONNECT tunnel failed, response 403該沙盒的特定端點無nemoclaw <名稱> logs --tail 50 確認拒絕紀錄
主機登錄 sandboxes.json 損壞list、onboard 報 JSON 無效主機的沙盒管理中依官方指示備份壞檔後移除(11.3)
主機重開機沙盒顯示 Stopped全部低依「Reconnect after a host reboot」步驟(11.3);官方不保證自動復原
主機磁碟滿映像檔推送失敗、OOM全部中nemoclaw gc --dry-run、清理 Docker(11.3)

2.9 本章實務案例與注意事項

案例:資安審查時被問「Agent 拿得到 API Key 嗎?」

正確回答要分路徑:

  1. 推理憑證(NVIDIA、OpenAI 等):存在 OpenShell Gateway,沙盒內只有 placeholder;但沙盒內的 Agent 可以使用這把 Key 呼叫被允許的路徑(例如 POST /v1/chat/completions),因此仍要在供應商端設定預算與限流。
  2. 託管 MCP:NemoClaw 只記錄憑證名稱與擁有者中繼資料,值由 OpenShell 在核准出口替換。
  3. 例外:OpenClaw 的 Gateway auth token 會被寫到 /tmp/nemoclaw-proxy-env.sh,讓沙盒 shell 能連本機 Gateway(官方 Filesystem Controls 頁明載);WhatsApp 這類 QR 配對的 session 憑證會存在沙盒內。
  4. 若同仁把 Key 直接寫進 openclaw.json 或 .env,沙盒就讀得到——這是行政規範要禁止的(第 13 章),而且 rebuild 會因私有封存的憑證掃描失敗而中止。

注意事項:

  • 架構圖中的「OpenShell 0.0.116」是 v0.0.139 的釘選版本;每次升級 NemoClaw 都要重新確認(grep openshell_version nemoclaw-blueprint/blueprint.yaml)。
  • 不要把 openshell term 的一次性核准當成正式白名單:它在沙盒刪除重建後就消失(6.3)。

第3章 環境需求與安裝前檢查

NemoClaw 的平台支援狀態由官方的 ci/platform-matrix.json 統一產生,文件與 README 都從這份 JSON 渲染。本章的表格以 v0.0.139 的平台矩陣為準;官方的用法說明也適用於企業:A “Tested with limitations” row is not a “Tested” row(「有限制的已測試」不等於「已測試」)。

3.1 平台/必要條件/支援狀態/注意事項

平台必要條件支援狀態注意事項
Linux(Ubuntu 24.04)Docker Engine;apt-get 可用Tested(主要驗證路徑,有 CI)Ubuntu 24.04 有主機層 onboarding 驗證;Ubuntu 26.04 只有 userspace 層 CI,Docker、AppArmor、Landlock 與實際 onboarding 驗證仍待完成
Linux(Ubuntu 22.04、Fedora、Rocky、Alma、NixOS、Arch)—未確認(官方:may work but are not validated);非 Ubuntu/Debian 系另列 Unsupported安裝程式假設 apt-get;Fedora 有已知卡住問題(issue #899)
Linux+原生 rootless PodmanNEMOCLAW_GATEWAY_RUNTIME=podman、cgroups v2、lsof、目前使用者的 Podman socketTested with limitations不支援自訂 --from Dockerfile 與唯讀主機掛載;託管 vLLM 仍需要 Docker
DGX OS(Spark)DockerTested(有 CI)可用 Express 安裝;雙機 vLLM 為 Experimental
DGX OS(Station GB300)DockerTested with limitations(無 CI)只在一台實機驗證;DGX OS 7.6.x 完整 E2E 仍待完成
macOS(Apple Silicon)Colima 或 Docker Desktop;建議 Xcode Command Line ToolsTested with limitations(有 CI)先啟動容器 Runtime;Homebrew Colima 需同時 brew install colima docker;Docker VM 核心可能不支援 Landlock
macOS(Intel x86_64)—⛔ Unsupported安裝程式在下載前即拒絕
Windows 11/10(build 19041+)+WSL 2Docker Desktop(WSL backend)或合格的 rootless PodmanTested with limitations(無 CI)所有 NemoClaw 指令在 WSL 內執行;官方以 x86-64 測試
原生 Windows(不經 WSL)—未確認/無安裝路徑官方只提供 WSL 2 路徑
NVIDIA RTX 工作站 GPU(Linux)NVIDIA Container Toolkit、CDIDeferred託管 vLLM 需 NEMOCLAW_EXPERIMENTAL=1 或 NEMOCLAW_PROVIDER=install-vllm
N1x Linux—Deferred實機 Express E2E 未完成,不可宣稱支援
Kubernetes/OpenShift—⛔ Unsupported沙盒是 Docker 容器,不是 Pod
離線(air-gapped)—⛔ Unsupportedonboarding 需要下載與 Provider 驗證(issue #4872、#2218)
多使用者共用主機—⛔ Unsupportedonboarding 會警告多使用者主機

來源:Platform Support、Prerequisites、ci/platform-matrix.json

3.2 硬體需求

資源最低建議說明
CPU4 vCPU4+ vCPU—
RAM8 GB16 GB沙盒映像檔推送時,容器 Runtime、k3s、Gateway 與匯出管線同時執行,管線會在記憶體中緩衝解壓縮的 layer;低於 8 GB 可能觸發 OOM(exit 137)
磁碟20 GB 可用40 GB 可用沙盒映像檔壓縮後約 2.4 GB;每次重建可能留下舊映像檔(用 nemoclaw gc 清理)
Swap—記憶體不足 8 GB 時至少 8 GB官方的緩解做法,代價是變慢
GPU雲端推理不需要本地推理依模型而定只支援 NVIDIA GPU;需 NVIDIA Container Toolkit 與健康的 CDI;AMD/Intel/Apple Metal ⛔ Unsupported

🏢 企業建議:Coding Agent 開發主機以 8 vCPU/32 GB/100 GB SSD 起跳。理由:Java+Node 專案本身的建置、Testcontainers 啟動的資料庫容器、再加上沙盒映像檔與重建備份,20 GB 很快用完。

自己檢查主機是否達標(🖥️ Host,唯讀;📖 指令為標準 Linux 工具):

# 🖥️ Host:主機資源檢查(不修改系統)
echo "CPU: $(nproc)"
free -g | awk '/^Mem:/{print "RAM(GB): "$2} /^Swap:/{print "Swap(GB): "$2}'
df -BG --output=avail,target ~ /var/lib/docker 2>/dev/null
nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv,noheader 2>/dev/null \
  || echo "GPU: 無(只用雲端推理時可接受)"
項目通過標準常見誤判
CPU≥ 4(企業建議 ≥ 8)VM 的 vCPU 被超額分配時,數字對但效能不夠,要看虛擬化平台的保證值
RAM(GB)≥ 8(企業建議 ≥ 32)free -g 無條件捨去:16 GB 主機常顯示 15,仍算通過
Swap(GB)RAM < 8 GB 時 ≥ 8Swap 只能避免 OOM,不能讓速度變快
avail家目錄與 /var/lib/docker 都 ≥ 20G兩者在同一個分割區時,只會列出一行
GPU本地推理才需要memory.used 接近 memory.total 代表 GPU 已被占滿

⚠️ 警告:v0.0.139 在 Ollama 回報「可用 GPU 記憶體 0 MB」時,會把它當成「整張 VRAM 都可用」(main 的 #13748 已修正)。GPU 被其他程序占滿的主機,onboarding 可能選出放不下的模型。先用上面的 nvidia-smi 確認 memory.used,必要時先停掉占用 GPU 的程序。

3.3 軟體與依賴

依賴版本誰負責安裝備註
Node.js22.19 以上安裝程式可透過 nvm 安裝透過 nvm 安裝時需要 sha256sum 或 shasum
npm10 以上隨 Node.js全域 prefix 不可寫時,CLI 會寫 shim 到 ~/.local/bin/nemoclaw
容器 RuntimeDocker Engine/Docker Desktop/Colima;或合格的 rootless Podman安裝程式可在 Linux 安裝 Docker(需 sudo)會把使用者加入 docker 群組(見 3.6 警告)
strings(binutils)—需自行安裝安裝程式用它驗證 OpenShell 執行檔
zstd—Debian/Ubuntu 上自動以 apt-get 安裝原生 Linux Ollama 路徑需要
git—需自行安裝bootstrap 安裝程式用 git fetch 取得指定版本
OpenShell0.0.116由 NemoClaw 安裝程式安裝⛔ 不要自行安裝其他版本

⚠️ 警告:官方 Prerequisites 頁的 OpenShell Lifecycle 警告:在 NemoClaw 管理的環境中,需要建立或重建 OpenShell Gateway 或沙盒時,用 nemoclaw onboard;避免 openshell self-update、npm update -g openshell 或直接 openshell sandbox create,除非你打算自己管理 OpenShell,事後再重跑 nemoclaw onboard。

3.4 Windows、WSL 2 與 Docker Desktop

Windows 的正確心智模型是:Windows 只負責提供 WSL 2 與 Docker Desktop;NemoClaw 本身完全在 WSL 的 Ubuntu 裡執行。官方原文:All NemoClaw commands run inside WSL, not in PowerShell.

步驟執行位置指令或動作預期結果
1. 確認 Windows 版本🪟 PowerShell[System.Environment]::OSVersion.VersionBuild 19041 以上
2. 啟用 WSL 2🪟 PowerShell(系統管理員)wsl --install --no-distribution啟用 WSL 與 Virtual Machine Platform;可能要求重開機
3. 安裝並註冊 Ubuntu🪟 PowerShell(系統管理員)wsl --install -d Ubuntu-24.04第一次啟動時建立 Unix 帳號;不要加 --no-launch
4. 確認是 WSL 2🪟 PowerShellwsl -l -vUbuntu-24.04 Running 2
5. 安裝 Docker DesktopWindows啟用 WSL 2 backend 與該發行版的 WSL integrationSettings → Resources → WSL integration 已勾選
6. 驗證 Docker🐧 WSLdocker info印出 Server 資訊

官方也提供 bootstrap 腳本一次完成 2~5 步(📖 Windows Preparation):

# 🪟 PowerShell:先下載到暫存檔,審查後再執行(不要直接管線執行)
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/NVIDIA/NemoClaw/main/scripts/bootstrap-windows.ps1' -OutFile "$env:TEMP\bootstrap-windows.ps1"
Get-Content "$env:TEMP\bootstrap-windows.ps1" | Select-Object -First 80   # 先看內容
Get-Help "$env:TEMP\bootstrap-windows.ps1" -Detailed                    # 看參數:-DistroName、-InstallDockerDesktop 等
powershell.exe -ExecutionPolicy Bypass -File "$env:TEMP\bootstrap-windows.ps1"

⚠️ 警告:bootstrap 腳本會要求系統管理員權限、啟用 Windows 功能、透過 winget 安裝 Docker Desktop。腳本網址指向 main 分支而不是版本標籤;企業應先下載、比對 SHA-256、經資安審查後放到內部檔案庫,再由端點管理工具發佈。-ExecutionPolicy Bypass 只影響該 PowerShell 程序。

Windows 特有的注意事項:

項目說明
Dashboard 綁定WSL 上 Dashboard 轉埠綁定所有介面(讓 Windows 主機連得到),非 WSL 環境只綁 127.0.0.1;企業防火牆要確認 WSL 虛擬網卡不對外
Windows 端 Ollama只在綁定 loopback 11434、Docker Desktop 可達、且對不受信任的 Host 標頭回 403 時才重用;⛔ 不要設 OLLAMA_HOST=0.0.0.0:11434
同時兩個 Ollama不要在 Windows 與 WSL 同時於 11434 執行 Ollama
--host-mount只支援 Linux 與 WSL 2 上的 Docker;原生 Windows 與 macOS 不支援
Cursor 等 IDE Agent若 Coding Agent 的終端機被組織政策鎖住,官方建議改由 Agent 產生 .ps1/.bat 檔、經人工檢視後手動執行,且檔案內不可嵌入真實憑證

3.5 macOS 與 DGX 平台

  • macOS(Apple Silicon):先啟動 Docker Desktop 或 Colima;NemoClaw 會驗證釘選的官方 OpenShell Homebrew formula,並只在每次 Homebrew 操作前後暫時信任該 formula。Colima 建議至少 colima start --cpu 4 --memory 8。
  • DGX Spark:官方主要驗證平台之一,安裝時可選 Express(自動選擇託管 vLLM 與 Balanced 政策);官方另有 DGX Spark Playbook(GitHub 版本:dgx-spark-playbooks/nvidia/nemoclaw)。Playbook 開宗明義要求「只使用乾淨環境,不放個資、機密或敏感憑證」。
  • DGX Station:Tested with limitations,安裝前需依官方「Prepare DGX Station」頁完成準備;安裝程式可能以結束碼 10(需要重開機)或 11(需要重新登入)暫停。

macOS 自我檢查(🖥️ Host,唯讀;🧪 docker info 的欄位以你的 Docker 版本為準):

uname -m      # 預期 arm64;x86_64 代表 Intel Mac,不在支援矩陣內
docker info --format 'OS={{.OperatingSystem}} CPUs={{.NCPU}} MemGiB={{div .MemTotal 1073741824}}'
colima status 2>/dev/null   # 使用 Colima 時才有輸出

判讀方式:沙盒能用的是 Docker VM 的資源,不是 Mac 本機的資源。即使 Mac 有 36 GB 記憶體,MemGiB 低於 8 時仍會遇到 3.2 說的 OOM。這時調高 Docker Desktop 的資源設定,或用 colima start --cpu 4 --memory 8 重建 VM。

DGX Station 安裝程式的結束碼處理(🖥️ Host;📖 結束碼 10、11 出自官方「Prepare DGX Station」頁;🧪 未實機執行):

# 沿用 4.3 已下載並審查過的 nemoclaw.sh
NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG=v0.0.139 bash nemoclaw.sh; rc=$?
case $rc in
  0)  echo "完成:繼續 4.4 的版本確認" ;;
  10) echo "需要重新開機:重開後用同一行指令重跑" ;;
  11) echo "需要重新登入:登出再登入後用同一行指令重跑" ;;
  *)  echo "失敗($rc):保留完整輸出,依 11.3.1 排查" ;;
esac

❌ 壞例:看到結束碼 10 就判定「安裝失敗」,改用其他安裝方式重裝。結束碼 10、11 是安裝程式預期中的暫停點,照提示重開機或重新登入後重跑即可。

3.6 網路、DNS、Proxy、TLS 與防火牆需求

需求用途企業注意事項
連到 www.nvidia.com、github.com、raw.githubusercontent.com下載安裝程式與指定版本原始碼若只允許內部鏡像,需另建 Git mirror(🧪,官方未提供離線安裝)
連到容器 registry(ghcr.io;本地 NIM 另需 nvcr.io 與 NGC 登入)拉取 digest 固定的沙盒映像檔若用企業 registry 代理,確認 digest 不變
連到 registry.npmjs.org安裝 CLI 與相依套件可走企業 npm 代理(🧪)
推理服務端點Provider 驗證與 Agent 推理例如 integrate.api.nvidia.com、api.openai.com
DNS(UDP 53)容器內名稱解析官方 preflight 會執行 docker run --rm busybox nslookup nemoclaw-dns-probe-<亂數>.invalid;封鎖 UDP 53、只走 DNS over TLS 的企業網路會失敗(解法見 11.3)
HTTP Proxy沙盒出口沙盒預設代理是 OpenShell 注入的 10.200.0.1:3128;企業 Proxy 以 NEMOCLAW_PROXY_HOST、NEMOCLAW_PROXY_PORT 在 onboarding 前設定,屬建置期設定,變更要重新 onboarding
TLS 攔截(MITM Proxy)企業 Proxy 重新簽章onboarding 前設定 NEMOCLAW_CORPORATE_CA_BUNDLE=/path/corp-ca.pem,NemoClaw 會驗證並把 CA 烤進映像檔;既有沙盒要 rebuild

⚠️ 警告(docker 群組):官方 Prerequisites 頁警告:Members of the docker group can control the daemon with root-level impact. 個人開發機加入 docker 群組是常見做法,但共用或受管主機應使用組織核准的 Docker 存取方式。這也是「一人一台主機」的原因之一。

3.7 模型推理服務、API Key 與帳號權限

onboarding 精靈提供的推理選項與對應的憑證環境變數(📖 Quickstart):

選項適用憑證變數平台矩陣狀態
NVIDIA Endpointsbuild.nvidia.com 上的託管模型(含 Nemotron)NVIDIA_INFERENCE_API_KEYTested
OpenRouter託管的 OpenAI 相容 ProviderOPENROUTER_API_KEYTested
OpenAIhttps://api.openai.com/v1OPENAI_API_KEYTested
其他 OpenAI 相容端點LocalAI、vLLM、NIM、SGLang、企業 AI GatewayCOMPATIBLE_API_KEYTested with limitations
AnthropicAnthropic Messages APIANTHROPIC_API_KEYTested
其他 Anthropic 相容端點含 AWS Bedrock Runtime(主機端 adapter)依端點Tested with limitations
Google GeminiGoogle 的 OpenAI 相容端點依 ProviderTested
Local Ollama主機上的 Ollama無Tested with limitations
Local vLLM/llama.cpp/NIM本機 GPU 推理依路徑Tested with limitations/Experimental
Model Router從 NVIDIA Endpoints 模型池中逐請求選模NVIDIA_INFERENCE_API_KEYExperimental

帳號權限的最低要求(🏢):

  • 推理 API Key 使用專案專屬、低額度、可撤銷的 Key,不用個人主帳號 Key。
  • 在供應商端設定每日/每月預算與速率上限(NemoClaw 不做計費控管)。
  • 若要讓 Agent 存取內部 Git,申請唯讀、單一 repo、有到期日的 Token(第 7、13 章)。

3.8 企業 Proxy、內網 Git、套件倉庫與私有模型的限制

企業設施現況(v0.0.139)做法狀態
企業 HTTP Proxy支援建置期設定NEMOCLAW_PROXY_HOST/PORT 後 onboarding📖
企業 TLS 攔截 CA支援NEMOCLAW_CORPORATE_CA_BUNDLE📖
內網 Git(Bitbucket、GitLab)沒有內建 preset自訂 preset+--trusted-private-host(6.11)📖 機制/🧪 路徑規則
內部 Maven/npm 代理(Nexus、Artifactory)官方 preset 只有公開的 npm、pypi、brew、huggingface自訂 preset 指向內部代理📖 機制/🧪 實測
私有模型服務(vLLM、企業 AI Gateway)「其他 OpenAI 相容端點」onboarding 時輸入 base URL 與 COMPATIBLE_API_KEY📖
完全離線⛔ 不支援不建議用 NemoClaw—
私有 IP 的端點OpenShell 預設以 SSRF 防護封鎖私有、迴環、link-local自訂 preset 必須用 --trusted-private-host <精確主機名> 明確信任,NemoClaw 會解析並把位址釘死📖

📌 註記:官方 Customize Network Policy 頁提醒,不要依賴 host.docker.internal 作為一般的主機服務路徑,因為它會繞過 OpenShell 政策路徑且不一定可達。要讓沙盒連主機上的 HTTP 服務,應把服務開在 Gateway 可達的主機 IP,並用自訂 preset 放行。

3.9 安裝前預檢腳本

以下腳本只讀取資訊、不安裝任何東西。執行位置:🖥️ Host(Linux 或 WSL Ubuntu)。🧪 本腳本依官方需求撰寫,未在 Linux 實機執行;請先在測試主機驗證輸出。

#!/usr/bin/env bash
# preflight-nemoclaw.sh — 🏢 企業自訂預檢(唯讀,不修改系統)
set -u
pass(){ printf '  [PASS] %s\n' "$1"; }
fail(){ printf '  [FAIL] %s\n' "$1"; FAILED=1; }
warn(){ printf '  [WARN] %s\n' "$1"; }
FAILED=0

echo "== 作業系統與核心"
. /etc/os-release 2>/dev/null && echo "  $PRETTY_NAME"
[[ "${ID:-}" == "ubuntu" && "${VERSION_ID:-}" == "24.04" ]] && pass "Ubuntu 24.04(官方主要驗證路徑)" || warn "不是 Ubuntu 24.04,屬未驗證或有限制平台"
kver=$(uname -r | cut -d. -f1-2)
awk -v v="$kver" 'BEGIN{split(v,a,".");exit !(a[1]>5||(a[1]==5&&a[2]>=13))}' && pass "核心 $kver ≥ 5.13(Landlock 可用)" || fail "核心 $kver < 5.13,檔案系統限制會降級"
grep -qi microsoft /proc/version && warn "偵測到 WSL:Windows 路徑為 Tested with limitations"

echo "== 硬體"
cpus=$(nproc); mem=$(awk '/MemTotal/{printf "%d",$2/1024/1024}' /proc/meminfo); disk=$(df -BG --output=avail "$HOME" | tail -1 | tr -dc 0-9)
(( cpus >= 4 )) && pass "CPU $cpus 核" || fail "CPU $cpus 核 < 4"
(( mem >= 8 )) && pass "RAM ${mem} GB" || fail "RAM ${mem} GB < 8(需 swap)"
(( disk >= 20 )) && pass "家目錄可用 ${disk} GB" || fail "家目錄可用 ${disk} GB < 20"

echo "== 軟體"
command -v node >/dev/null && node -e 'const [a,b]=process.versions.node.split(".").map(Number);process.exit(a>22||(a===22&&b>=19)?0:1)' \
  && pass "Node.js $(node -v)" || warn "Node.js 缺少或低於 22.19(安裝程式可用 nvm 安裝)"
for c in git strings sha256sum curl; do command -v "$c" >/dev/null && pass "$c 存在" || fail "$c 不存在"; done
command -v zstd >/dev/null && pass "zstd 存在" || warn "zstd 不存在(Debian/Ubuntu 會自動安裝)"

echo "== 容器 Runtime"
if docker info >/dev/null 2>&1; then
  pass "Docker 可用:$(docker version --format '{{.Server.Version}}' 2>/dev/null)"
  id -nG | grep -qw docker && warn "目前帳號在 docker 群組(等同 root 影響力,確認符合公司規範)"
  docker run --rm busybox nslookup registry.npmjs.org >/dev/null 2>&1 && pass "容器內 DNS 正常" || fail "容器內 DNS 失敗(見 11.3 企業防火牆 DNS)"
else
  fail "docker info 失敗(未安裝、未啟動或沒有權限)"
fi

echo "== 網路與 Proxy"
env | grep -iE '^(https?_proxy|no_proxy)=' | sed 's/=.*@/=***@/' || true
for u in https://www.nvidia.com https://github.com https://registry.npmjs.org https://ghcr.io; do
  curl -sS -o /dev/null -m 10 -w "%{http_code}" "$u" >/dev/null 2>&1 && pass "可連 $u" || fail "無法連 $u"
done
for v in REQUESTS_CA_BUNDLE CURL_CA_BUNDLE SSL_CERT_FILE NEMOCLAW_CORPORATE_CA_BUNDLE; do
  [[ -n "${!v:-}" ]] && warn "$v=${!v}(NemoClaw 會依序作為企業 CA 來源)"
done

echo "== 多使用者"
users=$(who | awk '{print $1}' | sort -u | wc -l)
(( users <= 1 )) && pass "目前只有 $users 位登入使用者" || warn "有 $users 位使用者登入,官方不支援多使用者共用主機"

exit $FAILED

▶️ 預期結果:全部 [PASS] 時結束碼為 0;任何 [FAIL] 結束碼為 1。[WARN] 需要人工判斷。

安裝完成後,改用官方的唯讀就緒報告(📖 System Readiness):

# 🖥️ Host:不會修改主機、Docker、Gateway、憑證、政策或沙盒狀態
nemoclaw host probe
nemoclaw host probe --json > host-probe-$(date +%Y%m%d).json
echo "exit=$?"   # 0=supported、2=incompatible、3=inconclusive

3.10 本章實務案例與注意事項

案例:同仁的 Windows 筆電裝了 Docker Desktop,但 nemoclaw onboard 卡在 DNS 檢查。

診斷順序:

  1. 🐧 WSL:docker run --rm busybox nslookup registry.npmjs.org。失敗代表是容器 DNS,不是 NemoClaw。
  2. 若公司封鎖 UDP 53、只允許 DNS over TLS(TCP 853),容器不會繼承主機的 DoT 設定。官方解法:在 Docker Desktop 設定 GUI 指定企業 DNS。
  3. 若 DNS 伺服器回 NXDOMAIN/REFUSED,代表解析器有回應但拒絕,要找 DNS 管理員檢查轉送規則,不是開 UDP 53。
  4. 修好後重跑 nemoclaw onboard --resume。

注意事項:

  • 平台狀態以研究日為準,每次升級前重新查看 Platform Support 頁。
  • Ubuntu 26.04 目前只有 userspace CI,不要因為「新版」就選它。
  • WSL 上的 Dashboard 綁定所有介面,筆電在公共網路時要確認 Windows 防火牆設定。

第4章 安裝、初始化與首次啟動

本章以「在一台乾淨的 Ubuntu 24.04(或 WSL 2 Ubuntu 24.04)主機上,安裝 NemoClaw v0.0.139、建立一個 Deep Agents Code 開發沙盒、並驗證限制有效」為主線,OpenClaw 與 Hermes 的差異在各步驟註明。每個指令都標示執行位置、前提、預期結果、失敗排查,以及是否會改動系統。

4.1 安裝流程總覽

flowchart TD
    A["Step 1 安裝前檢查<br/>preflight 腳本"] --> B["Step 2 下載並審查安裝程式<br/>固定版本、關閉遙測"]
    B --> C["Step 3 執行安裝<br/>Node.js、Docker、OpenShell、CLI"]
    C --> D["Step 4 選擇 Agent<br/>onboarding 精靈"]
    D --> E["Step 5 推理服務<br/>Provider、模型、憑證"]
    E --> F["Step 6 沙盒與政策<br/>名稱、政策層級、preset"]
    F --> G["Step 7 首次啟動<br/>launch 或 connect"]
    G --> H["Step 8~9 測試請求<br/>確認回應"]
    H --> I["Step 10 驗證限制<br/>檔案、網路、憑證"]
    I --> J["Step 11 日誌與狀態<br/>status、logs、doctor"]
    J --> K{"全部通過?"}
    K -- 否 --> L["依 11.3 排查<br/>onboard --resume"]
    L --> D
    K -- 是 --> M["記錄版本盤點<br/>12.2"]

4.2 Step 1:安裝前的環境檢查

項目內容
執行位置🖥️ Host(Linux 或 🐧 WSL)
前提已完成第 3 章的平台確認;Windows 已完成 3.4
指令bash preflight-nemoclaw.sh(3.9 的腳本)
預期結果結束碼 0,沒有 [FAIL]
失敗排查依 [FAIL] 項目處理;DNS 失敗見 11.3
是否修改系統否(只讀取資訊;會拉取並執行 busybox 測試映像檔)

4.3 Step 2:官方安裝方式與安全檢查

官方安裝指令是:

curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash

在企業環境,不要直接執行這一行。先理解它做了什麼(📖 摘自 v0.0.139 install.sh 與 scripts/install.sh):

階段動作會修改系統嗎
bootstrap解析要安裝的版本:NEMOCLAW_INSTALL_REF > NEMOCLAW_INSTALL_TAG > 預設 lkg否
bootstrap在暫存目錄 git init 並 git fetch --depth 1 該版本暫存目錄
bootstrap若已安裝較新版本,拒絕以 lkg 降級否
bootstrap檢查下載的 scripts/install.sh 非空且以 shebang 開頭,然後執行否
安裝第三方軟體聲明(需接受)否
安裝必要時以 nvm 安裝 Node.js(驗證 nvm 安裝程式的完整性)是:家目錄
安裝Linux 上若無 Docker,下載 Docker 官方便利腳本並以 sudo 執行、啟動服務、把使用者加入 docker 群組是:系統層級
安裝安裝 OpenShell 0.0.116(比對官方 checksum 檔)與 Gateway 使用者服務是
安裝以 npm link 或 ~/.local/bin/nemoclaw shim 安裝 CLI是
安裝若有既有沙盒:先全部備份、必要時汰換 Gateway、執行 upgrade-sandboxes --auto是
安裝前置檢查通過後自動啟動 nemoclaw onboard是:建立沙盒

⚠️ 警告(供應鏈):bootstrap 對下載的 payload 只做「非空、以 shebang 開頭」的檢查,沒有簽章或雜湊比對;完整性依賴 HTTPS 與 GitHub。版本標籤本身有 SSH 簽章(git cat-file -p 可看到 BEGIN SSH SIGNATURE),但驗證需要 NVIDIA 的公鑰,官方文件未提供驗證步驟(🧪)。

企業建議的安全安裝程序(🏢):

# 🖥️ Host:1. 下載而不執行
mkdir -p ~/nemoclaw-install && cd ~/nemoclaw-install
curl -fsSL --proto '=https' --proto-redir '=https' https://www.nvidia.com/nemoclaw.sh -o nemoclaw.sh
sha256sum nemoclaw.sh | tee nemoclaw.sh.sha256

# 2. 與 GitHub 上的固定版本比對(兩者應相同;不同時停止並通報)
curl -fsSL "https://raw.githubusercontent.com/NVIDIA/NemoClaw/v0.0.139/install.sh" -o install-v0.0.139.sh
sha256sum install-v0.0.139.sh
diff -q nemoclaw.sh install-v0.0.139.sh && echo "SAME" || echo "DIFFERENT:交資安審查"

# 3. 審查重點(至少看這幾處)
grep -n 'DEFAULT_INSTALL_REF=' nemoclaw.sh            # 預設版本來源
grep -n 'github.com/NVIDIA/NemoClaw.git' nemoclaw.sh  # 下載來源
grep -n 'verify_downloaded_script' nemoclaw.sh        # 完整性檢查方式
bash nemoclaw.sh --help                               # 只印說明,不安裝
項目內容
執行位置🖥️ Host
前提可連 www.nvidia.com 與 raw.githubusercontent.com
預期結果SAME;--help 印出選項與環境變數清單
失敗排查DIFFERENT:可能是 nemoclaw.sh 已更新到比 v0.0.139 新的 bootstrap;以 GitHub 標籤版本為準,並請資安比對差異
是否修改系統否(只下載檔案)🧪 www.nvidia.com/nemoclaw.sh 與 GitHub 檔案是否逐位元相同,需實際比對

4.4 Step 3:執行安裝並確認版本

# 🖥️ Host:每個新 shell 都要先設定
export NEMOCLAW_DISABLE_TELEMETRY=1      # 關閉預設遙測(官方:每個 shell 都要設)
export NEMOCLAW_NO_EXPRESS=1             # 🏢 不使用 Express 自動選擇,改為逐項確認

# 固定版本安裝;NEMOCLAW_INSTALL_REF 要清空,否則它的優先順序較高
NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG=v0.0.139 \
  NEMOCLAW_AGENT=langchain-deepagents-code \
  bash ~/nemoclaw-install/install-v0.0.139.sh

📌 註記:官方文件的寫法是 curl … | NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG=vX.Y.Z bash,環境變數必須放在管線右側的 bash 前面才讀得到。上例改為執行已審查的本地檔案,效果相同。不指定時安裝的是 lkg(研究當日為 v0.0.137),與文件站 latest(v0.0.139)不一致。

項目內容
執行位置🖥️ Host
前提Step 2 審查通過;有 sudo 權限(若需安裝 Docker)
預期結果依序完成 Node.js、Docker、OpenShell、CLI 安裝,接著進入 onboarding 精靈
失敗排查印出 newgrp docker → 執行後重跑;nemoclaw: command not found → source ~/.bashrc 或把 ~/.local/bin 加入 PATH;strings 缺少 → sudo apt-get install -y binutils
是否修改系統是:安裝套件、加入群組、建立使用者服務、建立 ~/.nemoclaw/

安裝後的版本確認(若安裝程式已直接進入精靈,可在另一個終端機執行):

# 🖥️ Host
nemoclaw --version          # 預期:nemoclaw v0.0.139
nemo-deepagents --version   # 同一套 CLI 的別名
openshell --version         # 預期:openshell 0.0.116(🧪 實際輸出格式依 OpenShell 0.0.116)
nemoclaw agents list        # 預期列出 openclaw、hermes、langchain-deepagents-code

nemoclaw agents list 的官方預期輸出:

openclaw                   Gateway-based AI agent with plugin ecosystem (openclaw.ai)
hermes                     Self-improving AI agent with learning loop (Nous Research)
langchain-deepagents-code  Terminal coding agent built on the Deep Agents SDK

✅ 建議:nemoclaw --version 的版本來自建置身分(build identity),不是 package.json(後者寫 0.1.0,只是備援值)。版本對不上時,以 --version 為準並記錄到 12.2 的盤點表。

4.5 Step 4:選擇 Agent 與引導式初始化

Agent入口選擇方式適合
OpenClaw(預設)nemoclaw onboard不加 --agent常駐助理、Dashboard、訊息通道
Hermesnemohermes onboard--agent hermes 或 NEMOCLAW_AGENT=hermes自我學習型 Agent;提供 OpenAI 相容 API(連接埠 8642~8652)
LangChain Deep Agents Codenemo-deepagents onboard--agent langchain-deepagents-code(別名 dcode、deepagents、langchain)終端機 Coding Agent,無 Dashboard
# 🖥️ Host:建立開發用 Deep Agents 沙盒(若安裝程式沒有自動進入精靈)
nemo-deepagents onboard --name dev-order

精靈依序詢問:Agent(若入口未指定)→ 推理 Provider 與模型 → 憑證 → 沙盒名稱 → 檢閱畫面 → 選擇性的 Web Search 與訊息通道 → 政策層級與 preset。

沙盒名稱規則(📖 Troubleshooting「Invalid sandbox name」):1~19 個字元、小寫、字母開頭、只含字母數字與單一連字號、字母或數字結尾、不可有 --;不可與全域指令同名(onboard、list、setup、start、stop、status、debug、uninstall、credentials、help)。

🏢 命名規範:<用途>-<專案代號>,例如 dev-order、re-legacy、up-billing。19 字元限制來自 OpenShell 0.0.116 的路由名稱限制(官方 Update Sandboxes 頁)。

4.6 Step 5:模型推理服務設定

精靈的推理選單(📖 Quickstart):

  1) NVIDIA Endpoints
  2) OpenRouter
  3) OpenAI
  4) Other OpenAI-compatible endpoint
  5) Anthropic
  6) Other Anthropic-compatible endpoint
  7) Google Gemini
  8) Local Ollama (localhost:11434)
  9) Model Router (experimental)
  Choose [1]:

不想在精靈中貼 Key 時,事先以不留歷史紀錄的方式放進環境變數(📖 Credential Rotation 的寫法):

# 🖥️ Host:讀入時不回顯、不寫入 shell 歷史
printf 'NVIDIA inference API key: ' >&2
IFS= read -r -s NVIDIA_INFERENCE_API_KEY; printf '\n' >&2
export NVIDIA_INFERENCE_API_KEY
nemo-deepagents onboard --name dev-order
unset NVIDIA_INFERENCE_API_KEY
項目內容
執行位置🖥️ Host
前提已取得專案專屬、低額度的 API Key
預期結果精靈驗證 Provider 與模型後進入檢閱畫面,提供 Apply configuration/Edit/Exit onboarding
失敗排查驗證失敗 → 檢查 Key 與網路;相容端點失敗見 11.3
是否修改系統選 Apply 後在 OpenShell Gateway 註冊 Provider 與憑證

⚠️ 警告:使用企業私有模型時,選 Other OpenAI-compatible endpoint,輸入內部 base URL。官方 Platform Support 對這一列的註記是:它宣稱的是「轉接器」,不是所有相容端點都能用;企業 AI Gateway 的工具呼叫格式要實測(🧪,見 11.3「Tool calls appear as assistant text」)。

4.7 Step 6:沙盒建立與安全政策確認

精靈會問政策層級(📖 Network Policies — Policy Tiers):

層級套用的 preset本手冊建議
Restricted無層級預設(只有基準政策)🏢 企業首選:之後只加審查過的自訂 preset
Balanced(預設)npm、pypi、huggingface、brew-balanced、brave(及所選 Web Search)只用於個人評估
Open再加上 brew、weather、public-reference、slack、discord、telegram、jira、outlook 等⛔ 企業不使用
Personalpersonal-open-internet(強制):所有程式可連任何公開與私有位址的 80/443⛔ 企業禁止

非互動模式指定層級:

# 🖥️ Host
NEMOCLAW_POLICY_TIER=restricted nemo-deepagents onboard --name dev-order \
  --non-interactive --yes-i-accept-third-party-software

⚠️ 警告(Personal 層):官方原文:An agent can send workspace data or sandbox-visible credentials to an arbitrary reachable service on either port without an operator approval prompt. 而且 Personal 一旦套用,NemoClaw 拒絕就地移除,只能另建沙盒。

⚠️ 警告(Deep Agents 的基準政策):即使選 Restricted,Deep Agents Code 的 Agent 專屬基準政策(agents/langchain-deepagents-code/policy-additions.yaml)仍包含 github.com 與 api.github.com 的 access: full(L4,不檢查方法與路徑),以及 pypi。這代表 Agent 預設就能對 GitHub 推送資料。若企業不允許,必須在 onboarding 後以 nemo-deepagents dev-order policy exclude github --dry-run 預覽、再以 --force 移除(📖 v0.0.139 原始碼 src/lib/policy/baseline-exclusion.ts 為這個 key 註明的影響是「Git operations and GitHub API or source access may stop working」;見 6.15)。

4.8 Step 7:Agent 首次啟動

# 🖥️ Host:確認就緒
nemo-deepagents dev-order status

# 一步完成連線與啟動 TUI
nemo-deepagents launch dev-order

# 或分兩步:先進沙盒 shell,再自己啟動
nemo-deepagents dev-order connect
# 📦 Sandbox(connect 之後)
dcode status     # 印出沙盒名稱、harness、推理路由、Provider、模型、端點後結束
dcode            # 啟動互動式 TUI
項目內容
執行位置status/launch/connect:🖥️ Host;dcode:📦 Sandbox
前提onboarding 完成並印出 ready 摘要
預期結果status 顯示 Agent 行(例如 Agent: LangChain Deep Agents Code vX.Y.Z)與健康的 Inference 行
失敗排查connect 因 Gateway down 退出 → 11.3「Gateway 連線異常」;OpenClaw 卡在裝置配對 → nemoclaw onboard --resume
是否修改系統launch 在 Linux 會發佈 24 小時的就緒租約(不含憑證);其餘否

OpenClaw 的差異:用 nemoclaw my-assistant dashboard-url --quiet 取得含驗證片段的 Dashboard URL(把它當密碼對待),或 nemoclaw launch my-assistant 進入 openclaw tui。

4.9 Step 8~9:發送測試請求並驗證回應

# 🖥️ Host:Deep Agents 無頭模式(沒有核准 UI,會自動核准非 shell 工具;測試用簡單問題即可)
nemo-deepagents dev-order connect
# 📦 Sandbox
dcode -n "Reply with only: hello-nemoclaw" --json

▶️ 預期 stdout 只有一個 JSON 物件,data.status 為 success、data.exit_code 為 0、data.response 含 hello-nemoclaw;程序結束碼與 data.exit_code 相同。

{
  "schema_version": 1,
  "command": "non-interactive",
  "data": {
    "status": "success",
    "exit_code": 0,
    "response": "hello-nemoclaw",
    "completion": { "thread_id": "thread-id", "duration_ms": 842, "response_bytes": 14 }
  }
}

OpenClaw 版本(📖 Commands — agent):

# 🖥️ Host:OpenClaw 必須指定 --agent、--session-id、--session-key 或 --to 其中之一
nemoclaw my-assistant agent --session-id smoke-1 -m "Reply with only: hello-nemoclaw"

失敗時的判讀:timeout 結束碼 124;stderr 會有 error_class、category、retryable、correlation_id,用 correlation_id 對照 logs。

4.10 Step 10:確認檔案、網路與憑證限制有效

這一步是驗收的核心:沒有做這一步,就不能宣稱「已在沙盒中執行」。以下以 exec 從主機送指令進沙盒(以 sandbox 使用者、HOME=/sandbox 執行)。🧪 錯誤訊息的確切字樣依映像檔而定。

# 🖥️ Host:控制有效性驗證(🏢 企業自訂驗收腳本)
S=dev-order
run(){ nemo-deepagents "$S" exec -- bash -lc "$1"; }

echo "== 1. 身分:應為 sandbox,不是 root"
run 'id -un'

echo "== 2. 系統路徑唯讀:應失敗"
run 'touch /usr/local/bin/evil 2>&1 || echo BLOCKED-OK'

echo "== 3. 工作區可寫:應成功"
run 'mkdir -p /sandbox/work && touch /sandbox/work/.probe && echo WRITE-OK'

echo "== 4. 主機機密不可見:應找不到"
run 'ls /home/*/.ssh /root/.ssh 2>&1 | head -3; echo CHECKED'

echo "== 5. 未核准網路:應被拒(CONNECT 403)"
run 'python3 -c "import urllib.request as u; u.urlopen(\"https://example.com\", timeout=10)" 2>&1 | tail -1'

echo "== 6. 環境中沒有真實推理金鑰:應無輸出"
run 'env | grep -E "nvapi-[A-Za-z0-9]{8}|sk-[A-Za-z0-9]{16}" || echo NO-RAW-KEY'

echo "== 7. Landlock 狀態(看 onboarding 輸出或 doctor)"
nemo-deepagents "$S" doctor

▶️ 預期結果:

檢查預期若不符
1sandbox⛔ 停止使用,檢查是否用了自訂映像檔或直接容器
2BLOCKED-OK 或 Read-only file system/Permission denied檢查 Landlock 是否降級(核心版本)
3WRITE-OK檢查 /sandbox 權限
4No such file or directory⛔ 若看得到主機檔案,代表有不當掛載
5Tunnel connection failed: 403 類訊息;同時 exec 會在 stderr 附加 recent network policy denial detected for example.com:443 提示若成功連線,檢查是否誤選 Personal/Open 層
6NO-RAW-KEY⛔ 若出現真實 Key,立即撤銷並調查
7無 Landlock 降級警告依 11.3 處理

📌 註記:檢查 5 的 exec 失敗提示是官方功能:exec 指令非零結束時,NemoClaw 會查詢沙盒稽核紀錄,在 stderr 附上被拒的 host:port 與後續指令(logs --tail 50、policy list、policy add)。設定 NEMOCLAW_NO_POLICY_HINT=1 可關閉。

4.11 Step 11:檢查日誌與服務狀態

# 🖥️ Host
nemoclaw status                         # 全域:沙盒清單、輔助服務、Gateway 健康
nemo-deepagents dev-order status --json > status-dev-order.json
nemo-deepagents dev-order logs --tail 100
nemo-deepagents dev-order logs --follow  # 持續串流,Ctrl+C 結束
openshell term                           # 即時網路活動;j/k 選沙盒、Enter 進入
nemoclaw doctor                          # 主機與 Gateway 唯讀檢查(不需沙盒)

✅ 建議:把 status --json、host probe --json 與 4.10 的驗收輸出存成「安裝證據」,附在環境申請單上(13.2)。

4.12 非互動安裝(CI 與標準映像)

# 🔧 CI 或 🖥️ Host:完全非互動(變數要放在 bash 這一側)
export NEMOCLAW_DISABLE_TELEMETRY=1
NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG=v0.0.139 \
NEMOCLAW_NON_INTERACTIVE=1 \
NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
NEMOCLAW_AGENT=langchain-deepagents-code \
NEMOCLAW_PROVIDER=build \
NEMOCLAW_POLICY_TIER=restricted \
NEMOCLAW_SANDBOX_NAME=ci-smoke \
NVIDIA_INFERENCE_API_KEY="$NVIDIA_INFERENCE_API_KEY" \
  bash ./install-v0.0.139.sh

NEMOCLAW_PROVIDER 可用值(📖 install.sh --help):build、openrouter、openai、anthropic、anthropicCompatible、gemini、ollama、custom、nim-local、vllm、routed、hermes-provider、llama-cpp、install-llama-cpp(別名 cloud→build、nim→nim-local)。

⚠️ 警告:非互動模式遇到上一次失敗的 onboarding session 會拒絕執行並以非零結束,避免腳本無限重試。必須明確選擇 --fresh(丟棄紀錄)或 --resume(續作),見 11.3。

4.13 本章實務案例與注意事項

案例:新進同仁照網路教學執行 curl | bash,裝到的是 v0.0.137,文件卻寫 v0.0.139 的功能。

原因是安裝程式預設追蹤 lkg 標籤。處理方式:

  1. nemoclaw --version 確認實際版本。
  2. 以 NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG=v0.0.139 重跑已審查的安裝程式(既有沙盒會先被備份並升級)。
  3. nemoclaw upgrade-sandboxes --check 確認沒有過期沙盒。
  4. 部門標準作業程序改為「一律指定版本標籤」。

注意事項:

  • 每個新 shell 都要 export NEMOCLAW_DISABLE_TELEMETRY=1;建議寫進 ~/.bashrc,並在 13.2 的申請檢查表列為必要項目。
  • 首次 onboarding 跳過 Web Search 與訊息通道;兩者之後變更都需要重建沙盒。
  • 4.10 的驗收沒有全部通過前,不得把任何專案原始碼放進沙盒。

第5章 設定管理與 CLI 操作

NemoClaw 主機上有兩套 CLI:nemoclaw(含 nemohermes、nemo-deepagents 別名)與 openshell。官方 CLI Selection Guide 的經驗法則是:會改變 NemoClaw 如何建立、重建、保存或設定沙盒的事,先用 nemoclaw;要檢查或變更即時的 OpenShell Gateway、TUI、原始政策、轉埠或推理路由時,才用 openshell。 本章所有指令皆為 📖(v0.0.139 官方 Commands 參考與 CLI 原始碼)。

5.1 兩套 CLI 的分工

任務用 nemoclaw用 openshell
建立/重建沙盒✅ onboard、rebuild⛔ 不要用 openshell sandbox create 建 NemoClaw 沙盒
套用 preset✅ policy add/remove—
整份替換政策匯出用 policy get✅ openshell policy set --policy <檔> --wait <沙盒>
即時核准網路請求—✅ openshell term
檢視生效政策policy list、policy explain✅ openshell policy get <沙盒>
傳檔✅ upload/download(會檢查沙盒是否存活、拒絕含 symlink 的目錄)openshell sandbox upload/download(刻意繞過 wrapper 時)
轉埠受管轉埠用 recover 修復使用者自建轉埠用 openshell forward start --background <port> <沙盒>
憑證✅ credentials list/add/resetopenshell provider list(只看名稱)

5.2 指令文法

nemoclaw <全域指令> [選項]               例:nemoclaw status、nemoclaw doctor、nemoclaw list
nemoclaw <沙盒名稱> <沙盒動作> [選項]    例:nemoclaw dev-order status、nemoclaw dev-order policy list
nemoclaw <沙盒名稱> exec [選項] -- <指令>  例:nemoclaw dev-order exec --workdir /sandbox/work -- ls -la
  • 省略沙盒名稱時,需要名稱的動作會印出正確格式並結束。
  • 沙盒可以剛好叫 doctor:nemoclaw doctor status 操作名為 doctor 的沙盒;nemoclaw doctor 仍是全域檢查。
  • nemoclaw use <名稱> 設定預設沙盒(取代手改 ~/.nemoclaw/sandboxes.json)。
  • nemoclaw completion bash 產生補全腳本:source <(nemoclaw completion bash)。

5.3 命令總表

操作目的命令執行位置預期結果注意事項
查看 CLI 版本nemoclaw --version🖥️ Hostnemoclaw v0.0.139不是 nemoclaw version
主機就緒報告nemoclaw host probe [--json]🖥️ Host結束碼 0/2/3唯讀
主機與 Gateway 檢查nemoclaw doctor [--json]🖥️ Host各項檢查結果不需要沙盒
全域狀態nemoclaw status [--json]🖥️ Host沙盒清單、Gateway、輔助服務只看 NEMOCLAW_GATEWAY_PORT 選定的 Gateway
列出沙盒nemoclaw list [--json]🖥️ Host名稱、模型、Provider、preset;● 表示有連線中的 sessionJSON 會遮蔽可辨識的憑證值
列出可用 Agentnemoclaw agents list🖥️ Host三個 Agent 名稱全域指令;<名稱> agents list 是 OpenClaw 內的 Agent
建立沙盒nemoclaw onboard [--agent …] [--name …]🖥️ Hostready 摘要互動精靈;CI 用 --non-interactive
續作中斷的 onboardingnemoclaw onboard --resume🖥️ Host從檢查點繼續只用於中斷,不用於重建完成的沙盒
重新建立同名沙盒nemoclaw onboard --fresh --name <名稱> --recreate-sandbox🖥️ Host新沙盒⚠️ 原沙盒會被取代,先備份
單一沙盒狀態nemoclaw <名稱> status [--json]🖥️ HostAgent 版本、Inference 健康、恢復提示會實際送一次推理請求驗證憑證
單一沙盒健康檢查nemoclaw <名稱> doctor [--json]🖥️ HostDocker、OpenShell、Gateway、路由、模型呼叫--fix 嘗試修復(OpenClaw)
連線進沙盒nemoclaw <名稱> connect🖥️ Host → 📦進入沙盒 shell會先做就緒等待與路由調和
連線並啟動 Agentnemoclaw launch <名稱>🖥️ Host直接進 Agent TUILinux 有 24 小時就緒租約
單次 Agent 回合nemoclaw <名稱> agent …🖥️ HostAgent 回應OpenClaw 需 --agent/--session-id 等選擇器;Deep Agents 轉給 dcode
在沙盒執行指令nemoclaw <名稱> exec -- <指令>🖥️ Host指令輸出與結束碼以 sandbox 使用者執行;取代 docker exec(後者以 root 執行)
停止沙盒nemoclaw <名稱> stop🖥️ Host狀態 Stopped,所有狀態保留釋放 CPU/記憶體/GPU
啟動沙盒nemoclaw <名稱> start🖥️ Host回到 Ready,修復 Gateway 與轉埠主機重開機後使用
修復沙盒nemoclaw <名稱> recover🖥️ Host恢復就緒與轉埠不開 SSH session
重啟沙盒內 Gatewaynemoclaw <名稱> gateway restart🖥️ HostGateway 重新啟動設定或 plugin 只在啟動時讀取時使用
重建沙盒nemoclaw <名稱> rebuild [--yes]🖥️ Host以新映像檔重建並還原原生 home升級 Agent 版本的正規方式
刪除沙盒nemoclaw <名稱> destroy [--yes]🖥️ Host沙盒與持久化狀態刪除⛔ 不可復原,先 download
查看日誌nemoclaw <名稱> logs [--follow] [--tail N] [--since 10m]🖥️ Host生命週期與 Gateway 輸出--tail 與 -n 相同
即時網路活動與核准openshell term🖥️ HostTUI遠端主機要先 SSH 過去
查看推理設定nemoclaw inference get [--json]🖥️ HostProvider、模型、端點不會驗證憑證
切換模型/Providernemoclaw inference set --provider <p> --model <m> [--sandbox <名稱>]🖥️ Host路由更新部分變更會觸發重建(6.14)
列出憑證nemoclaw credentials list🖥️ HostProvider 名稱不顯示值
註冊憑證nemoclaw credentials add <名稱> --type <t> --credential <ENV>🖥️ Host註冊到 Gateway值從環境變數讀,不放在 argv
移除憑證nemoclaw credentials reset <名稱>🖥️ Host從 Gateway 移除有原生附掛時會拒絕
查看 presetnemoclaw <名稱> policy list🖥️ Host已套用與可用的 preset標示 [from <tier> tier]
預覽並套用 presetnemoclaw <名稱> policy add <preset> --dry-run 後去掉 --dry-run 加 --yes🖥️ Host顯示將開放的端點增量套用(6.13)
套用自訂 presetnemoclaw <名稱> policy add --from-file <檔> [--trusted-private-host <主機>]🖥️ Host命名空間化寫入即時政策先跑 6.16 的 lint
移除 presetnemoclaw <名稱> policy remove <preset> --yes🖥️ Host收窄出口—
匯出基礎政策nemoclaw <名稱> policy get > current-policy.yaml🖥️ Host已遮蔽憑證的 YAML憑證值被換成 [STRIPPED_BY_MIGRATION]
給 Agent 看的政策摘要nemoclaw <名稱> policy explain [--json]🖥️ Host已遮蔽的允許/阻擋說明OpenClaw 會寫到 /sandbox/.openclaw/workspace/POLICY.md
下載檔案nemoclaw <名稱> download <沙盒路徑> [主機目的地]🖥️ Host檔案複製到主機拒絕含 symlink 的目錄
上傳檔案nemoclaw <名稱> upload <主機路徑> [沙盒目的地]🖥️ Host檔案複製進沙盒相對路徑以目前目錄解析
雙向掛載nemoclaw <名稱> share mount [沙盒路徑] [本機目錄]🖥️ HostSSHFS 掛到 ~/.nemoclaw/mounts/<名稱>⚠️ 雙向即時同步,見 7.2
備份所有沙盒nemoclaw backup-all🖥️ Host寫入 ~/.nemoclaw/rebuild-backups/停止中的沙盒會暫時啟動
檢查需要升級的沙盒nemoclaw upgrade-sandboxes --check🖥️ Host列出過期沙盒唯讀;有問題時非零結束
更新 CLInemoclaw update [--check]🖥️ Host執行受管安裝流程企業用固定版本重跑安裝程式(12.5)
清理孤兒映像檔nemoclaw gc --dry-run,確認後 nemoclaw gc --yes🖥️ Host移除未使用的沙盒映像檔—
收集診斷包nemoclaw debug --sandbox <名稱> --output debug.tgz🖥️ Host系統、Docker、Gateway 日誌、狀態上傳前檢查是否含敏感資訊
解除安裝nemoclaw uninstall [--yes] [--keep-openshell]🖥️ Host移除執行資源,預設保留備份⛔ --destroy-user-data、--delete-models 不可逆
匯出 v1 設定nemoclaw config export <名稱> --output nemoclaw.yaml🖥️ Hostv1alpha1 YAML,檔案權限 0600不含憑證值

5.4 查看版本與執行狀態

# 🖥️ Host:每日開工檢查(唯讀)
nemoclaw --version
nemoclaw status
nemo-deepagents dev-order status

nemoclaw <名稱> status 的關鍵欄位(🧪 實際排版依版本):

欄位意義異常時
PhaseReady/Stopped/ErrorStopped → start;Error → recover 或 rebuild
Agent執行中的 Agent 與版本顯示過期警告 → rebuild
Inference從沙盒內走 Agent 實際路徑送出的推理檢查unauthorized(HTTP 401/403)→ 憑證問題(11.3)
Recovery hints建議的修復指令照做前先讀說明

5.5 建立、啟動、停止與連線

# 🖥️ Host:一天的生命週期
nemo-deepagents onboard --name dev-order        # 建立(第一次)
nemo-deepagents launch dev-order                 # 進 TUI 工作
nemo-deepagents dev-order stop                   # 下班釋放資源(狀態保留)
nemo-deepagents dev-order start                  # 隔天恢復
nemo-deepagents dev-order connect                # 只要 shell 時

📌 註記:全域的 nemoclaw start/nemoclaw stop 已淘汰。停止沙盒請用 nemoclaw <名稱> stop;公開網址 tunnel 用 nemoclaw tunnel start/stop。

5.6 Agent 啟動、互動與任務執行

Agent互動單次任務(自動化)從主機轉送
OpenClawnemoclaw launch <名稱> 或 Dashboardnemoclaw <名稱> agent --session-id <id> -m "<訊息>" [--json]exec -- openclaw agent --agent main -m "…"
HermesDashboard 或 OpenAI 相容 API(127.0.0.1:8642,Bearer 用 gateway-token --quiet)API 呼叫exec -- hermes --version
Deep Agents Codenemo-deepagents launch <名稱> → dcode TUI📦 dcode -n "<任務>" --jsonnemo-deepagents <名稱> agent -n "<任務>" --json

Deep Agents 的兩種模式差異是工作流程設計的關鍵(📖 Run Deep Agents Code):

模式檔案寫入與編輯Shell 執行適用
互動 TUI dcode破壞性工具需逐次核准需核准(或依 shell allowlist)開發、重構、需要人在迴圈中
無頭 dcode -n自動核准停用唯讀分析、產文件、摘要
--dcode-auto-approval thread-opt-in允許個別 thread 選擇 Auto 模式(dcode -y)依模式⛔ 企業預設不開啟

⚠️ 警告:官方明言 Headless dcode -n has no approval UI and automatically approves non-shell tool requests, including file writes and edits. 用 dcode -n 做「分析」時,仍要確認工作目錄是可丟棄的副本,或原始碼以 --host-mount 唯讀掛入。

管線輸入的等待期限(v0.0.139 與 main 的差異):

  • v0.0.139:官方文件寫「沙盒內的 OpenClaw 解析器最多等 30 秒的管線輸入」。但 OpenShell 要等到主機端 stdin 結束(EOF)才會啟動沙盒內的程式,所以只要產生輸入的程式不關閉管線,沙盒內的計時根本不會開始,指令會一直卡到外層逾時(Issue #13621)。
  • main(#13646,尚未發布):改由主機端先讀完管線輸入。期限是正整數的 --timeout,沒有指定時為 30 秒,輸入上限 4 MiB。逾時、超過上限或讀取失敗時,指令以結束碼 1 結束、印出處理建議,而且不會啟動這一輪對話。
# 🖥️ Host(📖 v0.0.139 Commands 參考)
# ✅ 好例:訊息用 -m 直接給,或從檔案導入(檔案讀完就是 EOF)
nemoclaw my-assistant agent --session-id ci-1 -m "列出 src/main 下的套件" --json
nemoclaw my-assistant agent --session-id ci-1 --timeout 300 < prompt.txt

# ❌ 壞例:產生器不會結束(tail -f),v0.0.139 會卡住直到外層逾時
tail -f prompt.txt | nemoclaw my-assistant agent --session-id ci-1

▶️ 在 CI 中驗證不會卡住:外層一定要再包一層 timeout,並分辨結束碼。

# 🔧 CI
timeout 600 nemoclaw my-assistant agent --session-id "ci-$CI_JOB_ID" --timeout 300 < prompt.txt; rc=$?
[ "$rc" -eq 124 ] && echo "外層逾時:檢查輸入是否有 EOF(v0.0.139 已知行為)"

📌 註記:v0.0.139 對不支援的 --dcode-auto-approval thread-opt-in(例如用在 OpenClaw,或自訂 Dockerfile/映像檔)要到「建立沙盒」這一步才會拒絕。在那之前,Gateway 可能已經啟動,精靈也可能已經問過推理 Provider。main(#13567)已改成在 onboarding 開始前就拒絕。在 v0.0.139 遇到這種半途失敗時,先用 nemoclaw list 確認沒有留下半成品沙盒,再用正確參數重跑。

5.7 模型 Provider 與推理服務設定

# 🖥️ Host
nemoclaw inference get --json
nemoclaw my-assistant inference get

# OpenClaw/Hermes:切換到同 Provider 的另一個模型(官方範例)
nemoclaw my-assistant inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b

# OpenClaw/Hermes:切換到企業私有 OpenAI 相容端點(憑證名稱用 --credential-env 指定)
export COMPATIBLE_API_KEY='<由密碼庫取得>'
nemoclaw my-assistant inference set --provider compatible-endpoint \
  --endpoint-url https://llm-gw.corp.example/v1 --credential-env COMPATIBLE_API_KEY \
  --model corp-coder-32b
unset COMPATIBLE_API_KEY

官方列出的標準 Provider ID:nvidia-prod、nvidia-nim、nvidia-router、openai-api、openrouter-api、anthropic-prod、compatible-anthropic-endpoint、gemini-api、compatible-endpoint、hermes-provider、llama-cpp-local、ollama-local 等。私有端點若在 RFC1918 位址,還要以 NEMOCLAW_TRUSTED_PRIVATE_HOSTS 明確信任(🧪 企業 AI Gateway 的實際驗證行為需實測)。

⚠️ 警告(Deep Agents):官方 Run Deep Agents Code 頁指出,Deep Agents 的模型與 Provider 設定是烤進映像檔的,config set 不支援,要變更請「重新 onboarding 該沙盒」。inference set 的官方說明只涵蓋 OpenClaw 與 Hermes。對 Deep Agents 沙盒,切換模型以 nemo-deepagents onboard --name dev-order(相同名稱、改選模型)為準,並先做 12.3 的備份(🧪)。

5.8 網路政策的檢視、更新與驗證

# 🖥️ Host
nemoclaw dev-order policy list                       # 已套用的 preset
nemoclaw dev-order policy explain                    # 已遮蔽的允許/阻擋摘要
openshell policy get dev-order                       # OpenShell 實際生效政策
nemoclaw dev-order policy add pypi --dry-run         # 預覽
nemoclaw dev-order policy add pypi --yes             # 套用(增量)
nemoclaw dev-order policy remove pypi --yes          # 移除
nemoclaw dev-order policy exclude github --dry-run   # 預覽移除基準項目的影響

詳細設計與審查見第 6 章。

5.9 沙盒狀態與日誌查詢

# 🖥️ Host
nemoclaw dev-order logs --since 30m
nemoclaw dev-order logs --follow
nemoclaw debug --quick --sandbox dev-order
nemoclaw debug --sandbox dev-order --output ~/nemoclaw-debug-$(date +%Y%m%d%H%M).tgz

OpenShell TUI 操作(📖 Approve Network Requests):

按鍵動作
j/k選擇沙盒或規則
Enter進入沙盒檢視、查看規則詳情
r切到 Network Rules 面板
a核准選取的待審規則(加入目前沙盒實例的執行中政策)
x拒絕選取的待審規則
A核准全部待審規則(需再按 y 或 Enter 確認)——⛔ 企業禁止使用

用 status --json 判讀推理路由(🖥️ Host;📖 欄位名稱出自 v0.0.139 Commands 參考的 status 說明,🧪 實際值依你的 Provider 而定):

nemoclaw dev-order status --json \
  | jq '{provider, model, recordedRoute, liveRoute, routeDrift, inferenceHealth, failureLayer, openshellVersion}'
看到的值正確解讀下一步
liveRoute: null、routeDrift: null,Provider 是原生附掛(NVIDIA、固定託管、原生本地)正常。這類沙盒不讀共享路由,所以兩個欄位永遠是 null(自 #12886 起,v0.0.139 已包含)改看 recordedRoute 與 inferenceHealth
routeDrift 不是 null共享路由和沙盒紀錄的路由不一致先處理 drift,再相信任何端點資訊
failureLayer 不是 null(例如 docker_unreachable)發生前置故障;此時 inferenceHealth 會被設成 null,避免顯示過時的健康狀態依 failureLayer 先修 Docker 或容器
inferenceHealth 為 ok不一定代表模型真的回答過:官方說明 ok 也可能是「路由可達但沒有送請求」或原生 NVIDIA 降級要確認,就照 4.9 送一次測試請求

❌ 誤判例:監控腳本把 liveRoute == null 當成故障並發出告警。原生附掛 Provider 的沙盒會因此天天誤報;官方 Issue #13552 就曾把這個行為誤報成退化,main 的 #13648 隨後補上了文件說明。

5.10 狀態保存、恢復與資源清理

# 🖥️ Host:獨立備份(不依賴 rebuild 的內建封存)
SANDBOX=dev-order
BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
nemo-deepagents "$SANDBOX" download /sandbox/.deepagents/config.toml "$BACKUP_DIR/"
nemo-deepagents "$SANDBOX" download /sandbox/.deepagents/agent/AGENTS.md "$BACKUP_DIR/agent/"
nemo-deepagents "$SANDBOX" download /sandbox/.deepagents/agent/memories/ "$BACKUP_DIR/agent/memories/"
nemo-deepagents "$SANDBOX" download /sandbox/.deepagents/agent/skills/ "$BACKUP_DIR/agent-skills/"
nemo-deepagents "$SANDBOX" download /sandbox/work/ "$BACKUP_DIR/work/"   # 🏢 專案工作目錄

# 清理
nemoclaw gc --dry-run

5.11 安裝更新、故障復原與解除安裝

# 🖥️ Host:更新(🏢 企業以固定版本重跑已審查的安裝程式,見 12.5)
nemoclaw upgrade-sandboxes --check
nemoclaw update --check

# 解除安裝(預設保留 rebuild-backups/、backups/、sandboxes.json)
nemoclaw uninstall
旗標效果風險
--yes不詢問—
--keep-openshell保留 OpenShell—
--delete-models刪除 Ollama 回報的所有模型(包含其他應用程式使用的)⛔ 不可逆
--destroy-user-data一併刪除使用者資料⛔ 不可逆
--all-gateway-ports移除所有 Gateway 連接埠的環境影響同主機其他環境

5.12 常用環境變數

變數用途生效時機
NEMOCLAW_DISABLE_TELEMETRY=1關閉匿名遙測每個 shell
NEMOCLAW_INSTALL_TAG/NEMOCLAW_INSTALL_REF指定安裝版本(REF 優先)安裝
NEMOCLAW_NON_INTERACTIVE=1、NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1非互動安裝安裝/onboarding
NEMOCLAW_NO_EXPRESS=1跳過 Express 提示安裝
NEMOCLAW_AGENTopenclaw、hermes、langchain-deepagents-code安裝/onboarding
NEMOCLAW_SANDBOX_NAME沙盒名稱onboarding
NEMOCLAW_PROVIDER、NEMOCLAW_MODEL、NEMOCLAW_ENDPOINT_URL推理選擇onboarding
NEMOCLAW_POLICY_TIERrestricted、balanced、open、personalonboarding
NEMOCLAW_POLICY_MODEsuggested、custom、skiponboarding
NEMOCLAW_TRUSTED_PRIVATE_HOSTS逗號分隔的精確私有主機推理、託管 MCP、自訂 preset 註冊
NEMOCLAW_PROXY_HOST/NEMOCLAW_PROXY_PORT沙盒出口 Proxy(預設 10.200.0.1:3128)建置期,變更需重新 onboarding
NEMOCLAW_CORPORATE_CA_BUNDLE企業 CA PEM建置期,既有沙盒需 rebuild
NEMOCLAW_GATEWAY_PORTOpenShell Gateway 連接埠(預設 8080)所有指令
NEMOCLAW_LOG_LEVELerror、warn、info、debug所有指令
NEMOCLAW_RESOURCE_PROFILE、NEMOCLAW_CPU、NEMOCLAW_RAM沙盒 CPU/記憶體onboarding
NEMOCLAW_SANDBOX_READY_TIMEOUT建立後就緒等待秒數(預設 180)onboarding
NEMOCLAW_LOCAL_INFERENCE_TIMEOUT本地推理驗證逾時(預設 180)onboarding
NEMOCLAW_EXPERIMENTAL=1顯示實驗性 Provideronboarding(⛔ 企業預設不開)
NEMOCLAW_NO_POLICY_HINT=1關閉 exec 失敗時的政策提示exec
NEMOCLAW_NO_CONNECT_HINT=1關閉 connect 的提示connect

5.13 版本差異與淘汰指令

指令狀態改用
nemoclaw setup淘汰(相容別名)nemoclaw onboard
nemoclaw setup-spark淘汰標準安裝程式+nemoclaw onboard
nemoclaw start(全域)淘汰nemoclaw <名稱> start 或 nemoclaw tunnel start
nemoclaw stop(全域)淘汰nemoclaw tunnel stop
nemoclaw <名稱> config set(OpenClaw)不支援進沙盒用 openclaw configure/openclaw config set
nemoclaw <名稱> config set(Deep Agents)不支援重新 onboarding
NEMOCLAW_DISABLE_DEVICE_AUTH=1無效(OpenClaw 2026.9.1 已移除繞過)依正常配對流程
v1 線的 plan/apply/destroy屬另一條產品線見 1.7,不適用 v0.0.x

5.14 偽指令說明(概念用,不可直接執行)

有些企業需求目前沒有官方指令。為了說明概念,本手冊以 # 偽指令 標記,不可複製執行:

# 偽指令:概念示意,NemoClaw v0.0.139 沒有這些指令
nemoclaw fleet status --all-hosts          # 多主機集中管理(官方:Manual or admin-only)
nemoclaw audit export --siem splunk        # 集中稽核匯出(官方:Manual or admin-only)
nemoclaw rbac grant reviewer alice         # 操作者 RBAC(官方:Out of scope)
nemoclaw budget set --monthly 200usd       # 成本上限(官方:Platform or partner-owned)

對應的企業替代做法分別見 14.7(稽核)、13.1(角色)、14.10(成本)。

5.15 本章實務案例與注意事項

案例:同仁用 docker exec -it <容器> bash 進沙盒除錯,結果在裡面以 root 改了檔案。

  • 官方說明:docker exec 以 root 執行並落在不同的環境;支援的替代是 nemoclaw <名稱> exec(以 sandbox 使用者、HOME=/sandbox 執行)或 connect。
  • exec 結束後,NemoClaw 會驗證並必要時還原 OpenClaw 設定的權限契約;docker exec 不會。
  • 處置:nemoclaw <名稱> doctor 檢查,必要時 rebuild;並在 13.11 的禁止清單加入「不得以 docker exec 操作 NemoClaw 沙盒」。

注意事項:

  • 表格中的旗標以 v0.0.139 為準;升級後先跑 nemoclaw help 與 nemoclaw <名稱> --help(🧪)比對。
  • 會刪資料的指令(destroy、uninstall --destroy-user-data、--recreate-sandbox)一律先 download 或 backup-all。

第6章 安全架構與政策管理

本章是全書的核心。前半(6.1~6.10)說明 NemoClaw 在每一層提供什麼控制、控制的極限在哪裡;後半(6.11~6.16)手把手寫出一份教學用最小權限政策,套用、驗證、並教你如何審查 AI 幫你寫的政策。所有政策格式依 v0.0.139 的 Blueprint 與官方 preset 原始檔(📖),搭配 OpenShell 0.0.116。

6.1 五層防護與套用時機

層保護什麼執行點何時套用能否執行期變更
網路只允許政策列出的主機/連接埠/方法/路徑/程式OpenShell Gateway 與 L7 代理每個請求✅ 可熱更新
檔案系統系統路徑唯讀,只有 /sandbox、/tmp 等可寫Landlock(核心)+容器掛載沙盒建立時鎖定❌ 需重建
程序阻擋提權與危險系統呼叫、限制程序數seccomp、no-new-privileges、非 root 使用者、ulimit沙盒建立時鎖定❌ 需重建
Gateway 驗證哪些裝置與客戶端能連到 Agent GatewayOpenClaw 裝置配對、Hermes bearer token建立時部分
推理Agent 能用哪些模型、走哪條路由OpenShell 推理路由與附掛 Provider每個請求✅ 可熱更新

📌 註記:官方 Security Best Practices 頁強調,OpenShell 執行 NemoClaw 所設定的平台機制(網路命名空間隔離、seccomp、SSRF 防護、TLS 終結、Gateway 驗證)。NemoClaw 決定「設成什麼」,OpenShell 決定「怎麼擋」。

6.2 沙盒隔離與檔案系統限制

各 Agent 的檔案系統基準(📖 nemoclaw-blueprint/policies/openclaw-sandbox.yaml、agents/*/policy-additions.yaml):

項目OpenClawHermesDeep Agents Code
可寫/sandbox(include_workdir: true)、/tmp、/dev/null、/dev/pts、/sandbox/.openclaw、/sandbox/.nemoclaw、/home/linuxbrew/sandbox、/tmp 等/sandbox、/sandbox/.deepagents、/run/nemoclaw-dcode-mcp、/tmp、/dev/null
唯讀/usr、/lib、/proc、/dev/urandom、/app、/etc、/var/log、/var/lib/dpkg同類同上,另加 /opt/venv(保護釘選的 dcode harness)
Landlockbest_effort(核心不支援時靜默降級)best_effortstrict(無法執行時沙盒啟動失敗,fail closed)
執行身分sandbox:sandboxsandbox:sandboxsandbox:sandbox

主機目錄的兩種帶入方式:

方式方向支援安全性
nemoclaw onboard --host-mount /主機/目錄:/sandbox/目錄主機 → 沙盒,唯讀Linux/WSL 2 上的 Docker;macOS、原生 Windows、Podman、K8s 不支援✅ 適合逆向工程:Agent 改不到原始檔
nemoclaw <名稱> share mount雙向 SSHFS主機需有 SSHFS⚠️ 主機端編輯即時進沙盒、沙盒端寫入即時回主機;等於把沙盒的寫入能力延伸到主機目錄

⚠️ 警告:--host-mount 只在 onboarding 時宣告,沒有讀寫模式。不要為了「讓 Agent 直接改主機上的專案」而改用 share mount 掛整個家目錄;應改為在沙盒內 git clone 工作副本(7.2)。

6.3 網路:預設拒絕與允許清單

運作方式(📖 Network Policies、Security Best Practices):

  1. 沙盒的所有出站流量都經過 OpenShell 的 CONNECT 代理。
  2. 政策比對「主機+連接埠+發起程式」;有 protocol: rest 的端點再比對 HTTP 方法與路徑(L7)。
  3. 未列出的請求被擋下、記錄,並出現在 openshell term 等候核准。
  4. OpenShell 另外硬性封鎖未指定、迴環、link-local 位址(含常見的雲端 metadata 範圍);私有位址需要明確的 allowed_ips(由 NemoClaw 的 --trusted-private-host 產生)。

程式身分(binary)比對:OpenShell 讀取 /proc/<pid>/exe(核心可信的執行檔路徑,不是 argv[0]),往上走訪程序樹找祖先程式,並在第一次使用時計算執行檔的 SHA-256;執行期間若執行檔被替換,雜湊不符會立即拒絕。路徑支援 glob:* 比對一層、** 遞迴。

L4 與 L7 的差別:

寫法檢查內容用途風險
沒有 protocol(例如 access: full)主機、連接埠、程式無法被 L7 檢查的協定(Git over HTTPS 的部分客戶端、WebSocket 相容問題)放行後整條 TCP 串流都不看內容
protocol: rest+enforcement: enforce+rules再加上每個 HTTP 請求的方法與路徑REST API、套件庫規則寫太寬(POST /**)等於沒限制
protocol: websocket/json-rpc/mcp對應協定的方法(MCP 可再比對 tool)WebSocket、MCP—

核准的持久性(官方兩頁的說法需合併理解):

情境結果
在 openshell term 核准合併為該沙盒政策的新版本,同一沙盒實例內重啟仍有效
destroy 後重新 onboarding回到 Blueprint 基準,一次性核准消失
要讓未來的沙盒也有效寫成 preset(6.11)或改基準政策

⚠️ 警告:官方 Best Practices:If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. 企業規範:openshell term 只能核准「已有申請單、範圍精確」的請求,禁止 A(全部核准)。

6.4 程序權限與系統呼叫限制

控制預設由誰執行限制
非 rootAgent、Gateway、supervisor 以 sandbox 執行(OpenShell 0.0.116 拒絕 root OCI 使用者)映像檔+OpenShell同 UID,彼此無隔離(2.4)
no-new-privilegesOpenShell 以 prctl(PR_SET_NO_NEW_PRIVS) 設定OpenShell—
seccomp過濾危險系統呼叫、socket domainOpenShell—
CapabilitiesOpenShell 負責受管程序的 capabilityOpenShell直接用 Docker 啟動時要自己加 --cap-drop=ALL
程序數ulimit -u 512映像檔 entrypointbest effort:Runtime 不允許時只記警告;Deep Agents 較嚴格(每次啟動都套用並驗證)
檔案描述元ulimit -n 65536同上同上
PATH 鎖定/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin(Deep Agents 加 /opt/venv/bin)entrypoint—
移除工具鏈清除 gcc、g++、cpp、make、netcat 系列Dockerfile自訂映像檔要自己決定(7.3)

✅ 建議:若需要硬性的資源上限(fail closed),官方建議由容器 Runtime 設定;企業共用主機應另以 Docker 的 --memory、--cpus 或 NEMOCLAW_RESOURCE_PROFILE(Blueprint 定義的 creator、developer 等 profile)限制(🧪 實際效果依 Runtime)。

6.5 外部 API 與模型服務存取控制

對象控制方式審查重點
推理服務附掛 Provider 限制主機、路徑、方法、程式;或共享路由 inference.local不要在政策中額外開放推理供應商的其他路徑(例如檔案上傳 API)
託管 MCPnemoclaw <名稱> mcp add <名稱> --url https://… --env <TOKEN_ENV>;可加 --deny-tool 'delete_*'只接受 HTTPS Streamable HTTP;deny 規則只比對工具名稱、不檢查參數
一般 REST API自訂 preset,protocol: rest+精確路徑讀寫分離(6.11)
Web Searchbrave/tavily preset+獨立 Provider搜尋查詢本身就是一種外送資料

託管 MCP 範例(📖 Commands — mcp add):

# 🖥️ Host:Token 只存在當下 shell,註冊後立即 unset
export LOCAL_MCP_TOKEN='<由密碼庫取得>'
nemo-deepagents dev-order mcp add jira-ro \
  --url https://mcp.corp.example/mcp \
  --env LOCAL_MCP_TOKEN \
  --trusted-private-host mcp.corp.example \
  --deny-tool 'create_*' --deny-tool 'delete_*' --deny-tool 'update_*'
unset LOCAL_MCP_TOKEN
nemo-deepagents dev-order mcp status jira-ro

6.6 API Key、Token、SSH 金鑰與其他敏感憑證管理

憑證NemoClaw 的處理企業規範(🏢)
推理 API Key註冊到 OpenShell Gateway;沙盒內為 placeholder專案專屬、設預算上限、季度輪替
託管 MCP Token只記錄名稱與擁有者;值由 Gateway 保管唯讀 scope 優先
Web Search Key沙盒專屬 Provider;變更需重建非必要不開
訊息通道 Token(Slack 等)Gateway 保管;登錄檔只存 SHA-256⛔ 企業預設禁止訊息通道
GitHub TokenNemoClaw 不保存;需要時呼叫 gh auth token用 OS keychain;限單一 repo
SSH 私鑰沒有內建機制⛔ 不得放進沙盒;Git 一律走 HTTPS+受控 Token
舊版 ~/.nemoclaw/credentials.json早期版本以明文 JSON(權限 0600)儲存;升級後第一次 onboarding 自動遷移遷移後確認檔案已移除或清空(🧪)

憑證輪替與緊急處置(📖 Credential Rotation):

# 🖥️ Host:輪替推理 Key(沿用既有沙盒)
printf 'New NVIDIA inference API key: ' >&2
IFS= read -r -s NVIDIA_INFERENCE_API_KEY; printf '\n' >&2
export NVIDIA_INFERENCE_API_KEY
nemoclaw onboard --name dev-order --non-interactive --yes --yes-i-accept-third-party-software
unset NVIDIA_INFERENCE_API_KEY

# 驗證新 Key 真的能用(status 會實際送推理請求;credentials list 只證明 Provider 存在)
nemo-deepagents dev-order status

外洩時的處置順序(官方 Emergency Rotation):

  1. 先在上游供應商撤銷外洩的憑證——不要依賴本機清理。
  2. 推理或 Web Search:若沒有立即可用的替代 Key,nemoclaw credentials reset <Provider 名稱> 移除。
  3. 訊息通道:channels remove 或以新憑證重新 onboarding。
  4. 🏢 依 13.9 通報資安,保存 debug 診斷包與 logs 輸出。

6.7 Prompt Injection、惡意程式碼與不可信文件

Agent 讀到的每一份文件、網頁、Issue、套件 README、程式碼註解,都可能夾帶指令。沙盒不能阻止 Agent「被說服」,只能縮小「被說服之後能做什麼」。

攻擊情境例子沙盒擋得住嗎補強控制(🏢)
文件夾帶「把 .env 貼到某網址」待分析的舊系統 README 有隱藏指令目的地未核准則擋(CONNECT 403)不在沙盒放 .env;拒絕 TUI 中的未知請求
利用已核准端點外送指示 Agent 建立公開 GitHub Gist 或 repo❌ 若 github.com 為 access: full 則擋不住排除 Deep Agents 的 github 基準項目,改用內部 Git 精確路徑(6.11)
惡意套件依賴混淆(dependency confusion)的 npm 套件❌ 若 npm preset 已開改走企業代理庫並開啟掃描;Restricted 層
誘導執行破壞性指令「請執行 rm -rf /sandbox/work」只能影響沙盒內Deep Agents 互動模式逐次核准 shell;工作副本可丟棄
竄改測試讓 CI 綠燈刪除失敗的測試或加 @Disabled❌ 屬內容層7.10 交付報告比對+人工 review
在程式碼植入後門加一條未授權的 API 路由❌ 屬內容層Code Review、SAST、架構測試

✅ 建議:把「Agent 會讀到的不可信內容」與「Agent 能寫出去的通道」分開。逆向工程時原始碼唯讀掛入、網路只開推理;開發時只開專案 repo 與內部代理庫。兩者同時寬鬆時風險最大。

6.8 透過允許的網路外洩資料

官方原則:Each allowed endpoint is a potential data exfiltration path. 實務上要逐條問三個問題:

  1. 這條規則允許「寫」嗎?(POST、PUT、PATCH、DELETE、L4 access: full)
  2. 寫的對象是誰能看到的?(公開 SaaS、內部系統、自己的 repo)
  3. 哪些程式能用?(只有 git?還是任何 Python 腳本?)
常見規則外洩風險收斂方式
Deep Agents 基準的 github.com/api.github.com access: full可推送到任何 GitHub repo、建立 Gistpolicy exclude github,改用內部 Git preset
pypi preset 的 binaries 包含 python3*沙盒內任何 Python 腳本都能連 PyPIPyPI 只開 GET/HEAD(官方 preset 已是如此);上傳路徑不開
官方 outlook preset 允許 graph.microsoft.com 的 PATCH /**可修改信箱資料Open 層才有;企業不用 Open
推理服務本身Prompt 內容就是外送資料依資料分級選擇私有或外部模型(13.6)
Personal 層任何 80/443 目的地⛔ 禁用

6.9 套件安裝、依賴下載與供應鏈攻擊

供應鏈環節NemoClaw 的現況企業補強
安裝程式HTTPS 下載;payload 只檢查 shebang4.3 的下載審查與固定版本
OpenShell 執行檔安裝時比對官方 checksum 檔;strings 驗證內部鏡像時保留 checksum
沙盒映像檔@sha256 digest 釘選;三個 Agent 映像檔需屬同一發佈批次企業 registry 代理不得改寫 digest
自訂映像檔(--from)由你負責;NemoClaw 只做 secret-safety 排除(.env*、.ssh/、*.pem、*.key 等不進 build context)映像檔掃描(Trivy 等)、SBOM(CycloneDX/SPDX)、簽章
執行期套件安裝(npm、pip、brew)Balanced 層預設開 npm、pypi、brew-balancedRestricted 層+內部代理庫 preset;官方也建議能在建置期裝的就不要在執行期裝
本地模型映像檔v0.0.139 起 llama.cpp 映像檔有 Sigstore 簽章驗證簽章後再使用(🧪)

參考標準:SLSA、NIST SSDF SP 800-218、CycloneDX。

6.10 稽核日誌、異常監控與事件處理

資料來源取得方式內容限制
生命週期與 Gateway 日誌nemoclaw <名稱> logsonboarding、Gateway、政策拒絕拒絕紀錄可讀性仍在改善(issue #4760)
即時網路活動openshell term主機、連接埠、程式、方法互動式,不是長期儲存
OpenClaw 對話nemoclaw <名稱> sessions export --format tar --out x.tgzsession JSONL、trajectory需手動逐沙盒匯出
Hermes 狀態nemoclaw <名稱> sessions export單一 JSONL同上
Deep Agents 追蹤--observability 送 OTLP 到主機端 collector有界內容的 trace內容可能含敏感資料;本地接收端無驗證
診斷包nemoclaw debug --output系統、Docker、Gateway上傳前要檢查
flowchart TD
    A["偵測<br/>CONNECT 403 異常增加、未知 binary、推理費用暴增"] --> B["遏止<br/>nemoclaw 名稱 stop"]
    B --> C["保全證據<br/>logs、debug 診斷包、sessions export"]
    C --> D{"憑證可能外洩?"}
    D -- 是 --> E["上游撤銷憑證<br/>credentials reset"]
    D -- 否 --> F["分析<br/>政策、核准紀錄、Agent 對話"]
    E --> F
    F --> G["根因修正<br/>收斂 preset、更新規範"]
    G --> H["復原<br/>rebuild 或 destroy 後重建"]
    H --> I["事後檢討<br/>更新 13.11 允許/禁止表"]

🏢 企業建議:在主機上以 cron 每小時執行 nemoclaw <名稱> logs --since 1h 並轉送到企業日誌平台(🧪 輸出格式未保證穩定,解析前需實測)。官方目前把 SIEM 整合列為 Manual or admin-only。

6.11 教學用最小權限政策範例

情境:開發沙盒 dev-order 要讓 Deep Agents Code 開發 order-service。需求只有三項:

  1. 從內部 Nexus 的 maven-public 代理庫讀取 Maven 依賴。
  2. 從內部 Git clone/fetch demo/order-service 這一個 repo。
  3. 推送到同一 repo——寫入權限另外申請、預設不套用。

設計原則:一個 preset 一個用途;讀與寫拆成不同 preset;路徑寫到 repo 層級;程式只放行真正發起連線的那一個。

# presets/corp-maven-readonly.yaml(🏢 企業自訂;✅ 已通過 6.16 lint)
preset:
  name: corp-maven-readonly
  description: "內部 Nexus Maven 代理庫(唯讀);核准單 CHG-2026-0412"
network_policies:
  corp_maven_readonly:
    name: corp_maven_readonly
    endpoints:
      - host: nexus.corp.example
        port: 443
        protocol: rest
        enforcement: enforce
        rules:
          - allow: { method: GET, path: "/repository/maven-public/**" }
          - allow: { method: HEAD, path: "/repository/maven-public/**" }
    binaries:
      - { path: /usr/lib/jvm/java-21-openjdk-amd64/bin/java }
# presets/corp-git-order-read.yaml(🏢 企業自訂;✅ 已通過 6.16 lint)
preset:
  name: corp-git-order-read
  description: "內部 Git:order-service 唯讀(clone/fetch)"
network_policies:
  corp_git_order_read:
    name: corp_git_order_read
    endpoints:
      - host: git.corp.example
        port: 443
        protocol: rest
        enforcement: enforce
        rules:
          - allow: { method: GET, path: "/scm/demo/order-service.git/info/refs" }
          - allow: { method: POST, path: "/scm/demo/order-service.git/git-upload-pack" }
    binaries:
      - { path: /usr/bin/git }
# presets/corp-git-order-write.yaml(🏢 企業自訂;需另經核准才套用)
preset:
  name: corp-git-order-write
  description: "內部 Git:order-service 推送(需另經核准)"
network_policies:
  corp_git_order_write:
    name: corp_git_order_write
    endpoints:
      - host: git.corp.example
        port: 443
        protocol: rest
        enforcement: enforce
        rules:
          - allow: { method: POST, path: "/scm/demo/order-service.git/git-receive-pack" }
    binaries:
      - { path: /usr/bin/git }

逐欄解說:

欄位寫法為什麼
preset.name小寫 RFC 1123 label,且不與官方 preset 同名官方規則;檔名(去掉 .yaml)要與 preset.name 一致才能用名稱套用
network_policies 的 key用底線(corp_maven_readonly)與官方 preset 慣例一致;npm_yarn、personal_open_internet 是保留鍵
protocol: rest+enforcement: enforce明確寫出沒寫 protocol 就只有 L4;🏢 本手冊一律明寫 enforce,不依賴預設值
讀寫分離Git 的 smart HTTP:讀=GET …/info/refs+POST …/git-upload-pack;寫=POST …/git-receive-pack只套用讀 preset 時,Agent 無法 git push
路徑到 repo 層級/scm/demo/order-service.git/…其他 repo 一律拒絕;換專案就另一份 preset
binaries只放 git;Maven 放 javaMaven 的 mvn 是腳本,實際連線的程序是 java;OpenShell 看的是 /proc/<pid>/exe
不寫 allowed_ips改在套用時用 --trusted-private-host官方禁止自訂 preset 宣告 allowed_ips;NemoClaw 會解析並把位址釘死

🧪 待驗證:(1) Git 的 info/refs 請求帶查詢字串 ?service=git-upload-pack,路徑規則是否只比對路徑部分,需實機確認;(2) java 的實際路徑取決於自訂映像檔(7.3);(3) Git 用 git-remote-https 子程序連線,政策以祖先程式 git 比對(官方 github preset 也只列 /usr/bin/git),但請以 openshell term 回報的 binary 為準。

⚠️ 新增網路目的地的風險:每加一條端點,就問 6.8 的三個問題,並在申請單(13.4)寫明「允許的方法、路徑、程式、資料敏感度、到期日」。內部系統一樣算外洩通道——內部 Wiki 允許 POST,Agent 就能把程式碼貼上去。

6.12 套用與驗證政策

# 🖥️ Host:1. 靜態檢查(6.16)
python3 nemoclaw-policy-lint.py preset presets/corp-*.yaml

# 2. 預覽(私有主機必須明確信任;dry-run 會顯示產生的位址釘選)
nemo-deepagents dev-order policy add \
  --from-file presets/corp-maven-readonly.yaml \
  --trusted-private-host nexus.corp.example --dry-run

# 3. 套用唯讀 preset
nemo-deepagents dev-order policy add --from-file presets/corp-maven-readonly.yaml \
  --trusted-private-host nexus.corp.example --yes
nemo-deepagents dev-order policy add --from-file presets/corp-git-order-read.yaml \
  --trusted-private-host git.corp.example --yes

# 4. 確認生效
nemo-deepagents dev-order policy list
openshell policy get dev-order | grep -A3 corp_

驗證「該通的通、不該通的不通」(📦 透過 exec 執行;🧪 輸出依環境):

#測試指令(nemo-deepagents dev-order exec -- bash -lc '…')預期
V1允許的 repo 可 clonegit clone https://git.corp.example/scm/demo/order-service.git /sandbox/work/order-service成功
V2其他 repo 被拒git ls-remote https://git.corp.example/scm/demo/payment.gitCONNECT tunnel failed, response 403 或 HTTP 403
V3推送被拒(未套用寫入 preset)cd /sandbox/work/order-service && git push origin HEAD:ai/test被拒
V4允許的程式以外被拒curl -sS https://nexus.corp.example/repository/maven-public/被拒(curl 不在 binaries)
V5未列出主機被拒curl -sS https://example.com被拒
V6拒絕有紀錄🖥️ nemo-deepagents dev-order logs --tail 50看得到 V2~V5 的拒絕

✅ 建議:把 V1~V6 寫成腳本,每次修改 preset 後重跑,結果附在變更單上。只測「能通」不測「不能通」的政策驗收,不算完成。

6.13 政策更新是增量還是整份替換

這是最常出錯的地方。四種方式的語意不同:

方式語意保存在哪刪除重建後
nemoclaw <名稱> policy add <preset> 或 --from-file增量:把 preset 以命名空間化的 key 合併進即時政策;同名且內容相同則不變,不同則預覽後再套用OpenShell 即時政策若用 onboarding 重建會回到所選層級+preset;rebuild 會整份帶過去
openshell term 核准增量:合併為新的政策版本OpenShell 即時政策消失
openshell policy update <沙盒> --add-endpoint host:443:read-only:rest:enforce增量(OpenShell CLI 的動態變更,官方 Network Policies 頁範例)OpenShell 即時政策消失
openshell policy set --policy <檔> --wait <沙盒>整份替換:不合併,檔案裡沒有的項目全部消失OpenShell 即時政策(成為持久的即時政策)依重建方式
修改 Blueprint 基準政策檔後 nemoclaw onboard改變未來沙盒的基準原始碼樹生效

⚠️ 警告(整份替換):官方 Replace the Live Network Policy 頁原文:Applying a file that contains only one part silently removes the other entries. 正確流程是:nemoclaw <名稱> policy get > current-policy.yaml(不要加 --raw)→ 只在 network_policies 下新增 → 把每一個 [STRIPPED_BY_MIGRATION] 換回正確的 OpenShell 憑證綁定或 resolver placeholder → openshell policy set。openshell policy set 不接受 preset 格式(preset: 開頭)的檔案。managed_inference 項目不可移除。

6.14 哪些設定可執行期更新、哪些必須重建

設定生效方式操作
網路 preset執行期,下一個請求生效policy add/remove
網路允許清單(單一端點)執行期openshell term 核准或 openshell policy update
推理模型(同 Provider)執行期(OpenClaw/Hermes)inference set
推理 Provider執行期路由更新,必要時重建映像檔inference set;Deep Agents 需重新 onboarding
託管 MCP 的 deny-tool執行期mcp update
Gateway 程序環境、只在啟動讀取的 plugin 狀態重啟 Gateway 後gateway restart
Dashboard 轉送連接埠下次 connectNEMOCLAW_DASHBOARD_PORT=<port> nemoclaw <名稱> connect
Dashboard 綁定位址需重建NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw onboard --recreate-sandbox(⛔ 企業不開)
訊息通道新增、啟用、停用、Token需重建channels add/stop/start 後接受重建
Web Search Provider需重建重新 onboarding 並重建
檔案系統配置建立時鎖定onboard --recreate-sandbox
程序控制(seccomp、使用者)建立時鎖定重建
沙盒名稱建立時鎖定以新名稱 onboarding
GPU 直通建立時鎖定--gpu/--sandbox-gpu-device 重新 onboarding
企業 Proxy(NEMOCLAW_PROXY_HOST)建置期重新 onboarding
企業 CA建置期rebuild
Deep Agents 自動核准能力建置期(烤進唯讀檔)rebuild --dcode-auto-approval …
--host-mount建立時重新 onboarding

來源:Understand Runtime Changes、How It Works — Protection Layers

6.15 不同 Agent 的政策差異

不可假設三個 Agent 能套用完全相同的政策:

面向OpenClawHermesDeep Agents Code
基準政策檔nemoclaw-blueprint/policies/openclaw-sandbox.yamlagents/hermes/policy-additions.yamlagents/langchain-deepagents-code/policy-additions.yaml
基準網路項目nvidia、managed_inference、clawhub、openclaw_api、openclaw_docs、npm_registrymanaged_inference、nvidia、nous_research、pypimanaged_inference、observability-otlp-local、github(access: full)、pypi
可排除的基準項目(policy exclude)nvidia、clawhub、openclaw_api、openclaw_docs、npm_registrynvidia、nous_research、pypigithub、observability-otlp-local、pypi
不可排除managed_inferencemanaged_inferencemanaged_inference
發起連線的程式/usr/local/bin/openclaw、nodeHermes 的 Python/usr/local/bin/dcode、/opt/venv/bin/python3*
自訂 preset 的 binaries用 openshell term 回報的路徑同左官方提醒常見為 /usr/local/bin/dcode 或 /opt/venv/bin/python3*(後者等於所有沙盒內 Python)
訊息通道 preset支援支援不適用(沒有訊息 bridge)

可排除清單出自 v0.0.139 src/lib/policy/baseline-exclusion.ts(📖)。沒有列在清單裡的基準項目,policy exclude 會拒絕。

6.16 審查 AI 產出的政策

讓 AI 幫忙寫 preset 很有效率,但 AI 的預設傾向是「先讓它能動」。以下教你三步審查:工具快篩 → 人工逐條 → 拒絕測試。

1. 工具快篩:nemoclaw-policy-lint.py(✅ 已實測)

本手冊附的 🏢 企業自訂 lint 工具(完整原始碼見 18.10.1),規則如下:

規則等級檢查
N01ERROR/WARNpreset.name 非 RFC 1123、與官方同名;缺 description
N02ERROR使用官方保留鍵 npm_yarn、personal_open_internet
N03ERRORhost 為 *、0.0.0.0、CIDR、或萬用字元只到頂級網域(*.com)
N04ERROR自訂 preset 宣告 allowed_ips
N05WARN/ERROR沒有 binaries(規則不授權任何程式);沒有 network_policies
N06WARN沒有 protocol(L4-only)
N07ERROR有 protocol 卻沒寫 enforcement: enforce,或沒有 rules
N08ERROR/WARNmethod: "*";PUT/PATCH/DELETE 配 /**;POST /**
N10ERROR/WARNbinaries 為 /**、/usr/bin/* 等;直譯器(python3*、node、curl)
N11ERROR疑似明文憑證(nvapi-、sk-、ghp_、xoxb-、AKIA、Bearer …)
N12ERROR仍有 [STRIPPED_BY_MIGRATION]
N13ERROR整份 policy 模式:缺 version、是 preset 格式、缺 managed_inference
N14WARNtls: skip

❌ 壞例(AI 在「讓 Agent 能呼叫內部 API」的要求下產生;只用於審查訓練):

# 壞例:AI 產生的「先讓它能動」preset,只用於審查訓練
preset:
  name: Corp_API
network_policies:
  npm_yarn:
    name: npm_yarn
    endpoints:
      - host: "*"
        port: 443
      - host: api.corp.example
        port: 443
        protocol: rest
        allowed_ips: ["10.0.0.0/8"]
        rules:
          - allow: { method: "*", path: "/**" }
          - allow: { method: DELETE, path: "/**" }
    binaries:
      - { path: "/**" }
  helper:
    name: helper
    endpoints:
      - host: "*.com"
        port: 443
        protocol: rest
        enforcement: enforce
        headers: { Authorization: "Bearer abcdefghijklmnopqrstuvwxyz123456" }
        rules:
          - allow: { method: POST, path: "/**" }
    binaries:
      - { path: /usr/bin/curl }

🔍 執行 lint(✅ 實際輸出):

$ python3 nemoclaw-policy-lint.py preset bad-preset.yaml
ERROR N11 bad-preset.yaml network_policies.helper.endpoints[0].headers.Authorization: 疑似明文憑證;改用 OpenShell provider/placeholder
ERROR N01 bad-preset.yaml preset.name: 'Corp_API' 不是小寫 RFC 1123 label
WARN  N01 bad-preset.yaml preset.description: 缺少 description(審查與 policy list 時難以辨識)
ERROR N02 bad-preset.yaml network_policies.npm_yarn: 'npm_yarn' 是官方保留鍵
ERROR N10 bad-preset.yaml network_policies.npm_yarn: binary '/**' 範圍過大
ERROR N03 bad-preset.yaml network_policies.npm_yarn.endpoints[0]: host '*' 是全開或 CIDR 目的地,官方會拒絕
WARN  N06 bad-preset.yaml network_policies.npm_yarn.endpoints[0]: '*' 沒有 protocol(L4-only,access=None);只看主機與程式,不檢查方法與路徑
ERROR N04 bad-preset.yaml network_policies.npm_yarn.endpoints[1]: 自訂 preset 不得宣告 allowed_ips(改用 --trusted-private-host)
ERROR N07 bad-preset.yaml network_policies.npm_yarn.endpoints[1]: 'api.corp.example' 有 protocol 但未明確寫 enforcement: enforce
ERROR N08 bad-preset.yaml network_policies.npm_yarn.endpoints[1].rules[0]: 'api.corp.example' method '*' 等於允許所有方法
ERROR N08 bad-preset.yaml network_policies.npm_yarn.endpoints[1].rules[1]: 'api.corp.example' DELETE /**:寫入/刪除方法不可配全路徑
WARN  N10 bad-preset.yaml network_policies.helper: binary '/usr/bin/curl' 是直譯器或通用下載工具,等於沙盒內任何腳本都能用
ERROR N03 bad-preset.yaml network_policies.helper.endpoints[0]: host '*.com' 萬用字元範圍過大(只到頂級網域)
WARN  N08 bad-preset.yaml network_policies.helper.endpoints[0].rules[0]: '*.com' POST /**:請收斂到實際 API 路徑
結果:10 ERROR,4 WARN

好例(6.11 的三份 preset)的輸出是 結果:0 ERROR,0 WARN,結束碼 0。整份 policy 模式的壞例(只放新端點就要 policy set、還留著 [STRIPPED_BY_MIGRATION])會得到 N12 與 N13 兩個 ERROR。

📌 註記:拿官方 preset 跑這支工具,一定會出現 N01(因為與官方同名)——工具只用於自訂 preset。它也會對官方 preset 標出值得注意的寬鬆處,例如 pypi 的 binaries 包含 python3*(N10 WARN)、outlook 的 PATCH /**(N08 ERROR)、Deep Agents 基準的 github 為 L4(N06 WARN)。這些是官方的設計取捨,企業要知情後再決定是否採用。

2. 人工逐條審查清單:

  • 每個 host 都有申請單,且是精確主機名(不是 *.corp.example)。
  • 每條 rules 的方法與路徑都能對應到實際需要的 API;POST 有理由。
  • 讀與寫分在不同 preset;寫入 preset 有獨立核准。
  • binaries 只有真正發起連線的程式;不含 python3*、node、curl,除非有理由。
  • 沒有 allowed_ips、沒有 tls: skip、沒有任何憑證字串。
  • 私有主機在套用時以 --trusted-private-host 指定,並在 dry-run 輸出中確認釘選的位址正確。

3. 拒絕測試:6.12 的 V1~V6 全部符合預期,才可在變更單上簽核。

6.17 安全公告與弱點修補管理

NemoClaw 與 OpenShell 都在快速迭代,漏洞會集中公告。2026-08-25,NVIDIA Product Security 發布 Security Bulletin 5872(Security Bulletin: NVIDIA NemoClaw and OpenShell - August 2026),一次公告 18 個 CVE。以下依官方 CSAF 原始資料(NVIDIA/product-security 儲存庫的 2026/5872)整理:

CVE元件弱點類型(CWE)CVSS 3.1受影響版本
CVE-2026-65093OpenShell沙盒逃逸(CWE-427)9.9 Critical0~0.0.33
CVE-2026-65083OpenShell沙盒建立 API 的禁止清單不完整(CWE-184)9.9 Critical0~0.0.33
CVE-2026-65091OpenShell惡意 Gateway 造成 OS 指令注入(CWE-78)8.8 High0~0.0.33
CVE-2026-65092OpenShell以路徑穿越繞過 L7 REST 網路政策(CWE-22)8.5 High0~0.0.33
CVE-2026-65086OpenShell沙盒 exec 處理器指令注入(CWE-78)6.8 Medium0~0.0.33
CVE-2026-65085OpenShell推理代理輸出編碼不當(CWE-116)5.2 Medium0~0.0.33
CVE-2026-65105NemoClaw推理服務未驗證即可存取(CWE-306,相鄰網路)8.1 High0~0.0.25
CVE-2026-65098NemoClaw遠端存取輔助流程的弱驗證(CWE-1390)8.1 High0~0.0.4
CVE-2026-65084NemoClaw部署流程憑證驗證不當(CWE-295)8.1 High0~0.0.1
CVE-2026-65081NemoClaw安裝流程執行不受信任的程式碼(CWE-494)8.1 High0~0.0.21
CVE-2026-65099NemoClawCLI 指令注入(CWE-78)7.8 High0~0.0.1
CVE-2026-65096NemoClawTelegram bridge 指令注入(CWE-78)7.8 High0~0.0.1
CVE-2026-65090NemoClawNIM 管理元件指令注入(CWE-78)7.8 High0~0.0.17
CVE-2026-65089NemoClawstatus/logs 外掛指令注入(CWE-78)7.8 High0~0.0.3
CVE-2026-65097NemoClaw安裝腳本下載程式碼未做完整性檢查(CWE-494)7.5 High0~0.0.21
CVE-2026-65082NemoClaw遷移指令程式碼注入(CWE-94)7.0 High0~0.0.17
CVE-2026-65087NemoClaw憑證保護不足(CWE-522)5.6 Medium0~0.0.1
CVE-2026-65088NemoClaw以可見的敏感資訊啟動程序(CWE-214)5.5 Medium0~0.0.17

本手冊基準 NemoClaw v0.0.139/OpenShell 0.0.116 都高於所有受影響範圍。這張表的價值在於提醒我們三件事:

從公告學到的對應的本手冊控制
兩個 CWE-494(安裝時執行或下載未驗證的程式碼)4.3「先下載、比對、審查,再固定版本執行」不是多餘的程序
CWE-22 可以繞過 L7 路徑規則不要只靠路徑規則保護敏感 API;Git 寫入 preset 之外,還要搭配 Token 權限(6.11、14.4)
CWE-306 推理服務未驗證(相鄰網路)本地推理服務只綁 loopback,主機防火牆擋掉同網段(3.4、14.6)

📌 註記:公告的「Updated Version」欄寫法不一致。例如 CVE-2026-65105 的受影響範圍是 0 to 0.0.25,修補欄卻寫 f06796ff3; 0.0.25。遇到這種模稜兩可的寫法,以保守方式解讀:版本必須高於受影響範圍的上限。

6.17.1 版本下限檢查腳本

check-security-floor.sh(🏢 本手冊自行撰寫;✅ 版本比較邏輯已用假的 nemoclaw/openshell 指令實測;🧪 實機的 --version 輸出格式以實際為準):

#!/usr/bin/env bash
# check-security-floor.sh — 🏢 確認主機上的 NemoClaw/OpenShell 高於已知安全公告的受影響範圍(唯讀)
# 基準:NVIDIA Security Bulletin 5872(2026-08-25)。有新公告時,只改下面兩個值並走 PR。
NEMOCLAW_MIN=0.0.26    # 公告中 NemoClaw 受影響範圍最高到 0.0.25 → 至少要 0.0.26
OPENSHELL_MIN=0.0.34   # 公告中 OpenShell 受影響範圍最高到 0.0.33,修補版 v0.0.34
ver_ge() { [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]; }   # $1 >= $2
extract() { grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1; }
rc=0
check() {  # 名稱 實際版本 最低版本
  if [ -z "$2" ]; then echo "UNKNOWN  $1:讀不到版本"; rc=1
  elif ver_ge "$2" "$3"; then echo "OK       $1 $2(>= $3)"
  else echo "VULN     $1 $2(< $3,依公告 5872 升級)"; rc=1; fi
}
check nemoclaw  "$(nemoclaw --version 2>/dev/null | extract)"  "$NEMOCLAW_MIN"
check openshell "$(openshell --version 2>/dev/null | extract)" "$OPENSHELL_MIN"
exit $rc

實測輸出(✅ 以假指令模擬三種主機):

--- 假設 nemoclaw=0.0.139 openshell=0.0.116
OK       nemoclaw 0.0.139(>= 0.0.26)
OK       openshell 0.0.116(>= 0.0.34)
exit=0
--- 假設 nemoclaw=0.0.25 openshell=0.0.33
VULN     nemoclaw 0.0.25(< 0.0.26,依公告 5872 升級)
VULN     openshell 0.0.33(< 0.0.34,依公告 5872 升級)
exit=1
--- 假設 nemoclaw=0.0.9 openshell=0.0.100
VULN     nemoclaw 0.0.9(< 0.0.26,依公告 5872 升級)
OK       openshell 0.0.100(>= 0.0.34)
exit=1

審查 AI 寫的版本比較程式時,最常見的錯誤:

❌ 壞例為什麼錯🔍 怎麼抓
[[ "$v" > "0.0.34" ]] 字串比較字串比較會判定 0.0.100 < 0.0.34、0.0.9 > 0.0.26用上面第三組測資(0.0.9、0.0.100)跑一次
讀不到版本時當成通過openshell 不在 PATH 時會靜默放行刪掉假的 openshell 再跑,必須出現 UNKNOWN 且結束碼 1
把下限寫成公告的「修補版」欄位修補欄寫法不一致(見上方註記)對照公告的「Affected Versions」欄重算

6.17.2 企業的弱點管理流程(🏢)

步驟做法驗證方式
1. 訂閱平台管理者訂閱 NVIDIA Product Security 公告,並 watch NVIDIA/product-security 儲存庫(提供機器可讀的 CSAF JSON)訂閱紀錄截圖存檔
2. 判定公告發布後 1 個工作天內,比對核准版本與受影響範圍判定結果寫入維護紀錄表(12.10)
3. 盤點對所有主機執行 check-security-floor.sh(更新下限後)結束碼 0 的主機數 ÷ 總主機數
4. 修補時限Critical:7 天;High:30 天;Medium:90 天(🏢 依企業弱點管理政策調整)逾期主機清單
5. 無法如期修補停用該主機上的沙盒(nemoclaw <名稱> stop),走 14.12 風險接受簽核單

6.18 對照 OWASP Top 10 for Agentic Applications 2026

OWASP GenAI Security Project 在 2025-12-09 發布 OWASP Top 10 for Agentic Applications for 2026(ASI01~ASI10),是目前最常被稽核引用的 Agent 風險清單。下表把每一項對到 NemoClaw 的控制與本手冊章節,並寫出沙盒管不到、要靠企業補強的部分:

編號風險NemoClaw/OpenShell 的控制管不到的部分(企業補強)🔍 怎麼驗證
ASI01Agent Goal Hijack網路預設拒絕,限制被劫持後能把資料送去哪裡(6.3)沙盒不判斷意圖;被文件裡的指令誘導改程式,仍可能發生(6.7)16.1 演練 0 的 Prompt Injection 題目
ASI02Tool Misuse & ExploitationDeep Agents 互動模式逐次核准;dcode -n 停用 shell(5.6)核准者沒看清楚就按下核准抽查核准紀錄;見下方「核准卡路徑」註記
ASI03Identity & Privilege Abuse憑證放在 Gateway,沙盒內只有 placeholder(6.6)Provider 是 Gateway 範圍,同一主機的沙盒共用(14.4);Git Token 權限要另外收斂13.5 的 placeholder 檢查;用 AI Token 推送 main 應被拒絕
ASI04Agentic Supply Chain Vulnerabilities映像檔以 digest 釘選;OpenShell 版本鎖定(12.1)安裝腳本與套件來源要自己審查(4.3、6.9)4.3 的 diff -q;6.17 公告中的 CWE-494 案例
ASI05Unexpected Code Execution (RCE)Landlock、seccomp、非 root、唯讀系統路徑(6.2、6.4)程式碼在 CI 執行時已離開沙盒4.10 控制有效性驗證;CI Runner 也要隔離
ASI06Memory & Context Poisoning無直接控制;rebuild 會完整保留 Agent 的原生 homeAGENTS.md、Agent 記憶檔被改了也會一路帶下去PR 審查必看 AGENTS.md 的 diff;敏感專案定期重建全新沙盒
ASI07Insecure Inter-Agent Communication一個沙盒只跑一種 Agent訊息通道(Telegram、Slack 等)是對外入口;6.17 表中的 CVE-2026-65096 就發生在 Telegram bridgenemoclaw <名稱> channels list 應為空(🏢 企業預設不開通道)
ASI08Cascading Failures無;同一主機的沙盒共用 Gateway 與 Provider(2.8)一個 Gateway 故障或一把 Key 外洩,會影響整台主機2.8 故障影響分析;不同敏感等級分主機(14.4)
ASI09Human-Agent Trust Exploitation無Agent 宣稱「完成」「測試通過」check-change-report.py(7.10)、check-test-weakening.py(13.8)
ASI10Rogue Agents出口拒絕與日誌(6.10);可隨時 stop/destroy偵測要靠企業日誌平台(14.7)14.7 偵測規則的觸發演練

📌 註記:v0.0.139 的 Deep Agents Code 編輯核准卡會把絕對路徑縮寫成檔名,例如對 /tmp/square.py 的編輯只顯示 square.py(main 的 #13591 已修正)。在 v0.0.139 上核准編輯前,先在卡片的 diff 內容或 dcode 的工具呼叫紀錄確認完整路徑,不要只看檔名。

✅ 建議:稽核要求「Agent 風險評估」時,直接用上表當底稿:每一列都填入貴單位的實測證據(截圖、指令輸出、PR 連結)。評估重點放在「管不到的部分」那一欄,那才是企業要負責補強的地方。

6.19 本章實務案例與注意事項

案例:Agent 回報「Maven 下載依賴時 403,請幫我在政策加上 repo.maven.apache.org」。

錯誤處理:直接在 openshell term 按 a 核准,或請 AI 產生 host: "*.apache.org" 的 preset。

正確處理:

  1. nemo-deepagents dev-order logs --tail 50 確認被拒的 host 與 binary(可能其實是 java 以外的程式,例如被誘導的 curl)。
  2. 企業規範是走內部 Nexus:確認專案的 settings.xml 指向 nexus.corp.example,而不是放行公開 Maven Central。
  3. 若真的需要新端點,走 13.4 白名單申請,以 6.11 格式撰寫、6.16 審查、6.12 驗證。

注意事項:

  • openshell term 的核准不寫入基準政策,destroy 後消失;rebuild 則會把目前的即時政策整份帶到新沙盒。
  • 政策 YAML 放進 Git(14.9),每次變更走 PR,CI 自動跑 lint。
  • 本章的 Git 路徑規則與 binary 路徑標 🧪,第一次導入時務必以 V1~V6 實測。

第7章 使用 NemoClaw 開發 Web Application

本章以一個虛構的企業專案「訂單服務 order-service」(Vue 3+TypeScript+Tailwind CSS 前端、Java 21+Spring Boot 後端、Hexagonal Architecture、PostgreSQL)為主線,建立一套可重複的 AI Agent 開發流程。重點不在「AI 能寫多少程式」,而在「怎麼讓 AI 在受控環境寫、寫完怎麼證明是對的」。

7.1 NemoClaw 在開發流程中的角色

工作誰負責NemoClaw 的角色
隔離 Agent 的執行環境NemoClaw+OpenShell✅ 主要價值
限制 Agent 能連的 Git、套件庫、模型NemoClaw preset+OpenShell✅ 主要價值
寫程式、改程式Agent(Deep Agents Code)提供執行環境
編輯器、除錯器IDE(VS Code、IntelliJ)❌ 不取代
版本控制、分支、PRGit+Git Server❌ 不取代
編譯、單元測試、整合測試Maven/Gradle/npm、JUnit、Playwright❌ 不取代
品質與安全掃描SonarQube、SAST、SCA、Trivy❌ 不取代
建置與部署CI/CD❌ 不取代
架構規範專案的架構文件與 ArchUnit 測試❌ 不取代
決定要不要合併人❌ 不取代

✅ 建議:把 NemoClaw 想成「讓 AI Coding Agent 上班的隔離辦公室」。辦公室有門禁(網路政策)、保險箱(憑證)、監視器(日誌);但它不負責驗收產品——驗收是 CI 與 Code Review 的事。

7.2 選擇 Agent 與程式碼進出沙盒的方式

Agent 選擇:三個受支援 Agent 中,LangChain Deep Agents Code(dcode) 是官方定位的「終端機 Coding Agent」,最適合本章。OpenClaw 與 Hermes 是常駐助理型,雖然也能操作檔案,但不是為程式開發設計。

程式碼怎麼進出沙盒:

方式方向適用評估
在沙盒內 git clone 工作副本(搭配 6.11 的 Git preset)雙向(push 需寫入 preset)開發✅ 建議:Agent 的修改只存在分支上,經 PR 才進主線
nemoclaw <名稱> upload/download單次複製規格文件、測試資料✅ 簡單、可稽核
--host-mount(唯讀)主機 → 沙盒參考文件、舊系統原始碼✅ 逆向工程首選(第 8 章);開發時無法寫回
share mount(SSHFS 雙向)雙向即時與 IDE 共同編輯⚠️ 主機目錄等於對 Agent 開放寫入;只掛單一工作副本,不可掛家目錄
flowchart LR
    DEV["開發者工作站<br/>IDE"] -->|"1. 撰寫規格<br/>docs/spec/*.md"| GIT["內部 Git<br/>demo/order-service"]
    GIT -->|"2. clone(讀 preset)"| SBX["沙盒 dev-order<br/>/sandbox/work/order-service"]
    SBX -->|"3. Agent 在 ai/ 分支修改"| SBX
    SBX -->|"4. push ai/ 分支(寫 preset,另經核准)"| GIT
    GIT -->|"5. 開 PR"| CI["CI/CD<br/>建置、測試、掃描"]
    CI -->|"6. 結果"| REV["人工 Code Review"]
    REV -->|"7. 合併或退回"| GIT
    DEV -.->|"8. 本機 checkout 分支驗證"| GIT

7.3 開發沙盒的工具鏈

官方受管映像檔的實際內容(📖 v0.0.139 原始碼):

項目Deep Agents Code 受管映像影響
基底node:24.22.1-trixie-slim(digest 釘選)有 Node.js 24 與 npm,可跑前端工具(需 npm preset 或內部代理庫)
Python/opt/venv(唯讀,dcode harness 用)不能在 /opt/venv 安裝套件
Git有可 clone
JDK/Maven/Gradle沒有沙盒內不能直接建置 Java
編譯器(gcc、make)被移除原生模組無法編譯

三種做法:

做法說明狀態
A. Agent 只改碼,建置測試在 CIAgent 推送 ai/ 分支,由 CI 跑 mvn verify、npm test,結果回饋給開發者再交給 Agent✅ 起步建議;最符合「工具負責客觀驗證」
B. 由操作者用 exec 在沙盒跑前端測試例如 nemo-deepagents dev-order exec --workdir /sandbox/work/order-service/web -- npm test🧪 需 npm 或內部 npm 代理 preset
C. 自訂映像檔加入 JDK 與 Mavennemoclaw onboard --from <Dockerfile>;官方允許以受管 Dockerfile 為基礎就地修改(需在 NemoClaw 原始碼樹執行 CLI)🧪 進階;需自行承擔映像檔安全與相容性

做法 C 的 Dockerfile 片段(🧪 未實測;只示意要補的東西,不是完整檔案):

# 以 v0.0.139 原始碼的 agents/langchain-deepagents-code/Dockerfile 為基礎,在最後一個 stage 加入:
ARG NEMOCLAW_TOOL_DISCLOSURE=progressive
ENV NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE}
# 企業 CA(官方要求自訂 Dockerfile 自行實作企業 CA 建置契約,見 3.6)
ARG NEMOCLAW_CORPORATE_CA_B64
USER root
RUN apt-get update \
 && apt-get install -y --no-install-recommends openjdk-21-jdk-headless maven \
 && rm -rf /var/lib/apt/lists/*
USER sandbox

⚠️ 警告:官方說明 --from 提供的 Dockerfile「定義完整映像檔」,NemoClaw 不會疊在受管 Runtime 之上;自訂映像檔也失去官方「三個 Agent 同一發佈批次」的驗證。rootless Podman 路徑不接受自訂 Dockerfile。採用做法 C 前,先在 14 章的試行環境完成映像檔掃描與 4.10 驗收。

📌 註記(審批邊界):Deep Agents 互動模式下,Agent 想執行 mvn test 這類 shell 指令會先請你核准;無頭 dcode -n 則停用 shell 執行。所以「讓 Agent 自己跑測試」只在互動模式、且你逐次核准時成立。這也是本手冊建議以 CI 作為測試真相來源的原因之一。

7.4 可重複的 AI Agent 開發流程

flowchart TD
    S0["0. 準備<br/>規格放進 docs/spec、AGENTS.md 就位"] --> S1["1. Agent 讀規格與既有程式<br/>提出計畫(不改檔)"]
    S1 --> G1{"人工核准計畫?"}
    G1 -- 修改 --> S1
    G1 -- 核准 --> S2["2. Agent 在 ai/ 分支小步實作"]
    S2 --> S3["3. Agent 補測試、執行允許的檢查"]
    S3 --> S4["4. Agent 輸出交付報告<br/>修改清單、測試結果、未完成事項"]
    S4 --> T1["5. 工具驗證<br/>check-change-report、check-layering"]
    T1 -- 不通過 --> S2
    T1 -- 通過 --> S5["6. push ai/ 分支、開 PR"]
    S5 --> T2["7. CI:建置、單元、整合、E2E、SAST、SCA、ArchUnit"]
    T2 -- 失敗 --> S2
    T2 -- 通過 --> R1{"8. 人工 Code Review"}
    R1 -- 退回 --> S2
    R1 -- 核准 --> M["9. 合併"]

每一步的輸入、輸出與品質門檻整理在第 10 章的 SSDLC 表。

7.5 專案慣例檔:讓 Agent 先讀規則

Deep Agents Code 會讀取 AGENTS.md(使用者層級在 /sandbox/.deepagents/agent/AGENTS.md;專案層級放在 repo 根目錄,依 Deep Agents Code 上游行為,🧪 以實際版本為準)。在 repo 根目錄放一份:

# AGENTS.md — order-service(給 AI Agent 的專案規則)

## 先讀
1. docs/spec/ 下的需求與規格;與程式衝突時,以規格為準並回報衝突。
2. docs/architecture.md 的分層規則。

## 架構(Hexagonal)
- com.example.order.domain:實體、值物件、Port 介面。不得 import Spring、JPA、Jackson。
- com.example.order.application:Use Case,只依賴 domain。
- com.example.order.adapter.web / adapter.persistence:Spring Controller、JPA Repository。
- 依賴方向只能 adapter → application → domain。

## 規則
- 修改前先提出計畫(檔案清單、理由、風險),等人類回覆「核准」再動手。
- 不新增第三方依賴;需要時在計畫中提出。
- 不修改 .env*、*-prod.yml、CI 設定、資料庫 migration 既有檔案(只能新增)。
- 每個商業規則都要有對應的單元測試。
- 不得刪除或停用(@Disabled、.skip)既有測試。

## 交付報告格式(必須照抄標題)
## 修改清單
| 檔案 | 動作 | 理由 |
## 測試結果
| 指令 | 結束碼 | 摘要 |
## 未完成與待確認

7.6 Prompt 範本與審查方法

以下每個範本都遵守同一個骨架:先讀 → 先計畫 → 等核准 → 小步修改 → 交付報告。每個範本後面附「如何審查 AI 產出」。

7.6.1 範本 P1:分析需求並建立 SRS

你是本專案的系統分析師。請在不修改任何程式碼的前提下完成:
1. 閱讀 docs/spec/requirements-raw.md 與既有程式(src/),整理成 SRS 草稿,存成 docs/spec/SRS.md。
2. SRS 章節:目的與範圍、角色、使用案例(UC-xx,每個含前置條件、主要流程、例外流程)、
   功能需求(FR-xx)、非功能需求(NFR-xx:效能、安全、稽核、可用性)、資料需求、待確認問題(Q-xx)。
3. 每條 FR 都要能追溯到原始需求的段落(寫出段落標題)。
4. 原始需求沒寫的內容,一律列入「待確認問題」,不得自行補齊。
完成後只輸出:新增的檔案路徑、FR/NFR/Q 的數量、你認為最模糊的三個需求。

如何審查:

檢查方法
是否偷改程式🔍 git status --porcelain 只應出現 docs/spec/SRS.md
是否憑空補需求🔍 隨機抽 5 條 FR,回原始需求找段落;找不到的就是幻覺
待確認問題是否太少需求越模糊,Q 應越多;Q 為 0 是警訊

❌ 壞例:「FR-12 系統應支援 OAuth2 單一登入」——原始需求只寫「使用者需登入」,SSO 是 AI 自行補的。

7.6.2 範本 P2:產生系統架構與設計規格

請依 docs/spec/SRS.md 與 docs/architecture.md(Hexagonal Architecture)產生 docs/design/SDD.md:
1. 元件圖(Mermaid):domain、application、adapter.web、adapter.persistence 的類別與依賴方向。
2. 每個 Use Case 的序列圖(Mermaid),標出經過的 Port。
3. 資料模型:實體、欄位、型別、約束;PostgreSQL DDL 草稿(不要建立 migration 檔)。
4. 每個設計決策附理由與替代方案(ADR 格式,最多 5 則)。
5. 列出與 SRS 不一致或 SRS 未定義而必須假設的地方。
不要修改 src/。完成後回報檔案路徑與假設清單。

如何審查:Mermaid 圖能否渲染(貼到 Mermaid Live Editor 或用 18.10 的檢查方式);依賴箭頭是否只從 adapter 指向 application/domain;每個假設是否都進了 Q 清單。

7.6.3 範本 P3:REST API 規格與 OpenAPI

請依 SDD.md 為「建立訂單」與「查詢訂單」撰寫 docs/api/openapi.yaml(OpenAPI 3.1):
- 路徑:POST /api/v1/orders、GET /api/v1/orders/{orderId}
- 請求與回應 schema 要有 required、format、minimum、maxLength。
- 錯誤回應統一用 application/problem+json(RFC 9457),列出 400、404、409、422。
- 金額欄位用字串表示的十進位數(避免浮點誤差),並說明理由。
- 不要產生程式碼。完成後執行你被允許的檢查,回報結果。

如何審查:🔍 用 CI 中的 OpenAPI linter(如 Redocly、Spectral)驗證;檢查是否把內部欄位(資料庫 ID、內部狀態碼)暴露到回應。

7.6.4 範本 P4:依規格開發後端

任務:實作「建立訂單」Use Case(UC-01)。
限制:
- 先讀 AGENTS.md、docs/spec/SRS.md 的 UC-01、docs/design/SDD.md、docs/api/openapi.yaml。
- 先輸出計畫:要新增/修改的檔案、每個檔案的職責、對應的 FR 編號、要新增的測試。等我回覆「核准」。
- 核准後在 ai/uc-01-place-order 分支實作,遵守 Hexagonal 分層:
  domain(Order、OrderRepository Port)→ application(PlaceOrderService)→ adapter(Controller、JPA)。
- 金額超過 50,000(不含)時狀態為 PENDING_REVIEW;金額必須 > 0。
- 不新增依賴;不修改既有 migration;不碰 .env* 與 *-prod.yml。
- 完成後依 AGENTS.md 的格式輸出交付報告。

如何審查:

檢查方法
分層是否正確✅ python3 check-layering.py src/main/java com.example.order(7.8),以及 CI 的 ArchUnit
報告是否誠實✅ python3 check-change-report.py .ai-reports/uc-01.md origin/main(7.10)
邊界值50,000 本身是否「不需覆核」?規格寫「超過」,測試要有 50000 與 50000.01 兩筆
是否偷加依賴🔍 git diff origin/main -- pom.xml package.json

7.6.5 範本 P5:依規格開發前端(Vue 3+TypeScript+Tailwind)

任務:在 web/ 實作「建立訂單」頁面。
- 先讀 docs/api/openapi.yaml 與 web/src 既有的元件、路由、API client 慣例。
- 技術:Vue 3 Composition API + <script setup lang="ts">、Tailwind CSS、既有的 API client。
- 表單欄位:客戶編號(必填,最多 20 字)、金額(必填,> 0,最多兩位小數)。
- 前端驗證只是使用者體驗;以後端回傳的 problem+json 為準顯示錯誤。
- 路由 /orders/new;成功後導到 /orders/{orderId}。
- 不新增 npm 套件;樣式只用 Tailwind 既有 class,不寫 inline style。
- 先列計畫等核准;完成後輸出交付報告(含 npm run lint、npm run test:unit 的結束碼)。

如何審查:是否用 v-html 顯示後端訊息(XSS 風險);是否把金額轉成 Number 做運算;是否把 API base URL 寫死。前端若採 Angular,相同骨架改成 Angular 的元件、Reactive Forms 與 HttpClient 慣例即可。

7.6.6 範本 P6:產生單元測試與整合測試

請為 PlaceOrderService 與 Order 補測試:
- 單元測試(JUnit 5):金額邊界(0、0.01、50000、50000.01)、null 金額、客戶編號空白。
- 整合測試:以 Testcontainers 啟動 PostgreSQL,驗證 JPA adapter 的 save/findById。
- E2E(Playwright):建立訂單成功與金額為 0 時的錯誤訊息。
- 測試名稱用「條件_預期結果」;不得使用 Thread.sleep;不得修改正式程式碼來讓測試通過,
  若發現正式程式碼的缺陷,回報而不是修改。
完成後輸出交付報告。

如何審查:🔍 git diff --stat origin/main -- src/main 應為空(只動測試);❌ 壞例:Agent 為了讓測試過,把 compareTo(...) > 0 改成 >= 0。

7.6.7 範本 P7:檢查 Clean Architecture 依賴方向

請只做分析、不修改:
1. 列出 src/main/java 下所有違反「adapter → application → domain」方向的 import,含檔案:行號。
2. 列出 domain 套件中所有 Spring、JPA、Jackson 相依。
3. 對每個違規提出最小修正方案(例如抽出 Port 介面),估計影響的檔案數。
輸出成 docs/review/architecture-findings.md。

如何審查:用 7.8 的兩個工具交叉比對——AI 列出的違規數應與工具相同;AI 多列的要求它附證據,少列的就是漏看。

7.6.8 範本 P8:產生安全檢查清單

請依 OWASP ASVS 4.0.3 Level 2 與本專案的 openapi.yaml,產生 docs/security/checklist-uc01.md:
- 只列與 UC-01 相關的條目(輸入驗證、授權、錯誤處理、日誌、敏感資料)。
- 每條寫:ASVS 編號、檢查方法(程式碼位置或測試名稱)、目前狀態(符合/不符合/無法判斷)。
- 「無法判斷」要說明缺少什麼資訊。不得修改程式碼。

如何審查:抽查「符合」的條目是否真的有對應程式或測試;ASVS 編號是否存在(OWASP ASVS)。

7.6.9 範本 P9:執行 Code Review 並修正缺陷

請 review 分支 ai/uc-01-place-order 相對於 origin/main 的變更:
1. 先只輸出問題清單:嚴重度(高/中/低)、檔案:行號、問題、建議修法。不要修改。
2. 我會勾選要修的項目;你只修勾選的項目,每項一個 commit,commit 訊息引用問題編號。
3. 修完後重新輸出交付報告。

如何審查:AI 自我 review 有盲點(會偏袒自己寫的程式)。人工 reviewer 仍必須看完整 diff;把 AI 的清單當成「起點」而不是「結論」。

7.7 範例專案結構與程式碼

order-service/
├── AGENTS.md
├── docs/{spec,design,api,security,review}/
├── pom.xml
├── src/main/java/com/example/order/
│   ├── domain/            Order.java、OrderRepository.java(Port)
│   ├── application/       PlaceOrderService.java
│   └── adapter/
│       ├── web/           OrderController.java
│       └── persistence/   InMemoryOrderRepository.java(正式版為 JPA)
├── src/main/resources/db/migration/V1__create_orders.sql
├── src/test/java/com/example/order/   OrderTest.java、ArchitectureTest.java
└── web/                   Vue 3 + TypeScript + Tailwind

核心領域與 Use Case(✅ 已在撰寫環境以 Java 21+Maven 3.9.9 編譯並通過測試;為了縮小依賴,範例中的 adapter 以純 Java 示意):

// src/main/java/com/example/order/domain/Order.java
package com.example.order.domain;

import java.math.BigDecimal;

public record Order(String id, String customerId, BigDecimal amount) {
    public static final BigDecimal REVIEW_THRESHOLD = new BigDecimal("50000");

    public Order {
        if (amount == null || amount.signum() <= 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
    }

    public boolean needsManagerReview() {
        return amount.compareTo(REVIEW_THRESHOLD) > 0;
    }
}
// src/main/java/com/example/order/domain/OrderRepository.java
package com.example.order.domain;

import java.util.Optional;

/** 輸出 Port:由 adapter.persistence 實作。 */
public interface OrderRepository {
    void save(Order order);

    Optional<Order> findById(String id);
}
// src/main/java/com/example/order/application/PlaceOrderService.java
package com.example.order.application;

import com.example.order.domain.Order;
import com.example.order.domain.OrderRepository;
import java.math.BigDecimal;
import java.util.UUID;

/** Use Case:只依賴 domain 的 Port,不知道資料存在哪裡。 */
public class PlaceOrderService {
    private final OrderRepository repository;

    public PlaceOrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public Order place(String customerId, BigDecimal amount) {
        Order order = new Order(UUID.randomUUID().toString(), customerId, amount);
        repository.save(order);
        return order;
    }
}

正式專案的 Spring Boot Web adapter(🧪 示意,未在撰寫環境編譯;需 Spring Boot 3.x 與 Jakarta Validation):

// src/main/java/com/example/order/adapter/web/OrderController.java
package com.example.order.adapter.web;

import com.example.order.application.PlaceOrderService;
import com.example.order.domain.Order;
import jakarta.validation.Valid;
import jakarta.validation.constraints.DecimalMin;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import java.math.BigDecimal;
import java.net.URI;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/orders")
class OrderController {
    private final PlaceOrderService service;

    OrderController(PlaceOrderService service) {
        this.service = service;
    }

    record CreateOrderRequest(@NotBlank @Size(max = 20) String customerId,
                              @DecimalMin(value = "0.01") BigDecimal amount) { }

    record OrderResponse(String orderId, String status) { }

    @PostMapping
    ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest req) {
        Order order = service.place(req.customerId(), req.amount());
        String status = order.needsManagerReview() ? "PENDING_REVIEW" : "CREATED";
        return ResponseEntity.created(URI.create("/api/v1/orders/" + order.id()))
                .body(new OrderResponse(order.id(), status));
    }
}

資料庫 migration(🧪 Flyway 慣例;PostgreSQL 語法):

-- src/main/resources/db/migration/V1__create_orders.sql
CREATE TABLE orders (
    id           VARCHAR(36)    PRIMARY KEY,
    customer_id  VARCHAR(20)    NOT NULL,
    amount       NUMERIC(15, 2) NOT NULL CHECK (amount > 0),
    status       VARCHAR(20)    NOT NULL,
    created_at   TIMESTAMPTZ    NOT NULL DEFAULT now()
);
CREATE INDEX idx_orders_customer ON orders (customer_id);

不同資料庫的差異(請 Agent 產生 DDL 時明確指定目標資料庫):

項目PostgreSQLOracleDB2SQL Server
十進位金額NUMERIC(15,2)NUMBER(15,2)DECIMAL(15,2)DECIMAL(15,2)
時區時間TIMESTAMPTZTIMESTAMP WITH TIME ZONETIMESTAMP(另存時區)DATETIMEOFFSET
字串VARCHAR(n)VARCHAR2(n CHAR)VARCHAR(n)NVARCHAR(n)(Unicode)
Testcontainers 模組postgresqloracle-freedb2(需接受授權)mssqlserver(需接受授權)

前端元件(🧪 示意,未在撰寫環境建置):

<!-- web/src/views/OrderCreate.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import { useRouter } from 'vue-router'
import { createOrder, type ProblemDetail } from '@/api/orders'

const customerId = ref('')
const amount = ref('')
const error = ref<string | null>(null)
const router = useRouter()

async function submit() {
  error.value = null
  if (!/^\d+(\.\d{1,2})?$/.test(amount.value) || amount.value === '0') {
    error.value = '金額必須大於 0,最多兩位小數'
    return
  }
  try {
    const res = await createOrder({ customerId: customerId.value, amount: amount.value })
    await router.push(`/orders/${res.orderId}`)
  } catch (e) {
    error.value = (e as ProblemDetail).detail ?? '建立失敗'
  }
}
</script>

<template>
  <form class="mx-auto max-w-md space-y-4 p-6" @submit.prevent="submit">
    <label class="block">
      <span class="text-sm font-medium">客戶編號</span>
      <input v-model.trim="customerId" maxlength="20" required class="mt-1 w-full rounded border px-3 py-2" />
    </label>
    <label class="block">
      <span class="text-sm font-medium">金額</span>
      <input v-model.trim="amount" inputmode="decimal" required class="mt-1 w-full rounded border px-3 py-2" />
    </label>
    <p v-if="error" class="text-sm text-red-600" role="alert">{{ error }}</p>
    <button type="submit" class="rounded bg-blue-600 px-4 py-2 text-white">建立訂單</button>
  </form>
</template>

📌 註記:錯誤訊息用 {{ error }} 文字插值(Vue 會跳脫),不用 v-html;金額保持字串傳給後端,由後端以 BigDecimal 解析。這兩點都是 7.6.5 審查時要確認的。

7.8 架構守門:ArchUnit 與快篩工具

ArchUnit 測試(✅ 已實測:正常時 mvn test 通過;在 domain.Order 注入一個參照 adapter.web.OrderController 的方法後,測試失敗並指出違規):

// src/test/java/com/example/order/ArchitectureTest.java
package com.example.order;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

@AnalyzeClasses(packages = "com.example.order", importOptions = ImportOption.DoNotIncludeTests.class)
class ArchitectureTest {

    @ArchTest
    static final ArchRule layers = layeredArchitecture()
            .consideringOnlyDependenciesInLayers()
            .layer("Domain").definedBy("..domain..")
            .layer("Application").definedBy("..application..")
            .layer("Adapter").definedBy("..adapter..")
            .whereLayer("Adapter").mayNotBeAccessedByAnyLayer()
            .whereLayer("Application").mayOnlyBeAccessedByLayers("Adapter")
            .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Adapter");

    @ArchTest
    static final ArchRule domainIsFrameworkFree = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("org.springframework..", "jakarta.persistence..", "com.fasterxml.jackson..");
}

pom.xml 的測試依賴(✅ 撰寫環境使用的版本):

<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>5.11.4</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>com.tngtech.archunit</groupId>
  <artifactId>archunit-junit5</artifactId>
  <version>1.3.0</version>
  <scope>test</scope>
</dependency>

違規時的實際輸出(✅ 節錄):

[ERROR] Tests run: 2, Failures: 1, Errors: 0, Skipped: 0 <<< FAILURE! -- in com.example.order.ArchitectureTest
Architecture Violation [Priority: MEDIUM] - Rule 'Layered architecture considering only dependencies in layers, ...
Method <com.example.order.domain.Order.debug(com.example.order.adapter.web.OrderController)> has parameter of type <com.example.order.adapter.web.OrderController> in (Order.java:0)

快篩工具 check-layering.py(✅ 已實測;完整原始碼見 18.10.3):不需要編譯,Agent 交付前就能跑,適合放在 pre-commit:

$ python3 check-layering.py src/main/java com.example.order
結果:0 項違規

$ python3 check-layering.py src/main/java com.example.order    # 注入違規後
L01 src/main/java/com/example/order/domain/Order.java:4: domain → com.example.order.adapter.web.OrderController
結果:1 項違規

📌 註記:check-layering.py 只看 import 敘述,抓不到完整類別名稱(FQCN)直接使用與反射;ArchUnit 分析位元組碼,才是正式守門。兩者並用:快篩給 Agent 即時回饋,ArchUnit 在 CI 擋合併。

7.9 測試策略

層級工具在哪跑範例狀態
單元JUnit 5沙盒(若有 JDK)或 CI✅ OrderTest
架構ArchUnitCI✅ ArchitectureTest
整合Testcontainers+PostgreSQLCI(沙盒內沒有 Docker)🧪
E2EPlaywrightCI🧪

單元測試(✅ 已實測通過):

// src/test/java/com/example/order/OrderTest.java
package com.example.order;

import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;

import com.example.order.domain.Order;
import java.math.BigDecimal;
import org.junit.jupiter.api.Test;

class OrderTest {
    @Test
    void amountAboveThresholdNeedsReview() {
        assertTrue(new Order("1", "c1", new BigDecimal("50000.01")).needsManagerReview());
        assertFalse(new Order("2", "c1", new BigDecimal("50000")).needsManagerReview());
    }

    @Test
    void nonPositiveAmountIsRejected() {
        assertThrows(IllegalArgumentException.class, () -> new Order("3", "c1", BigDecimal.ZERO));
    }
}

Testcontainers 整合測試(🧪 示意;需 Docker,因此在 CI 執行):

@Testcontainers
@SpringBootTest
class JpaOrderRepositoryIT {
    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired
    OrderRepository repository;

    @Test
    void savesAndFindsOrder() {
        var order = new Order("it-1", "c1", new BigDecimal("100.00"));
        repository.save(order);
        assertThat(repository.findById("it-1")).contains(order);
    }
}

Playwright E2E(🧪 示意):

// web/e2e/order-create.spec.ts
import { test, expect } from '@playwright/test'

test('金額為 0 時顯示錯誤', async ({ page }) => {
  await page.goto('/orders/new')
  await page.getByLabel('客戶編號').fill('C001')
  await page.getByLabel('金額').fill('0')
  await page.getByRole('button', { name: '建立訂單' }).click()
  await expect(page.getByRole('alert')).toContainText('金額必須大於 0')
})

7.10 交付報告與誠實性檢查

Agent 的交付報告必須照 AGENTS.md 的格式。check-change-report.py(✅ 已實測;完整原始碼見 18.10.2)把報告與 git diff 比對:

結果意義
UNREPORTED實際有改、報告沒寫——最危險,代表有變更沒人審
PHANTOM報告說改了、實際沒改——報告不可信
FORBIDDEN碰到 .env*、*.pem、*.key、*application-prod*
NOEVIDENCE測試結果沒有結束碼
TESTFAIL有測試結束碼非 0,Agent 卻宣稱完成

好例報告(✅ 實際輸出):

$ python3 check-change-report.py .ai-reports/good.md base
報告列出 2 檔、實際變更 2 檔、測試 1 筆、問題 0 項

❌ 壞例報告:少報一個新檔、多報一個沒改的檔、偷改 .env.local、測試失敗卻說完成:

$ python3 check-change-report.py .ai-reports/bad.md base
UNREPORTED .env.local: 實際有變更,報告未列出
UNREPORTED src/main/java/demo/C.java: 實際有變更,報告未列出
PHANTOM    src/main/java/demo/B.java: 報告列出,但 Git 沒有這個變更
FORBIDDEN  .env.local: 變更碰到禁止路徑
TESTFAIL   `mvn -q test`: 結束碼 1
NOEVIDENCE `npm run e2e`: 結束碼 '通過' 不是數字
報告列出 2 檔、實際變更 3 檔、測試 2 筆、問題 6 項

⚠️ 警告:報告中的「結束碼 0」仍是 Agent 自己寫的。check-change-report.py 只證明「報告與 Git 一致」;測試是否真的通過,以 CI 的結果為準。

7.11 程式碼品質、弱點掃描與依賴檢查

這些工具在沙盒外的 CI 執行(第 10 章有完整 pipeline)。🏢 建議的最低組合:

類別後端前端門檻
靜態分析/品質SonarQube 或 SpotBugs+PMDESLint+vue-tsc --noEmit新增程式碼無 Blocker/Critical
SASTSemgrep 或 CodeQL同左高風險 0
SCA(依賴弱點)OWASP Dependency-Check 或 Trivynpm audit --omit=dev 或 Trivy無已知 Critical;High 需例外單
授權CycloneDX SBOM+授權政策同左無禁用授權
機密掃描gitleaks同左0

7.12 建置、部署與交付文件

交付物產生者驗收者
SRS、SDD、OpenAPIAgent 草擬、SA/架構師修訂需求方、架構師
程式碼與測試Agent 實作、開發者修訂Code Reviewer
交付報告(每個 PR)Agentcheck-change-report.py+Reviewer
CI 報告(測試、覆蓋率、掃描)CIQA、資安
SBOMCI資安
部署說明、回復步驟開發者(可請 Agent 草擬)維運

7.13 本章實務案例與注意事項

案例:Agent 交付 UC-01,報告寫「測試全部通過」,CI 卻失敗在 ArchitectureTest。

追查:

  1. check-change-report.py 顯示 UNREPORTED src/main/java/com/example/order/domain/OrderMapper.java——Agent 為了方便,在 domain 放了一個依賴 JPA Entity 的 mapper,卻沒寫進報告。
  2. Agent 在沙盒內沒有 JDK(7.3),報告中的「mvn -q test 結束碼 0」是它「預期」的結果,不是實際執行的結果。
  3. 處置:退回 PR;在 AGENTS.md 加一條「沒有實際執行的指令不得寫進測試結果表,改寫在『未完成與待確認』」;在 pre-commit 加入 check-layering.py。

注意事項:

  • 所有 Prompt 都要求「先計畫、等核准」,但模型不一定遵守。真正的控制是:寫入 preset 預設不套用、只能推 ai/ 分支、主線受分支保護。
  • 不要讓 Agent 同時擁有「改程式」與「改 CI 設定」的能力;CI 檔案列入 AGENTS.md 的禁止清單,並由 CODEOWNERS 保護。
  • 範例中的 Spring、Testcontainers、Playwright 程式碼標 🧪,導入時以專案實際版本為準。

第8章 既有系統逆向工程

案例:一套沒有完整文件的企業舊系統「legacy-billing」(Java 8+Struts/Spring 混用、JSP 前端、Oracle Stored Procedure、夜間批次、MQ 介接)。目標是在 NemoClaw 管控下,讓 Agent 協助盤點、追蹤、重建規格,並產出可驗證的文件與回歸測試。逆向工程是 NemoClaw 最能發揮的情境:原始碼可以唯讀掛入,Agent 改不到原始檔。

8.1 原則

原則做法
先盤點、再分析、最後才談修改本章所有 Prompt 都禁止修改原始碼
事實與推測分開文件中每條結論標 [事實] 或 [推測];事實必附「來源:路徑:行號」
證據可驗證用 check-evidence.py(8.6)機械檢查引用存在、行號在範圍內
不連正式環境沙盒網路只開推理服務;不給資料庫連線
資訊不足就問每份文件都有「待確認問題 Q-xx」
不憑空補邏輯找不到的程式邏輯寫「未找到」,不寫「應該是」

8.2 環境準備:唯讀掛入原始碼、只開推理

# 🖥️ Host:1. 準備一份「去敏」後的原始碼副本(見 8.9),不要直接掛正式 repo
cp -a /srv/src/legacy-billing /srv/re/legacy-billing-snapshot-20261027
gitleaks detect --no-git --source /srv/re/legacy-billing-snapshot-20261027 --report-path /srv/re/gitleaks.json

# 2. 建立逆向工程沙盒:原始碼唯讀掛入、Restricted 層
export NEMOCLAW_DISABLE_TELEMETRY=1
NEMOCLAW_POLICY_TIER=restricted nemo-deepagents onboard --name re-legacy \
  --host-mount /srv/re/legacy-billing-snapshot-20261027:/sandbox/src

# 3. 移除 Deep Agents 預設的 GitHub 與 PyPI 出口(逆向工程不需要)
nemo-deepagents re-legacy policy exclude github --dry-run
nemo-deepagents re-legacy policy exclude github --force
nemo-deepagents re-legacy policy exclude pypi --force
nemo-deepagents re-legacy policy list
# 🖥️ Host:4. 驗證唯讀與輸出目錄
nemo-deepagents re-legacy exec -- bash -lc 'touch /sandbox/src/x 2>&1 || echo RO-OK'
nemo-deepagents re-legacy exec -- bash -lc 'awk "\$2==\"/sandbox/src\"{print \$2,\$4}" /proc/mounts'
nemo-deepagents re-legacy exec -- bash -lc 'mkdir -p /sandbox/re-out && echo OUT-OK'
項目內容
執行位置🖥️ Host
前提Linux 或 WSL 2 上的 Docker(--host-mount 不支援 macOS 與 Podman)
預期結果RO-OK;/proc/mounts 中 /sandbox/src 的選項含 ro;OUT-OK
失敗排查onboarding 拒絕 --host-mount → 檢查平台與 Gateway 是否為 NemoClaw 管理的 Docker driver
是否修改系統建立沙盒與政策變更;原始碼副本不會被修改

📌 註記:--host-mount 掛入的是「主機目錄的即時唯讀視圖」,主機端之後修改副本,沙盒內會看到。所以要掛的是「凍結的快照副本」,並在文件中記錄快照日期與來源 commit。

8.3 逆向工程流程

flowchart TD
    A["1. 盤點<br/>目錄、模組、語言、建置檔"] --> B["2. 呼叫關係<br/>JSP、Action、Controller、Service"]
    B --> C["3. 資料追蹤<br/>API、資料表、Stored Procedure"]
    C --> D["4. 商業規則<br/>條件、例外、錯誤碼"]
    D --> E["5. 批次與介接<br/>排程、MQ、檔案交換、外部系統"]
    E --> F["6. 架構圖與資料流圖<br/>Mermaid"]
    F --> G["7. 文件<br/>SRS、SDD、API、資料字典"]
    G --> H["8. 行為比對<br/>文件 vs 實際執行"]
    H --> I["9. 回歸測試與差異報告"]
    A -.->|"每步都產出待確認問題 Q-xx"| Q["待確認問題清單<br/>交給系統負責人"]
    D -.-> Q
    E -.-> Q

8.4 步驟總表

步驟AI 的工作輸出人工檢查
1. 盤點列出目錄、模組、檔案數、語言、框架版本、建置檔、設定檔inventory.md、modules.csv數字與 find/wc 結果相符
2. 呼叫關係從 URL/JSP 追到 Action/Controller、Service、DAOcall-graph.md(Mermaid)抽 3 條路徑人工追
3. 資料追蹤列出每支 DAO 用到的資料表、SQL、SP 與參數data-access.mdSP 名稱與 DB 物件清單比對
4. 商業規則抽出條件判斷、例外處理、錯誤碼business-rules.md(標 [事實]/[推測])check-evidence.py+業務人員確認
5. 批次與介接排程設定、批次程式、MQ queue、檔案格式、外部 URLintegration.md與維運排程表比對
6. 圖系統架構圖、資料流圖architecture.md圖中每個節點都能在 1~5 找到出處
7. 文件SRS、SDD、API 規格、資料字典SRS.md、SDD.md、api.md、data-dictionary.md架構師與系統負責人審
8. 行為比對依文件設計測試案例,在測試環境執行並比對behavior-diff.mdQA
9. 回歸測試產生 characterization tests 與差異報告src/test/...、regression-report.mdCode Review

8.5 Prompt 範本

8.5.1 共用前言(每個逆向 Prompt 的開頭都貼上)

【逆向工程共同規則】
- 原始碼在 /sandbox/src(唯讀)。所有輸出寫到 /sandbox/re-out/。
- 禁止修改、移動、刪除 /sandbox/src 下任何檔案;禁止嘗試連線任何資料庫或外部系統。
- 每條結論標示:
  [事實]:原始碼可直接證實,必須附(來源:相對於 /sandbox/src 的路徑:起始行-結束行)。
  [推測]:根據命名、註解或慣例推論,必須附(依據:…;待確認 Q-xx)。
- 找不到就寫「未找到」,並列出你搜尋過的路徑與關鍵字;不得補寫不存在的邏輯。
- 檔案可能是 MS950(Big5)編碼;讀到亂碼時回報檔名,不要猜內容。
- 遇到看起來像密碼、金鑰、身分證號、帳號的字串,以 *** 遮蔽,並在報告中列出位置。
- 最後輸出:產出檔案清單、[事實]/[推測] 數量、待確認問題清單。

8.5.2 範本 R1:盤點程式碼、目錄與模組

(貼上共用前言)
任務:盤點 /sandbox/src。
1. 目錄樹(深度 3)與每個頂層目錄的用途推測。
2. 依副檔名統計檔案數與行數(java、jsp、xml、properties、sql、sh、js)。
3. 建置工具與版本(pom.xml、build.gradle、build.xml),列出主要框架與版本。
4. 設定檔清單(*.properties、*.xml、*.yml),標出疑似含連線資訊的檔案(只列路徑,內容遮蔽)。
5. 模組清單 modules.csv:模組名稱、路徑、主要套件、檔案數、對外介面(URL/Queue/檔案)。
輸出 /sandbox/re-out/inventory.md、/sandbox/re-out/modules.csv。

如何審查:

# 🖥️ Host:用指令重算,比對 Agent 報的數字
nemo-deepagents re-legacy exec -- bash -lc 'cd /sandbox/src && find . -name "*.java" | wc -l && find . -name "*.jsp" | wc -l'
nemo-deepagents re-legacy download /sandbox/re-out/ ./re-out/

數字對不上時,要求 Agent 列出它統計的檔案清單——差異通常是它只掃了部分目錄(上下文不足)。

8.5.3 範本 R2:前後端呼叫關係

(貼上共用前言)
任務:建立「請款單查詢」功能的呼叫鏈。
起點:web.xml、struts-config.xml、@RequestMapping 中與 invoice 相關的 URL。
對每條 URL 追到:JSP → Action/Controller 方法 → Service 方法 → DAO 方法 → SQL 或 SP。
輸出 call-graph.md:
- 一張 Mermaid flowchart。
- 一張表:URL|Action/Controller(路徑:行)|Service(路徑:行)|DAO(路徑:行)|資料表/SP。
追不到的環節寫「未找到」並列出搜尋過的關鍵字。

如何審查:隨機抽 3 條鏈,自己用 grep -n 追一次。❌ 壞例:表格中 Service 欄寫 InvoiceService.query(),但該類別實際沒有 query 方法——這就是幻覺,check-evidence.py 的 BADLINE 或人工追查會抓到。

8.5.4 範本 R3:追蹤 API、資料表與 Stored Procedure

(貼上共用前言)
任務:列出所有資料存取。
1. 每個 DAO/Mapper:方法、SQL(原文)、讀寫的資料表、使用的 SP 與參數方向(IN/OUT)。
2. 動態 SQL(字串串接)另列一節,標出可能的 SQL Injection 位置([事實]+行號)。
3. 若 /sandbox/src 內有 *.sql 或 SP 原始碼,列出 SP 內部再呼叫的 SP 與資料表。
4. 產生 data-access.md 與 tables.csv(資料表、被哪些模組讀、被哪些模組寫)。

如何審查:資料表清單交給 DBA 與實際 schema 比對;SQL Injection 位置交給資安複核。

8.5.5 範本 R4:重建商業規則與例外處理

(貼上共用前言)
任務:重建「請款金額計算」的商業規則。
1. 找出所有與金額、稅率、折扣、四捨五入相關的程式碼。
2. 每條規則一行:[事實] 規則描述(來源:路徑:行-行)。
3. 例外處理:每個 catch、錯誤碼、錯誤訊息,對應到使用者看得到的結果。
4. 命名或註解暗示、但程式沒有實作的規則,標 [推測] 並開 Q-xx。
5. 不同模組實作不一致的規則,另列「規則衝突」一節。
輸出 business-rules.md。

如何審查:先跑 8.6 的 check-evidence.py;通過後,請業務人員逐條確認 [事實] 的描述是否等於程式行為(工具只證明「行號存在」,不證明「描述正確」)。

8.5.6 範本 R5:批次作業、排程、訊息佇列與外部介接

(貼上共用前言)
任務:盤點非同步與外部介接。
1. 排程:crontab、Quartz、Spring @Scheduled、shell script;列出排程時間、程式入口、輸入輸出檔案。
2. 訊息佇列:MQ queue/topic 名稱、發送端、接收端、訊息格式(欄位)。
3. 檔案交換:檔名規則、編碼、固定長度欄位定義。
4. 外部系統:URL、主機名、介面規格;URL 中的主機名照列,帳密遮蔽。
5. 每項標出重跑(rerun)與失敗處理邏輯。
輸出 integration.md。

8.5.7 範本 R6:重建系統架構圖與資料流圖

(貼上共用前言)
任務:依 inventory.md、call-graph.md、data-access.md、integration.md 繪製:
1. 系統架構圖(Mermaid flowchart):模組、資料庫、MQ、外部系統。
2. 「請款」端到端資料流圖:資料從畫面輸入、經過哪些模組與資料表、到產出檔案。
圖中每個節點都要在註解中標註出處(引用前述文件的章節)。不得出現前述文件沒有的節點。

8.5.8 範本 R7:產生 SRS、SDD、API 規格與資料字典

(貼上共用前言)
任務:把前述分析整理成正式文件草稿:
- SRS.md:功能需求依 call-graph 的功能分組;每條 FR 標 [事實](附來源)或 [推測](附 Q)。
- SDD.md:模組設計、類別職責、例外處理策略。
- api.md:對外 URL 與參數(從 web.xml、Action、Controller 整理)。
- data-dictionary.md:資料表、欄位、型別、用途(用途若是推測必須標 [推測])。
文件開頭註明:原始碼快照日期 2026-10-27、來源 commit(由我提供)、本文件為 AI 草稿需人工審查。

8.5.9 範本 R8 與 R9:行為比對、回歸測試與差異報告

(貼上共用前言)
任務 R8:依 business-rules.md 為每條 [事實] 規則設計測試案例:輸入、預期輸出、依據規則編號。
輸出 behavior-cases.csv。不要執行,不要連線任何環境。

任務 R9:以 behavior-cases.csv 產生 characterization tests(JUnit 5)草稿:
- 測試只描述「目前的行為」,即使看起來像 bug 也照現況斷言,並在測試名稱加 _currentBehavior。
- 產出到 /sandbox/re-out/tests/,不要放進 /sandbox/src。
- 另外輸出 regression-report.md 範本:案例編號|舊系統結果|新系統結果|差異|判定(預期/缺陷/待確認)。

如何審查:測試要由人在測試環境對舊系統實際執行,把結果填回 behavior-cases.csv 的「實際輸出」欄;只有實際跑過的案例,才能作為重構或改版的基準。

8.6 事實與推測的機械檢查

check-evidence.py(✅ 已實測;完整原始碼見 18.10.4)檢查五件事:

結果意義
MISSING[事實] 沒有來源
BADFILE來源檔案不存在
BADLINE行號超出檔案長度或起訖顛倒
NOBASIS[推測] 沒有「依據:」或沒有 Q-xx
UNTAGGED條列含「必須/一律/會自動/禁止/只能」等結論字眼卻沒標示

好例(✅ 實際輸出):

- [事實] 訂單金額超過 50,000 時需主管覆核(不含 50,000)。(來源:src/main/java/com/example/order/domain/Order.java:6-6)(來源:src/main/java/com/example/order/domain/Order.java:15-17)
- [事實] 金額必須大於 0,否則拋出 IllegalArgumentException。(來源:src/main/java/com/example/order/domain/Order.java:8-12)
- [推測] 覆核門檻可能依客戶等級不同。(依據:Order.java 只有單一常數 REVIEW_THRESHOLD;待確認 Q-01)
$ python3 check-evidence.py docs/business-rules.md .
結果:事實 2 條、推測 1 條、問題 0 項

❌ 壞例(只用於審查訓練):

- [事實] 訂單一律於建立後 30 天自動結案。
- [事實] 覆核門檻定義於設定檔。(來源:src/main/resources/application.yml:12)
- [事實] 金額檢查位於 Order 建構子。(來源:src/main/java/com/example/order/domain/Order.java:80-95)
- [推測] VIP 客戶免覆核。
- 系統會自動通知主管。
$ python3 check-evidence.py docs/bad-rules.md .
MISSING  docs/bad-rules.md:3: [事實] 沒有來源
BADFILE  docs/bad-rules.md:4: src/main/resources/application.yml 不存在
BADLINE  docs/bad-rules.md:5: src/main/java/com/example/order/domain/Order.java:80-95 超出 1–17
NOBASIS  docs/bad-rules.md:6: [推測] 需要「依據:」與待確認編號 Q-xx
UNTAGGED docs/bad-rules.md:7: 疑似結論但未標示 [事實]/[推測]
結果:事實 3 條、推測 1 條、問題 5 項

⚠️ 警告:工具通過只代表「引用的位置存在」。最常見的高級錯誤是「行號正確、描述錯誤」(例如程式寫 > 0,文件寫「大於等於 0」)。抽查比例 🏢 建議:[事實] 至少 20%,涉及金額、權限、法規的規則 100%。

8.7 大型程式碼庫與上下文窗口限制

問題症狀做法
一次讀不完Agent 只分析前幾個目錄就下結論先跑 R1 產生 modules.csv,再逐模組下 Prompt
跨模組追蹤斷線呼叫鏈在模組邊界「未找到」每個模組產出「對外介面摘要」,跨模組時只給摘要+目標模組原始碼
上下文壓縮遺失細節長對話後忘記早先的規則每次新任務重貼共用前言;結果寫進檔案,不靠對話記憶
重複分析浪費 token每次都重新讀全部以 inventory.md、call-graph.md 作為索引,下一步只讀需要的檔案

逐模組批次分析(🖥️ Host;🧪 依 dcode -n 的 JSON 介面撰寫,未實機執行):

#!/usr/bin/env bash
# re-batch.sh — 🏢 逐模組執行無頭分析;dcode -n 停用 shell、只能讀檔與寫檔
set -euo pipefail
PREAMBLE=$(cat re-preamble.txt)               # 8.5.1 共用前言
while IFS=, read -r module path _; do
  [[ "$module" == "module" ]] && continue      # 跳過 CSV 標題
  prompt="${PREAMBLE}
任務:只分析 /sandbox/src/${path},產出 /sandbox/re-out/modules/${module}.md(對外介面摘要+商業規則)。"
  nemo-deepagents re-legacy agent -n "$prompt" --json > "out-${module}.json" || true
  jq -r '.data.status + " " + (.data.exit_code|tostring)' "out-${module}.json"
done < modules.csv

8.8 編碼格式與中文註解

台灣企業的舊系統常見 MS950(Big5)或混用 UTF-8:

# 🖥️ Host:在主機端(不是沙盒)偵測編碼,轉出 UTF-8 副本再掛入
cd /srv/re/legacy-billing-snapshot-20261027
find . -name "*.java" -exec file -i {} + | grep -v 'charset=utf-8\|charset=us-ascii' | head
# 轉碼到新目錄,保留原始副本不動(🧪 確認無亂碼後再掛入)
mkdir -p ../legacy-billing-utf8
find . -type f \( -name "*.java" -o -name "*.jsp" -o -name "*.properties" \) | while read -r f; do
  mkdir -p "../legacy-billing-utf8/$(dirname "$f")"
  iconv -f CP950 -t UTF-8 "$f" > "../legacy-billing-utf8/$f" 2>/dev/null || cp "$f" "../legacy-billing-utf8/$f"
done
注意說明
.properties 的 \uXXXXJava 舊版 properties 以 Unicode escape 存中文,請 Agent 解碼後再引用
轉碼後行號iconv 不改變行數,行號引用仍有效
中文註解與程式不一致舊系統常見「註解寫 A、程式做 B」——以程式為 [事實],註解內容只能作為 [推測] 的依據

8.9 敏感資料處理

風險掛入前的處理(🖥️ Host)
設定檔中的資料庫帳密gitleaks detect --no-git 掃描;以 sed 在副本中遮蔽後再掛入
SQL dump、測試資料含真實客戶資料⛔ 不放進副本;改用合成資料
日誌檔⛔ 不放進副本
正式環境主機名、IP可保留(逆向需要),但推理服務若在外部,屬資料外送,需依 13.6 分級
個資欄位定義(身分證、帳號)欄位名稱可保留;樣本值一律移除

⚠️ 警告:原始碼本身就可能是機密資料。把整個舊系統送進外部推理服務前,必須依 13.6 取得資料擁有者核准;高機密系統應改用企業私有模型(14.5)。

8.10 回歸測試與差異報告

測試類型目的產生方式執行位置
Characterization test鎖住「目前行為」,作為重構基準R9 草稿+人工修訂CI/測試環境
Golden master批次輸出檔逐位元比對在測試環境跑舊批次,保存輸出測試環境
契約測試外部介接格式不變依 integration.md 撰寫CI

差異報告範本:

案例規則舊系統結果新系統/文件預期差異判定負責人
BC-001BR-031,050.001,050.00無一致—
BC-002BR-07999.99(無條件捨去)1,000.00(四捨五入)0.01待確認 Q-12業務窗口

8.11 本章實務案例與注意事項

案例:Agent 產出的 business-rules.md 寫「[事實] 逾期 90 天自動轉呆帳(來源:BatchJob.java:120-135)」,check-evidence.py 通過,但業務人員說實際是 180 天。

追查:BatchJob.java:120-135 確實有 90,但那是「提醒」的天數;轉呆帳的 180 在另一個 SP 裡(沙盒內只有 Java 原始碼,沒有 SP 原始碼)。Agent 把兩件事混在一起。

改善:

  1. 共用前言加一條:「同一數值出現多次時,列出所有出現位置,不得只取第一個」。
  2. 向 DBA 申請 SP 原始碼(去敏後)一併掛入。
  3. 金額、天數、比率類規則改為 100% 人工確認。

注意事項:

  • 掛入的是凍結快照;文件要記錄快照日期與來源 commit,避免之後原始碼變動造成文件失效。
  • dcode -n 會自動核准檔案寫入;輸出目錄 /sandbox/re-out 與唯讀的 /sandbox/src 分開,是讓「自動核准」也安全的前提。
  • 逆向產出的所有文件都是草稿,必須經系統負責人簽核才能成為正式規格。

第9章 Framework 與執行環境升級

案例:把「order-service」從 Java 11+Spring Boot 2.7+Vue 2+Node 16 升級到 Java 21+Spring Boot 3.x+Vue 3+Node 22。升級是 AI Agent 很能幫忙、也很容易闖禍的工作:機械式修改量大(javax → jakarta、Options API → Composition API),但 Breaking Change 的影響要靠測試與人判斷。本章的鐵則:未經測試與人工審查的批次自動升級結果,不得視為可上線成果。

9.1 升級範圍與官方指南

對象典型升級主要 Breaking Change官方指南
Java8/11 → 17/21移除的 API、強封裝(--add-opens)、SecurityManager 淘汰Oracle JDK 21 Migration Guide
Spring Boot2.7 → 3.xJava 17 基線、javax.* → jakarta.*、Spring Security 6 設定方式、屬性改名Spring Boot 3.0 Migration Guide
Spring Framework5.3 → 6.x同上;部分 API 移除Spring Framework Versions
Vue2 → 3全域 API、v-model、過濾器移除、事件匯流排Vue 3 Migration Guide
Angular逐大版升級每版不同Angular Update Guide
TypeScript4.x → 5.x型別檢查變嚴TypeScript Release Notes
Node.js16 → 22 LTSOpenSSL 3、原生模組重編Node.js Releases
Maven/Gradle外掛版本、Gradle 8 → 9外掛相容性Maven Release History、Gradle Upgrading
資料庫驅動ojdbc8 → ojdbc11、mssql-jdbc 12預設加密(SQL Server encrypt=true)、時區處理各廠商 Release Notes
Docker 基底映像openjdk:11 → eclipse-temurin:21-jre基底 OS 改變、使用者權限映像檔供應商說明

✅ 建議:機械式重構可以先用確定性工具(例如 OpenRewrite 的 Spring Boot 3 recipe),再讓 Agent 處理工具處理不了的部分。確定性工具的輸出可重現、可審查,比讓 LLM 逐檔改穩定。

9.2 標準升級流程

flowchart TD
    U1["1. 盤點目前版本與依賴<br/>mvn dependency:tree、npm ls"] --> U2["2. 確認官方支援矩陣<br/>Java × Spring Boot × DB 驅動 × 中介軟體"]
    U2 --> U3["3. 研究 Breaking Changes<br/>Migration Guide 逐條對照"]
    U3 --> U4["4. 升級計畫與風險清單<br/>分批、順序、回復點"]
    U4 --> G1{"人工核准計畫?"}
    G1 -- 否 --> U3
    G1 -- 是 --> U5["5. 建立回復基線<br/>tag、分支、建置產物、DB 備份"]
    U5 --> U6["6. 逐步修改<br/>每批一個 PR"]
    U6 --> U7["7. 編譯、單元、整合、E2E"]
    U7 -- 失敗 --> U6
    U7 --> U8["8. 效能、安全、執行環境檢查"]
    U8 --> U9["9. 升級前後行為比對"]
    U9 --> U10["10. 升級報告、回復方案、驗收清單"]
步驟Agent 可協助必須由工具或人完成
1. 盤點整理依賴樹、找出已停止維護的套件在 CI 實際執行 mvn dependency:tree、npm ls --all
2. 支援矩陣彙整官方文件人確認企業中介軟體(WebLogic、WebSphere、AP Server)的支援聲明
3. Breaking Changes逐條對照 Migration Guide 與程式碼使用點—
4. 計畫草擬分批計畫與風險清單架構師核准
5. 基線產生指令清單人執行 tag 與備份
6. 修改小步修改Code Review
7. 測試補測試CI 執行
8. 非功能草擬檢查項目效能測試、弱點掃描工具
9. 行為比對設計比對案例測試環境實際執行
10. 報告草擬人簽核

9.3 各技術的升級要點

Java 11 → 21:

  • 先升 Java 17 再升 21,分兩個 PR,讓問題容易定位。
  • 搜尋 --illegal-access、sun.misc.Unsafe、反射存取 JDK 內部類別的程式。
  • maven-compiler-plugin 改用 <release>21</release>;確認 Lombok、MapStruct、Mockito 等需要配合 JDK 版本的工具已升級。

Spring Boot 2.7 → 3.x:

  • 先在 2.7 上清掉所有 deprecation 警告(官方 Migration Guide 的建議)。
  • javax.persistence、javax.validation、javax.servlet → jakarta.*;第三方函式庫也必須有 Jakarta 版本。
  • Spring Security:WebSecurityConfigurerAdapter 已移除,改用 SecurityFilterChain bean。
  • 屬性改名:使用 spring-boot-properties-migrator 在啟動時列出。

Vue 2 → 3:

  • 先升到 Vue 2.7(內建 Composition API),再用 @vue/compat 過渡到 Vue 3。
  • 搜尋 Vue.filter、$on/$off、.sync、v-model 的自訂元件用法。
  • UI 元件庫(Element UI → Element Plus 等)通常是最大的工作量,要先確認目標版本。

資料庫驅動與中介軟體:

  • SQL Server JDBC 10 起預設 encrypt=true,舊環境沒有正式憑證會連不上——這是設定變更,不是程式錯誤。
  • Oracle 驅動升級後確認 TIMESTAMP WITH TIME ZONE 與 DATE 的對應行為。
  • 企業 AP Server 是否支援 Jakarta EE 10,是能否升 Spring Boot 3 的前提。

9.4 Prompt 範本

9.4.1 範本 U1:差異分析(只讀不改)

任務:分析 order-service 從 Spring Boot 2.7.18 升級到 3.3.x 的影響。不要修改任何檔案。
1. 讀 pom.xml、所有 Java 原始碼、application*.yml。
2. 依 Spring Boot 3.0 Migration Guide 的章節,逐條列出本專案受影響的地方:
   章節|受影響檔案:行號|目前寫法|需要的修改|自動化可行性(OpenRewrite 可處理/需人工)。
3. 列出所有 javax.* import(數量與檔案清單)。
4. 列出沒有 Jakarta 相容版本的第三方依賴,附你查到的依據;查不到就寫「未確認」。
5. 列出測試覆蓋不足、升級後難以驗證的模組。
輸出 docs/upgrade/impact-analysis.md。

如何審查:🔍 grep -rn "import javax\." src/main/java | wc -l,與報告數字比對;「未確認」的依賴由人到官方 Maven Central 或專案網站確認,不能讓 Agent 猜版本號。

9.4.2 範本 U2:升級計畫與風險清單

依 docs/upgrade/impact-analysis.md 產生 docs/upgrade/plan.md:
- 分批:每批一個 PR,每批都能獨立建置與測試通過。建議順序:
  (1) 清 deprecation (2) Java 17 (3) Spring Boot 3 + jakarta (4) Security 設定 (5) Java 21。
- 每批:修改範圍、預估檔案數、驗證方式、回復方式、風險(高/中/低)與緩解。
- 標出需要人工決策的地方(例如替換不再維護的函式庫)。
不要修改程式碼。

9.4.3 範本 U3:最小範圍修改(執行單一批次)

只執行 docs/upgrade/plan.md 的「批次 3:Spring Boot 3 + jakarta」。
- 在 ai/upgrade-batch-3 分支作業;只做計畫列出的修改,不順手重構、不改格式、不升級計畫外的依賴。
- 每類修改一個 commit(pom.xml、javax→jakarta、屬性改名)。
- 遇到計畫沒預料到的問題,停下來回報,不要自行擴大範圍。
- 完成後輸出交付報告(修改清單、測試結果、未完成與待確認),並附 git diff --stat。

如何審查:

檢查方法
範圍是否膨脹🔍 git diff --stat origin/main 的檔案數 vs 計畫預估;超出 20% 要求解釋
是否混入格式化🔍 git diff -w --stat(忽略空白)與 git diff --stat 差很多,代表有大量空白變更
是否偷改測試🔍 git diff origin/main -- src/test 逐行看;刪除斷言或加 @Disabled 一律退回
報告誠實性✅ check-change-report.py

❌ 壞例:Agent 為了讓編譯通過,把找不到 Jakarta 版本的函式庫整段註解掉,報告寫「已移除未使用的依賴」。對策:計畫中「需要人工決策」的項目,Prompt 明確要求停下來回報。

9.5 升級前後行為比對

比對項目方法工具
API 回應同一組請求打舊版與新版,比對 JSON(忽略時間戳、ID)契約測試、錄製回放
錯誤格式Spring Boot 3 的錯誤回應格式可能改變E2E
資料庫寫入同一批交易,比對資料表內容Testcontainers+比對 SQL
效能p95 延遲、記憶體、啟動時間JMeter、Gatling
安全標頭Strict-Transport-Security、CSRF 行為ZAP baseline
日誌格式監控與告警依賴的欄位是否改變人工比對

9.6 升級報告、回復方案與驗收清單

升級報告範本:

欄位內容
升級範圍Java 11 → 21、Spring Boot 2.7.18 → 3.3.x
批次與 PR批次 1~5,PR #101~#105
測試結果CI 連結;單元/整合/E2E 通過數與失敗數
行為差異9.5 的比對結果與判定
已知問題編號、影響、暫行方案
回復方案回到 tag pre-upgrade-20261027 的部署步驟、資料庫是否需要回復
簽核開發、QA、資安、維運

驗收清單:

  • 所有批次的 CI 全綠(不是 Agent 報告說綠)。
  • 沒有被停用或刪除的測試;覆蓋率不低於升級前。
  • SCA 掃描沒有新增 Critical/High。
  • 9.5 的行為比對差異都有判定與負責人。
  • 回復方案在測試環境演練過一次。
  • 部署環境(JRE、AP Server、容器基底)已同步升級並驗證。

9.7 本章實務案例與注意事項

案例:Agent 一次 PR 改了 412 個檔案(計畫預估 180),CI 全綠。

審查發現:其中 230 個檔案只是 import 排序與空白調整(Agent 的格式化習慣),真正的邏輯變更被淹沒;而且一支 @Scheduled 批次因 Spring Boot 3 的排程執行緒池預設改變而變成序列執行——CI 沒有效能測試,所以沒抓到。

改善:

  1. Prompt 加入「不改格式」,並在 CI 加入 formatter check 讓格式化變更獨立成 PR。
  2. 批次作業加入執行時間的監控與 9.5 的效能比對。
  3. 退回重做,按計畫拆成 5 個 PR。

注意事項:

  • 升級用的沙盒同樣只開必要端點(內部 Maven 代理、內部 Git);讓 Agent 自己上網找「最新版本」會引入未審查的依賴。
  • 版本號由人確認並寫進計畫;Agent 只負責照計畫修改。
  • 升級完成不等於可上線:仍需走第 10 章的 SSDLC 關卡。

第10章 企業 SSDLC 與 AI 協作流程

本章把 NemoClaw 放進企業的安全軟體開發生命週期(SSDLC)。核心是三方分工:人員負責決策、AI 負責受控輔助、工具負責客觀驗證。任何一方都不能取代另外兩方。參考框架:NIST SSDF SP 800-218、OWASP SAMM、OWASP ASVS、OWASP Top 10、OWASP Top 10 for LLM Applications。

10.1 三方分工模型

flowchart LR
    subgraph HUMAN["人員:決策與負責"]
        H1["定義需求與驗收標準"]
        H2["核准計畫與網路白名單"]
        H3["Code Review 與合併"]
        H4["上線決策"]
    end
    subgraph AI["AI Agent:受控輔助(在 NemoClaw 沙盒內)"]
        A1["草擬文件"]
        A2["實作與重構"]
        A3["產生測試"]
        A4["交付報告"]
    end
    subgraph TOOL["工具:客觀驗證(在 CI 內)"]
        T1["建置與測試"]
        T2["SAST、SCA、機密掃描"]
        T3["ArchUnit、交付報告比對"]
        T4["政策 lint"]
    end
    H1 --> A1
    A1 --> H2
    H2 --> A2
    A2 --> A3 --> A4
    A4 --> T1 --> T2 --> T3
    T3 --> H3 --> H4
    T4 --> H2
角色擁有不能做
人員決策權、核准權、責任把「AI 說通過」當成通過
AI Agent在沙盒內讀寫工作副本、呼叫核准的端點合併主線、改 CI、改政策、取得正式憑證
工具可重現的判定(通過/失敗)理解需求是否正確

10.2 各階段的 AI 適用範圍

階段輸入AI 工作輸出產物品質門檻人工核准點
需求分析原始需求、訪談紀錄整理 SRS 草稿、找出模糊處(7.6.1)SRS 草稿、Q 清單每條 FR 可追溯;Q 清單已回覆需求方簽核 SRS
系統分析與設計SRS、架構規範草擬 SDD、序列圖、DDL、ADR(7.6.2)SDD、OpenAPIMermaid 可渲染;依賴方向正確架構師核准
程式開發SDD、OpenAPI、AGENTS.md依核准計畫小步實作(7.6.4~7.6.5)ai/ 分支、交付報告check-change-report 0 問題;check-layering 0 違規開發者核准計畫
程式碼審查PR diff產生問題清單草稿(7.6.9)Review 意見高嚴重度問題全部處理Code Reviewer 核准合併
單元測試程式碼、規則補邊界與例外測試(7.6.6)測試程式CI 通過;覆蓋率不下降;無停用測試Reviewer 確認測試有斷言
整合測試API、資料庫草擬 Testcontainers 測試整合測試CI 通過QA
效能測試非功能需求草擬 JMeter/Gatling 腳本腳本在測試環境由工具量測效能負責人
弱點掃描原始碼、映像檔解讀掃描結果、草擬修補修補 PR無 Critical;High 有例外單資安
UAT驗收案例草擬測試案例與資料(合成)UAT 案例業務人員實際操作業務簽核
部署與上線建置產物、部署說明草擬部署與回復步驟Runbook演練過回復變更管理會議
維運與問題追蹤日誌(去敏)、錯誤報告初步分析根因分析報告可重現步驟維運負責人

⚠️ 警告:「部署與上線」階段的 AI 只能草擬文件,不得持有部署憑證或連線正式環境。NemoClaw 沙盒在 alpha 階段不應有任何通往正式環境的網路路徑(14.8)。

10.3 Git、分支與 Pull Request 規範(🏢)

規則說明
Agent 只能推 ai/* 分支Git Server 的分支權限限制 AI 用的 Token;寫入 preset 也只放行特定 repo 的 git-receive-pack
主線受保護main/release/* 需要 PR、CI 通過、至少一位人類核准
Commit 標示 AI 參與Commit 訊息加 trailer,例如 AI-Assisted: NemoClaw v0.0.139 / dcode 0.1.71 / sandbox dev-order
PR 必附交付報告放在 .ai-reports/<分支名>.md,CI 自動比對
CODEOWNERS.github/、CI 設定、presets/、AGENTS.md 由指定人員審查
不讓 Agent 改 CIAGENTS.md 禁止;CODEOWNERS 強制

PR 範本(.github/pull_request_template.md):

## 變更摘要

## AI 參與
- [ ] 本 PR 有 AI Agent 參與(NemoClaw 沙盒:___,Agent/版本:___)
- [ ] 交付報告:`.ai-reports/___.md`
- [ ] 我已閱讀完整 diff,不只是交付報告

## 驗證
- [ ] CI 全綠(連結:___)
- [ ] 沒有停用或刪除既有測試
- [ ] 沒有新增未核准的依賴

## 安全
- [ ] 沒有憑證、個資、客戶資料
- [ ] 沒有修改 CI、政策 preset、AGENTS.md(若有,已由 CODEOWNERS 審查)

10.4 CI/CD 中的品質與安全關卡

以下 GitHub Actions 範例示意關卡順序(🧪 未在實際 repo 執行;工具版本請依企業標準固定):

# .github/workflows/ai-pr-gates.yml
name: ai-pr-gates
on:
  pull_request:
    branches: [main]
jobs:
  gates:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 機密掃描
        run: docker run --rm -v "$PWD:/repo" zricethehacker/gitleaks:v8.21.2 detect --source /repo --no-banner

      - name: AI 交付報告比對(僅 ai/ 分支)
        if: startsWith(github.head_ref, 'ai/')
        run: |
          report=".ai-reports/${GITHUB_HEAD_REF#ai/}.md"
          test -f "$report" || { echo "缺少交付報告 $report"; exit 1; }
          python3 tools/check-change-report.py "$report" "origin/${GITHUB_BASE_REF}"

      - name: 架構快篩
        run: python3 tools/check-layering.py src/main/java com.example.order

      - name: 政策 preset lint(若有變更)
        run: |
          pip install pyyaml==6.0.3
          files=$(git diff --name-only "origin/${GITHUB_BASE_REF}" -- 'presets/*.yaml')
          [ -z "$files" ] || python3 tools/nemoclaw-policy-lint.py preset $files

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
          cache: maven

      - name: 建置、單元測試、ArchUnit、整合測試(Testcontainers)
        run: mvn -B -ntp verify

      - name: 依賴弱點掃描
        run: mvn -B -ntp org.owasp:dependency-check-maven:check -DfailBuildOnCVSS=9

      - name: 前端
        working-directory: web
        run: |
          npm ci
          npm run lint
          npx vue-tsc --noEmit
          npm run test:unit

      - name: SBOM
        run: mvn -B -ntp org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom

📌 註記:check-change-report.py 需要 fetch-depth: 0 才能取得 base 分支;GITHUB_HEAD_REF 的 / 會成為報告檔名的一部分,請依專案的分支命名調整。

10.5 測試證據與稽核保存

證據來源保存位置(🏢)保存期限建議
交付報告Agentrepo .ai-reports/隨程式碼
CI 執行紀錄與報告CICI 系統、artifact 庫依企業稽核規範
政策變更紀錄PRpresets/ 的 Git 歷史永久
openshell term 核准紀錄操作者手動記錄變更單依規範
沙盒日誌nemoclaw <名稱> logs日誌平台(14.7)依規範
Agent 對話紀錄sessions export(OpenClaw/Hermes)受控儲存(含敏感資料)依規範,需存取控制
安裝驗收(4.10)操作者環境申請單隨環境

10.6 本章實務案例與注意事項

案例:稽核要求「證明這個上線版本中 AI 寫的程式都經過人工審查」。

可提出的證據鏈:

  1. Git 歷史中帶 AI-Assisted trailer 的 commit 清單(git log --grep='AI-Assisted')。
  2. 每個相關 PR 的人工核准紀錄與 PR 範本勾選(「我已閱讀完整 diff」)。
  3. CI 對每個 PR 的 check-change-report、ArchUnit、掃描結果。
  4. 該時期使用的 NemoClaw 版本與政策 preset 版本(12.2 的盤點表、presets/ 的 Git tag)。

注意事項:

  • 品質門檻要在 CI 強制,而不是寫在 Prompt 裡「請確保測試通過」。
  • AI 參與的程度越高,Code Review 的標準越不能降低;reviewer 疲勞是真實風險,PR 要小。
  • 工具版本(gitleaks、Dependency-Check、PyYAML)要固定,避免 CI 結果因工具升級而漂移。

第11章 系統維護、監控與故障排除

官方 Troubleshooting 頁超過 3,000 行、上百個情境。本章整理企業最常遇到的 12 類問題,每類依「症狀/可能原因/檢查方式/解決方法(風險由低到高)/驗證方式/預防措施」六欄呈現。所有診斷指令標示執行位置;會刪資料或重新初始化的步驟以 ⛔ 標示。

11.1 診斷的三個起手式

# 🖥️ Host:任何問題先跑這三個(都是唯讀)
nemoclaw doctor                       # 主機、Runtime、OpenShell CLI、登錄、Gateway
nemoclaw <名稱> status                # 單一沙盒:Phase、Agent、Inference、恢復提示
nemoclaw <名稱> logs --tail 100       # 最近的生命週期、Gateway、政策拒絕

需要回報上游或交給內部支援時:

# 🖥️ Host:收集診斷包(上傳前人工檢查是否含主機名、內部 URL、使用者名稱)
nemoclaw debug --sandbox <名稱> --output ~/nemoclaw-debug-$(date +%Y%m%d%H%M).tgz
tar tzf ~/nemoclaw-debug-*.tgz | head -50

11.2 每日巡檢

檢查指令(🖥️ Host)正常異常處理
CLI 版本未漂移nemoclaw --version與 12.2 盤點表一致查是誰升級(~/.nemoclaw/ 時間戳)
全域狀態nemoclaw statusGateway healthy11.3.4
沙盒健康nemoclaw <名稱> statusReady、Inference healthy11.3.5~11.3.7
過期沙盒nemoclaw upgrade-sandboxes --check結束碼 0排入維護窗口 rebuild
政策漂移nemoclaw <名稱> policy list 與 Git 中的 preset 清單比對一致查 openshell term 是否有未記錄的核准
拒絕紀錄nemoclaw <名稱> logs --since 24h拒絕次數在基準內異常增加 → 6.10 事件流程
磁碟df -h ~ /var/lib/docker可用 > 20%11.3.11
推理費用供應商主控台在預算內暫停沙盒、查用量

把上表做成一支腳本,每天開工跑一次(🏢;🧪 依官方指令撰寫、未實機執行;list --json 的欄位名稱沿用 12.2 的假設,第一次使用前先確認):

#!/usr/bin/env bash
# nemoclaw-daily.sh — 🏢 每日巡檢(唯讀)。任何一項異常就以結束碼 1 結束,方便排程判斷
APPROVED=${APPROVED:-0.0.139}          # 平台管理者公告的核准版本
PRESET_LIST=${PRESET_LIST:-presets.txt} # 從 presets repo 匯出的「應有 preset」清單,每行一個
rc=0
v=$(nemoclaw --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)
[ "$v" = "$APPROVED" ] && echo "OK   版本 $v" || { echo "FAIL 版本 $v ≠ 核准 $APPROVED"; rc=1; }
nemoclaw upgrade-sandboxes --check >/dev/null 2>&1 && echo "OK   沙盒映像檔為最新" || { echo "WARN 有過期沙盒,排入維護窗口"; rc=1; }
for s in $(nemoclaw list --json | jq -r '.sandboxes[].name'); do
  nemoclaw "$s" status --json | jq -r --arg s "$s" \
    '"\(if .failureLayer == null and .inferenceHealth == "ok" then "OK  " else "FAIL" end) \($s) phase=\(.phase) inference=\(.inferenceHealth) failure=\(.failureLayer)"'
  nemoclaw "$s" policy list 2>/dev/null | sort > "/tmp/$s.policy"
  if [ -f "$PRESET_LIST" ] && ! diff -q <(sort "$PRESET_LIST") "/tmp/$s.policy" >/dev/null; then
    echo "FAIL $s 政策與 presets repo 不一致:diff <(sort $PRESET_LIST) /tmp/$s.policy"; rc=1
  fi
done
exit $rc
輸出判讀
全部 OK、結束碼 0可以開工
FAIL 版本有人自行升級或安裝程式抓到 lkg:查 ~/.nemoclaw/ 時間戳,依 13.10 處理
FAIL <沙盒> … failure=docker_unreachableDocker 沒在跑:11.3.3
FAIL <沙盒> … inference=unauthorizedKey 失效或被撤銷:11.3.7
FAIL <沙盒> 政策…不一致有人在 openshell term 核准了未記錄的規則,或 preset 被移除:6.10

⚠️ 警告:policy list 的輸出格式不是穩定介面,直接 diff 可能因格式差異誤報。第一次使用時,先人工對照輸出,再調整 presets.txt 的寫法。這一段標 🧪 就是這個原因。

11.3 常見問題卡

11.3.1 安裝失敗或版本不相容

欄位說明
症狀安裝程式中止;或 onboarding 印出 openshell <version> is above the maximum supported by this NemoClaw release
可能原因平台不支援(Intel Mac、非 apt 發行版);Node.js 太舊;缺 sha256sum/strings;有人自行升級了 OpenShell
檢查方式🖥️ openshell --version;grep -n openshell_version "$(npm root -g)/nemoclaw/nemoclaw-blueprint/blueprint.yaml"(🧪 路徑依 npm 全域 prefix 或 ~/.local shim 安裝方式而定);node -v;command -v sha256sum strings
解決方法① 依錯誤安裝缺少的工具(sudo apt-get install -y binutils)② 以固定版本重跑已審查的安裝程式,讓它安裝相容的 OpenShell ③ 確認不是在不支援的平台
驗證方式nemoclaw doctor 全部通過;nemoclaw --version 為預期版本
預防措施禁止單獨 openshell self-update/npm update -g openshell(13.11);版本固定寫進環境申請單

11.3.2 CLI 找不到或環境變數未生效

欄位說明
症狀nemoclaw: command not found;或 NEMOCLAW_DISABLE_TELEMETRY 設了卻好像沒效
可能原因nvm/fnm 沒更新目前 shell 的 PATH;CLI 以 shim 裝在 ~/.local/bin;環境變數放在管線左側(VAR=1 curl … | bash 只影響 curl)
檢查方式🖥️ ls -l ~/.local/bin/nemoclaw;echo $PATH;env | grep NEMOCLAW_
解決方法① source ~/.bashrc 或開新終端機 ② 把 ~/.local/bin 加入 PATH ③ 安裝相關變數改放在 bash 那一側或先 export
驗證方式command -v nemoclaw、nemoclaw --version
預防措施在 ~/.bashrc 固定 export NEMOCLAW_DISABLE_TELEMETRY=1;SOP 統一寫法

11.3.3 Docker、WSL 2 或沙盒啟動失敗

欄位說明
症狀docker info 失敗;Cannot connect to the Docker daemon;permission denied;onboarding 逾時 did not become ready within Ns;exit 137
可能原因Docker 未啟動;使用者不在 docker 群組(或群組未在目前 shell 生效);Docker Desktop 沒開 WSL integration;記憶體不足被 OOM;cgroup v2 問題
檢查方式🖥️ systemctl status docker;id -nG;🐧 docker info;🪟 wsl -l -v;dmesg | grep -i oom(🧪 需權限)
解決方法① 啟動 Docker(Linux sudo systemctl start docker;Windows 開 Docker Desktop)② newgrp docker 後重跑 ③ Docker Desktop → Settings → Resources → WSL integration 勾選發行版 ④ 記憶體不足時建立 swap(官方步驟:4 GB /swapfile)⑤ 提高 NEMOCLAW_SANDBOX_READY_TIMEOUT
驗證方式docker run --rm busybox true 成功;nemoclaw onboard --resume 完成
預防措施主機規格依 3.2 的企業建議;WSL 主機固定 Docker Desktop 版本

11.3.4 Gateway 連線異常

欄位說明
症狀connect 因 Gateway down 退出;status 顯示 Gateway unhealthy;連接埠 8080 被占用
可能原因OpenShell Gateway 程序沒啟動(主機重開機後最常見);連接埠衝突;systemd user manager 不可用
檢查方式🖥️ systemctl --user status openshell-gateway;ss -ltnp | grep 8080;nemoclaw doctor
解決方法① Linux:systemctl --user restart openshell-gateway,再 nemoclaw <名稱> recover ② macOS:重跑 NemoClaw 安裝程式讓它修復受管的 Homebrew 服務(官方建議,不要直接 brew services)③ 連接埠衝突:停掉占用程序,或依官方指引以 NEMOCLAW_GATEWAY_PORT 使用替代連接埠
驗證方式nemoclaw status Gateway healthy;nemoclaw <名稱> connect 成功
預防措施開機後的「Reconnect after a host reboot」步驟寫成 SOP;官方不保證重開機後自動復原

11.3.5 Agent 無法回應

欄位說明
症狀Dashboard 打不開;TUI 沒反應;dcode -n 逾時(結束碼 124)
可能原因沙盒內 Agent Gateway 停了;沙盒 Stopped;推理逾時;OpenClaw 裝置配對未完成(scope upgrade pending approval)
檢查方式🖥️ nemoclaw <名稱> status;nemoclaw <名稱> logs --tail 100;📦 dcode status
解決方法① nemoclaw <名稱> recover ② nemoclaw <名稱> gateway restart ③ 沙盒 Stopped:nemoclaw <名稱> start ④ OpenClaw 配對:nemoclaw onboard --resume ⑤ 仍失敗:rebuild(會保留原生 home)
驗證方式4.9 的測試請求成功
預防措施監控 status --json 的 Phase;推理逾時見 11.3.6

11.3.6 模型推理服務連線失敗

欄位說明
症狀status 的 Inference 行逾時;Agent 回報 TLS 或連線錯誤;本地 Ollama/vLLM 不可達
可能原因推理端點不可達(企業防火牆);企業 TLS 攔截但未設 CA;本地服務沒啟動或綁錯介面;IPv6 解析問題
檢查方式🖥️ nemoclaw <名稱> status(會從沙盒內走實際路徑探測);curl -sS -m 10 https://integrate.api.nvidia.com/v1/models -o /dev/null -w '%{http_code}';本地:curl -sS http://127.0.0.1:11434/api/tags
解決方法① 開通防火牆到推理端點 ② 設 NEMOCLAW_CORPORATE_CA_BUNDLE 後 rebuild ③ 啟動本地服務 ④ 慢速網路或大模型:export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 後重新 onboarding
驗證方式status Inference healthy;4.9 測試成功
預防措施推理端點列入網路白名單基準;本地服務設為系統服務

11.3.7 API Key 或 Provider 設定錯誤

欄位說明
症狀status 回報 unauthorized(HTTP 401/403);onboarding 驗證失敗;換了 Key 仍用舊的
可能原因Key 過期或撤銷;額度用完;選錯 Provider;Hermes 原生 NVIDIA 路由的憑證參照過期
檢查方式🖥️ nemoclaw credentials list(只證明存在);nemoclaw <名稱> status(實際驗證);nemoclaw inference get
解決方法① 依 6.6 以新 Key 重跑 nemoclaw onboard --name <名稱> ② Hermes 憑證參照過期:nemoclaw <名稱> rebuild --yes ③ 沒有替代 Key 且需立即停用:nemoclaw credentials reset <Provider>
驗證方式nemoclaw <名稱> agent … 或 dcode -n 回覆預期字串
預防措施Key 到期前 14 天輪替;供應商端設額度告警

11.3.8 網路政策阻擋必要服務

欄位說明
症狀CONNECT tunnel failed, response 403;exec 失敗時 stderr 出現 recent network policy denial detected for <host>:<port>
可能原因端點不在政策中;binary 不符(例如 preset 只放行 git,卻用 curl);方法或路徑不符;私有 IP 被 SSRF 防護擋下;Personal 層以外的 host.docker.internal 路徑
檢查方式🖥️ nemoclaw <名稱> logs --tail 50(看被拒的 host、binary);nemoclaw <名稱> policy list;openshell policy get <名稱>;openshell term 觀察即時請求
解決方法① 確認需求是否合理(可能是被誘導的請求)② 已有核准的 preset 卻沒套用:policy add ③ 新需求:走 13.4 申請、6.11 撰寫、6.16 審查 ④ 私有主機:--trusted-private-host ⑤ 一次性需求:在 openshell term 核准單一規則
驗證方式6.12 的 V1~V6
預防措施preset 放 Git 並在 onboarding 時一併套用;官方提醒:能在建置期安裝的套件就不要在執行期下載

11.3.9 檔案權限不足

欄位說明
症狀Permission denied、Read-only file system;tmux 顯示 fork failed: Permission denied;Deep Agents 啟動失敗
可能原因寫到唯讀路徑(設計如此);--host-mount 本來就是唯讀;Landlock strict(Deep Agents)無法執行而 fail closed;用 docker exec 以 root 改過檔案造成擁有者錯亂
檢查方式📦 id、ls -ld <路徑>;🖥️ nemoclaw <名稱> doctor;awk '$2=="/sandbox/src"{print $4}' /proc/mounts(📦)
解決方法① 改寫到 /sandbox 或 /tmp ② 需要寫回主機時改用 download 或 Git,而不是要求讀寫掛載 ③ 核心不支援 Landlock:升級到 5.13 以上的核心 ④ 權限錯亂:rebuild
驗證方式4.10 的檢查 2、3 符合預期
預防措施禁止 docker exec 操作沙盒;工作目錄統一在 /sandbox/work

11.3.10 狀態保存或恢復失敗

欄位說明
症狀rebuild 中斷;backup-all 報 incomplete backup;sandboxes.json 不是有效 JSON;沙盒在登錄中但 Gateway 找不到
可能原因重建過程被中斷;原生 home 內放了憑證導致封存的憑證掃描失敗;登錄檔損壞;Gateway 重建後遺失沙盒
檢查方式🖥️ nemoclaw list --json;ls -la ~/.nemoclaw/rebuild-backups/;python3 -m json.tool ~/.nemoclaw/sandboxes.json
解決方法① 中斷的重建:以相同設定重跑 nemoclaw <名稱> rebuild(官方:不要手動刪 onboard-session.json 或 .onboard-rebuild-<名稱>.json)② 封存失敗:移除原生 home 內的明文憑證 ③ 登錄檔損壞:cp ~/.nemoclaw/sandboxes.json ~/.nemoclaw/sandboxes.json.bad && rm ~/.nemoclaw/sandboxes.json(官方步驟;⛔ 先備份)④ 沙盒已不存在:⛔ nemoclaw <名稱> destroy 清除紀錄後重新 onboarding,再以獨立備份還原
驗證方式nemoclaw list 正常;status Ready;工作目錄內容完整
預防措施重建前額外做 5.10 的獨立備份;不在原生 home 放憑證

11.3.11 磁碟不足、資源耗盡或效能下降

欄位說明
症狀映像檔推送失敗;建置變慢或卡住;主機回應遲緩;DGX Spark 上本地 vLLM 負載時主機凍結
可能原因舊沙盒映像檔累積;rebuild-backups/ 累積;容器 Runtime 資源配置不足(Colima、Docker Desktop);本地模型吃滿記憶體
檢查方式🖥️ df -h;docker system df;du -sh ~/.nemoclaw/rebuild-backups/;nemoclaw resources --json
解決方法① nemoclaw gc --dry-run 後 nemoclaw gc --yes ② 清理過期的 rebuild-backups/(⛔ 確認已有其他備份)③ 調高 Docker Desktop/Colima 的 CPU 與記憶體 ④ 停止不用的沙盒(stop)⑤ 本地模型改用較小的 profile
驗證方式可用空間 > 20%;onboarding 或 rebuild 完成
預防措施每週例行 gc;備份保留策略(12.3)

11.3.12 升級後服務無法啟動

欄位說明
症狀升級後 Installation completed with warnings;沙盒 not Ready;connect 警告 Agent 版本過期;舊沙盒無法 resume 或 rebuild
可能原因升級程序中某沙盒的備份或自動重建失敗;舊版沙盒沒有原生 Provider 附掛(2.6);OpenShell Gateway 版本不符
檢查方式🖥️ 安裝程式輸出的 recovery 訊息;nemoclaw upgrade-sandboxes --check;nemoclaw <名稱> status
解決方法① 依安裝程式提示的備份路徑與指令處理(nemoclaw onboard --resume/nemoclaw <名稱> rebuild)② 舊版沒有附掛的沙盒:先備份,再 nemoclaw onboard --fresh --name <名稱> --recreate-sandbox(⛔ 會取代原沙盒)③ 無法修復:依 12.6 回復到舊版
驗證方式upgrade-sandboxes --check 結束碼 0;4.10 驗收重跑通過
預防措施先在測試主機演練(12.4);升級前 backup-all+獨立備份

11.4 故障排除紀錄範本

欄位填寫內容
紀錄編號TS-2026-0001
日期時間2026-10-27 14:30
主機與沙盒dev-host-07/dev-order
版本NemoClaw v0.0.139、OpenShell 0.0.116、dcode 0.1.71
症狀(使用者觀察到的現象、錯誤訊息原文)
問題卡分類11.3.x
診斷步驟與輸出(指令+重點輸出;敏感資訊遮蔽)
根因—
解決方法—
驗證結果—
預防措施—
是否需更新規範或 preset是/否,PR 連結

11.5 本章實務案例與注意事項

案例:週一早上,整個部門的 NemoClaw 主機都顯示沙盒 Stopped。

原因:週末 OS 自動更新後重開機。官方說明重開機後容器 Runtime、OpenShell Gateway 與沙盒可能都沒有執行,自動復原不保證。

處置 SOP:

  1. 🖥️ sudo systemctl start docker(若未自動啟動)。
  2. 🖥️ systemctl --user status openshell-gateway,必要時 restart。
  3. 🖥️ 每個沙盒 nemoclaw <名稱> start。
  4. 🖥️ nemoclaw <名稱> status 確認 Ready,重跑 4.10 的檢查 1、5。

注意事項:

  • 解決方法依「風險由低到高」排列;不要一開始就 destroy 或 --recreate-sandbox。
  • 回報上游問題前,先確認版本是否為最新的 lkg 或 latest,並搜尋 GitHub Issues。
  • 安全漏洞走 SECURITY.md 的私密管道,⛔ 不開公開 Issue。

第12章 版本升級、備份、復原與解除安裝

NemoClaw 約每週發布一版,而且它把 OpenShell、Agent 版本、沙盒映像檔都綁在一起。本章的前提是:不要假設有完整的自動回復。官方提供的是「重建時保留原生 home」與「升級前備份」;版本回退、跨版本還原,都需要人工備份與演練。

12.1 版本關係

flowchart TB
    NC["NemoClaw CLI v0.0.139<br/>安裝程式:lkg 或指定 tag"]
    BP["Blueprint<br/>min/max_openshell_version = 0.0.116"]
    OS["OpenShell 0.0.116<br/>CLI、Gateway、SDK"]
    IMG["沙盒映像檔<br/>三個 Agent 同一發佈批次<br/>以 sha256 digest 釘選"]
    AG["Agent 版本<br/>烤進映像檔:OpenClaw、Hermes、dcode 0.1.71"]
    MDL["模型<br/>由推理服務決定"]
    PRJ["專案依賴<br/>Maven、npm"]
    NC --> BP --> OS
    NC --> IMG --> AG
    AG -.->|"呼叫"| MDL
    AG -.->|"在工作副本中"| PRJ
元件誰決定版本如何升級注意
NemoClaw CLI安裝程式(預設 lkg)重跑安裝程式(指定 tag)nemoclaw update 也走同一套安裝流程
OpenShellBlueprint 的版本範圍隨 NemoClaw 安裝程式⛔ 不可單獨升級
沙盒映像檔與 AgentNemoClaw 版本nemoclaw <名稱> rebuild 或 upgrade-sandboxes官方:不要在沙盒內就地更新 Agent(Agent 綁在映像檔)
模型推理服務inference set 或重新 onboarding模型行為變化不在 NemoClaw 控制內
專案依賴專案第 9 章—

12.2 升級前的版本盤點

🏢 盤點腳本(🧪 依官方指令撰寫,未實機執行;--json 欄位結構以實際輸出為準):

#!/usr/bin/env bash
# nemoclaw-inventory.sh — 記錄目前環境與依賴版本(唯讀)
set -u
OUT=${1:-inventory-$(hostname)-$(date +%Y%m%d%H%M).md}
{
  echo "# NemoClaw 環境盤點 $(date -Iseconds)"
  echo "## 主機"
  echo '```text'
  . /etc/os-release; echo "OS: $PRETTY_NAME"; echo "Kernel: $(uname -r)"
  echo "Docker: $(docker version --format '{{.Server.Version}}' 2>/dev/null || echo n/a)"
  echo "Node: $(node -v 2>/dev/null)  npm: $(npm -v 2>/dev/null)"
  echo '```'
  echo "## NemoClaw 與 OpenShell"
  echo '```text'
  nemoclaw --version
  openshell --version 2>/dev/null || echo "openshell: n/a"
  echo '```'
  echo "## 沙盒"
  echo '```json'
  nemoclaw list --json
  echo '```'
  for s in $(nemoclaw list --json | jq -r '.sandboxes[].name' 2>/dev/null); do
    echo "### $s"
    echo '```text'
    nemoclaw "$s" status 2>&1 | sed -n '1,40p'
    nemoclaw "$s" policy list 2>&1
    echo '```'
  done
  echo "## 需要升級的沙盒"
  echo '```text'
  nemoclaw upgrade-sandboxes --check 2>&1; echo "exit=$?"
  echo '```'
} > "$OUT"
echo "已寫入 $OUT"

📌 註記:nemoclaw list --json 的頂層欄位包含 schemaVersion、預設沙盒、復原中繼資料與沙盒清單(官方 Commands 說明);上面以 .sandboxes[].name 取名稱是 🧪 假設,請先執行一次確認欄位名稱。

12.3 備份範圍

對象位置是否在 rebuild 內建封存中建議備份方式
Agent 原生 home/workspace沙盒內(OpenShell 儲存)✅ 是backup-all+5.10 的獨立 download
專案工作副本沙盒 /sandbox/work✅ 是(在 home 下)優先 git push 到 ai/ 分支;其次 download
OpenShell 政策OpenShell以即時政策整份帶過去nemoclaw <名稱> policy get > policy-<名稱>.yaml(憑證已遮蔽)
自訂 preset 原始檔企業 Git repo presets/—Git
主機狀態~/.nemoclaw/(config.json、sandboxes.json 等)—複製到安全位置(⛔ 不放進映像檔、Git 或支援包——官方安全建議)
重建備份~/.nemoclaw/rebuild-backups/—依保留政策
推理與 MCP 憑證OpenShell Gateway❌ 不在任何封存中由企業密碼庫保管原始值;重建後重新註冊
設定匯出(為 v1 準備)——nemoclaw config export <名稱> --output <檔>(不含憑證值)

⚠️ 警告:官方 Persist Sandbox State 頁說明,destroy 會刪除沙盒的持久化狀態;Deep Agents 會清除整個保留的 /sandbox 根目錄。destroy 前必須先 download 需要的檔案。

12.4 測試環境的升級演練

步驟動作通過條件
1在測試主機安裝與正式(試行)主機相同的版本,建立相同 preset 的沙盒4.10 驗收通過
2放入合成資料的工作副本—
3執行 12.2 盤點存檔
4依 12.5 升級到目標版本安裝程式無 warning
5upgrade-sandboxes --check結束碼 0
6重跑 4.10、6.12 V1~V6全部符合
7跑一次 7.6.4 的開發任務交付報告與 CI 通過
8演練 12.6 的回復能回到升級前狀態
9讀新版 release notes,標出影響本企業的項目寫進升級單

12.5 升級程序

# 🖥️ Host:1. 盤點與備份
bash nemoclaw-inventory.sh
nemoclaw backup-all
for s in dev-order re-legacy; do nemoclaw "$s" policy get > "policy-$s-$(date +%Y%m%d).yaml"; done

# 2. 取得並審查新版安裝程式(同 4.3)
NEW=v0.0.140          # 🧪 範例版本號,依實際 release 填寫
curl -fsSL "https://raw.githubusercontent.com/NVIDIA/NemoClaw/${NEW}/install.sh" -o "install-${NEW}.sh"
curl -fsSL "https://raw.githubusercontent.com/NVIDIA/NemoClaw/${NEW}/nemoclaw-blueprint/blueprint.yaml" \
  | grep -E '^(min|max)_openshell_version'          # 確認新版要求的 OpenShell 範圍

# 3. 升級(安裝程式會再備份一次、必要時汰換 Gateway、執行 upgrade-sandboxes --auto)
export NEMOCLAW_DISABLE_TELEMETRY=1
NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG="$NEW" bash "install-${NEW}.sh"

# 4. 確認
nemoclaw --version
nemoclaw upgrade-sandboxes --check; echo "exit=$?"

安裝程式的結果判讀(📖 Update Sandboxes):

訊息意義處理
Confirmed recovery既有沙盒已復原並升級進行驗收
Installation completed with warnings復原未確認,或記錄的沙盒在 Gateway 上找不到依提示檢查,不要直接開始新 onboarding
非零結束、備份被略過或失敗升級在一般 onboarding 前中止依保留的備份路徑處理

📌 註記:若既有 OpenShell 版本落在新版支援範圍外,安裝程式會在備份後汰換 Gateway 再替換 OpenShell;版本未知或範圍無效時會停止而不汰換。官方另有「手動準備的升級」流程(backup-all --retire-legacy-forwards+openshell gateway destroy+NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1),只在官方指示時使用。

12.6 升級失敗時的復原策略

情境策略支援程度
單一沙盒升級後異常nemoclaw <名稱> rebuild(以目前映像檔重建並還原 home)📖 官方支援
重建中斷以相同設定重跑 rebuild(續作交易)📖 官方支援
新版 CLI 本身有問題,要回到舊版明確指定舊版 tag 重跑安裝程式(NEMOCLAW_INSTALL_TAG=v0.0.139);lkg 不會自動降級,nemoclaw update 有 --allow-downgrade🧪 官方未提供完整的降級保證:已用新映像檔重建的沙盒、新版寫入的狀態格式,舊版不一定讀得懂
沙盒無法修復以獨立備份(5.10)+重新 onboarding+upload 還原🏢 人工程序
主機整體損壞新主機依第 4 章重建,從 Git 與獨立備份還原🏢 人工程序(官方:獨立的機隊備份與災難復原是操作者責任)

回復計畫範本:

欄位內容
升級單號CHG-2026-0420
升級前版本NemoClaw v0.0.139/OpenShell 0.0.116
目標版本(填寫)
回復觸發條件4.10 任一項失敗;6.12 V1~V6 任一項不符;CI 任務成功率下降 > 20%
回復步驟1. 停止所有沙盒 2. 以舊版 tag 重跑安裝程式 3. 各沙盒 upgrade-sandboxes --check 4. 無法啟動者以獨立備份重新 onboarding+upload 5. 重跑 4.10
資料保全backup-all 路徑、獨立備份路徑、policy get 匯出檔
預估時間(填寫)
決策者(填寫)

12.7 沙盒重建與狀態恢復的差異

rebuild獨立備份+重新 onboarding+upload
觸發升級 Agent、套用建置期設定沙盒損壞、跨主機搬移、版本回退
搬移內容完整原生 home/workspace(不需 allowlist)只有你下載的檔案
政策目前的 OpenShell 即時政策整份帶過去回到 onboarding 選的層級+preset;自訂 preset 要重新套用
憑證不在封存內;主機端設定重新套用需重新註冊
主機端擁有的設定(推理、政策、訊息)依主機紀錄重新套用依新 onboarding
風險原生 home 有明文憑證時會中止漏下載檔案就遺失

怎麼證明 rebuild 沒有弄丟東西(🖥️ Host;🧪 未實機執行):

# 1. 重建前:記錄政策與工作區檔案指紋
nemoclaw dev-order policy list | sort > before-policy.txt
nemoclaw dev-order exec -- sh -c \
  'cd /sandbox/work && find . -type f -not -path "*/.git/*" -exec sha256sum {} + | sort -k2' > before-files.txt
# 2. 重建
nemoclaw dev-order rebuild
# 3. 重建後:重新記錄並比對(兩個 diff 都應沒有輸出)
nemoclaw dev-order policy list | sort > after-policy.txt
nemoclaw dev-order exec -- sh -c \
  'cd /sandbox/work && find . -type f -not -path "*/.git/*" -exec sha256sum {} + | sort -k2' > after-files.txt
diff before-policy.txt after-policy.txt && diff before-files.txt after-files.txt && echo "rebuild 前後一致"

選擇範例:

情境選擇理由
NemoClaw 從 v0.0.137 升到 v0.0.139,要讓 Agent 跟著升級rebuild只有換映像檔,原生 home 要完整帶過去
懷疑沙盒被 Prompt Injection 改過 AGENTS.md 或 Agent 記憶獨立備份+重新 onboardingrebuild 會把被污染的 home 一起帶過去(6.18 的 ASI06)
主機要退役,沙盒搬到新主機獨立備份+重新 onboarding+upload封存與憑證都不能跨主機搬移

12.8 解除安裝前的資料保留與憑證撤銷

# 🖥️ Host:解除安裝前檢查表的指令部分
nemoclaw list
for s in $(nemoclaw list --json | jq -r '.sandboxes[].name'); do   # 🧪 欄位名稱見 12.2 註記
  nemoclaw "$s" download /sandbox/work/ "./final-backup/$s/work/"
done
nemoclaw credentials list          # 記下 Provider 名稱,到上游供應商撤銷對應 Key
nemoclaw uninstall                 # 預設保留 rebuild-backups/、backups/、sandboxes.json
步驟動作
1所有工作副本已推送到 Git 或下載
2需要的對話紀錄已 sessions export(OpenClaw/Hermes)
3到推理供應商、MCP Server、Git Server 撤銷 NemoClaw 使用的 Key 與 Token(解除安裝不會撤銷上游憑證)
4執行 nemoclaw uninstall(多個 Gateway 連接埠時依提示使用 --all-gateway-ports)
5確認保留的 ~/.nemoclaw/ 內容,依資料保存規範決定是否刪除
6⛔ --delete-models 會刪除 Ollama 回報的所有模型(包含其他應用程式使用的),確認後才使用
7從資產清冊移除主機或標註停用

📌 註記:nemoclaw uninstall 執行的是已安裝套件內附的 uninstall.sh;若本機腳本遺失,CLI 不會自動下載遠端版本,而是印出對應版本的網址讓你下載審查後手動執行。只有 CLI 已損壞時才使用官方的 curl … uninstall.sh | bash 形式。

12.9 升級完成後的驗收

  • nemoclaw --version 為目標版本;12.2 盤點表已更新。
  • nemoclaw upgrade-sandboxes --check 結束碼 0。
  • 每個沙盒 status 為 Ready、Inference healthy、Agent 版本為新版。
  • 4.10 控制有效性驗證全部通過。
  • 6.12 V1~V6 全部符合(政策沒有在升級中被放寬或遺失)。
  • policy list 與 Git 中的 preset 清單一致。
  • 一個代表性開發任務的交付報告與 CI 通過。
  • 新版 release notes 中影響企業的項目已評估並記錄。

每一項的驗證指令與通過標準(▶️):

驗收項目指令(🖥️ Host)通過標準
版本nemoclaw --version等於目標版本
安全下限bash check-security-floor.sh(6.17.1)結束碼 0
沙盒映像檔nemoclaw upgrade-sandboxes --check; echo $?0
沙盒健康nemoclaw <名稱> status --json | jq '{phase, inferenceHealth, failureLayer}'failureLayer 為 null,inferenceHealth 為 ok(並照 4.9 實際送一次請求)
控制有效4.10 的驗收腳本全部 PASS
政策未被放寬12.7 的 policy list 前後比對diff 沒有輸出
交付流程選一個代表性任務跑完第 7 章流程CI 綠燈、check-change-report.py 0 項問題

❌ 壞例的驗收紀錄:「升級完成,Agent 可以正常對話」。這句話只證明推理通了,沒有證明政策沒被放寬、憑證沒有外洩、版本是對的。驗收紀錄要附上表中每一列的指令輸出。

12.10 升級檢查清單與維護紀錄表

升級檢查清單:

  • 已閱讀目標版本 release notes 與 Platform Support 變更。
  • 已確認目標版本的 OpenShell 版本範圍。
  • 已在測試主機完成 12.4 演練。
  • 已執行 12.2 盤點並存檔。
  • 已 backup-all、獨立備份、policy get 匯出。
  • 已通知使用者並排定維護窗口。
  • 已準備 12.6 回復計畫並指定決策者。
  • 升級後已完成 12.9 驗收。

維護紀錄表:

日期主機作業類型變更前版本變更後版本執行者驗收結果備註/單號
2026-10-27dev-host-07新安裝—v0.0.139/OS 0.0.116(姓名)4.10 通過CHG-2026-0412
升級/rebuild/preset 變更/憑證輪替

12.11 下一版升級預警:OpenShell 0.1.5 遷移(main 未發布)

研究日(2026-10-27)的狀態:

項目狀態來源
main 的 Blueprintmin_openshell_version 與 max_openshell_version 仍為 0.0.116nemoclaw-blueprint/blueprint.yaml@bafe6cc
升級 PR#12603「upgrade OpenShell runtime and SDK to 0.1.5」:OPEN,PR 自述 Not ready for approval or merge,完整驗證尚未完成PR 描述
維護者決定授權「進行 v0.1.5 依賴更新與驗證」,不是授權合併或發布;上游的 TLS、Personal 層網路存取與 GPU 問題仍未解決PR 描述引用的維護者留言
前置工作(已合併)#13635、#13763:讓受信任的 E2E 控制器可以驗證 OpenShell 0.1.3/0.1.5 候選版PR 描述
最近一次完整 E2E74 通過、9 失敗、19 跳過;失敗集中在 Docker MCP bridge(三個 Agent)、Hermes GPU、Pi、Personal 層對外存取、受保護映像檔的 GPU 本地推理PR 描述

PR #13635 的重現測試在 0.1.x 候選版上發現 Gateway 設定、volume 掛載許可、受管啟動、復原查詢與原生推理都有不相容。下一版若改綁 0.1.5,預期影響如下:

影響面預期變化企業要準備的事
推理路由OpenShell 0.1.0 已移除 inference.local;PR 改用「附掛到沙盒的原生推理 Provider」盤點仍走共享路由的沙盒(status --json 的 recordedRoute),升級後逐一驗證 4.9
Gateway 與 SDKCLI、SDK、Gateway、supervisor、映像檔與雜湊全部更新自寫的腳本若解析 OpenShell 輸出,要重新測試
舊 volumePR 原則是「保留舊 volume 不變、不做自動複製;所有權無法證明時,在修改前停止」升級前一定要有 12.3 的獨立備份;做好「舊沙盒資料要手動搬」的準備
憑證與 ProviderPR 宣稱保留憑證保管方式與操作者擁有的 Provider升級後跑 13.5 的 placeholder 檢查,確認憑證沒有落地
GPU維護者要求保留 GPU 支援,但 GPU 相關 E2E 仍有失敗用本地 GPU 推理的主機最後才升級
備份安裝程式在升級 OpenShell 前會用嚴格模式執行 backup-all,有一般沙盒被略過或失敗就中止升級前把所有沙盒啟動起來,避免被略過而中止(📖 Commands 參考)

自己追蹤進度(🖥️ Host,唯讀;✅ 研究日實際執行,以下是當日輸出):

gh pr view 12603 -R NVIDIA/NemoClaw --json state,isDraft,mergedAt,title
# {"isDraft":false,"mergedAt":null,"state":"OPEN","title":"chore(deps): upgrade OpenShell runtime and SDK to 0.1.5"}

curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/main/nemoclaw-blueprint/blueprint.yaml \
  | grep -E '^(min|max)_openshell_version'
# min_openshell_version: "0.0.116"
# max_openshell_version: "0.0.116"

git ls-remote --tags https://github.com/NVIDIA/NemoClaw.git \
  | grep -E 'refs/tags/v0\.0\.[0-9]+\^\{\}$' | sed -E 's#\^\{\}##' | sort -k2 -V | tail -3
# f00fb1da…  refs/tags/v0.0.137
# 7312e7f4…  refs/tags/v0.0.138
# a08ae7aa…  refs/tags/v0.0.139

git ls-remote https://github.com/NVIDIA/NemoClaw.git 'refs/tags/lkg^{}'
# f00fb1da…  refs/tags/lkg^{}      ← 與 v0.0.137 相同
觀察到的變化代表什麼平台管理者的動作
mergedAt 不再是 null0.1.5 已進入 main開始準備 12.4 演練環境;暫停核准任何新版本
Blueprint 的 max_openshell_version 變成 0.1.5下一個 tag 會帶 0.1.5讀該版 release notes,逐項對照上方影響表
出現新 tag,且 lkg 指向它官方認為它是 last known good仍不能直接升級:在測試主機完成 12.4、12.9 才核准

⚠️ 警告:PR 描述與 E2E 結果是「開發中的狀態」,合併前後都可能改變。本節只用來提早準備,正式升級時以當時的 release notes 與實測結果為準。

12.12 本章實務案例與注意事項

案例:同仁在沙盒內執行 openclaw update 想升級 OpenClaw,結果指令卡住,之後 connect 警告版本不一致。

說明:官方 Enterprise Readiness 頁明言不要在沙盒內就地更新 Agent,因為 Agent 綁在映像檔版本;官方 Troubleshooting 也有「openclaw update hangs or times out inside the sandbox」一節。正確做法是升級 NemoClaw 後執行 nemoclaw <名稱> rebuild。

注意事項:

  • 升級是「整組」的:NemoClaw、OpenShell、映像檔、Agent 一起動;不要嘗試只換其中一個。
  • 憑證永遠不在封存內;企業密碼庫才是憑證的真相來源。
  • 為未來的 v1 遷移,可定期執行 nemoclaw config export 保留宣告式設定(不含憑證)。

第13章 企業導入與同仁使用規範

本章是一份可以直接改寫成內部規範的範本(🏢 全章皆為企業建議,不是 NemoClaw 原生功能)。原則只有一條:不可只依賴 Agent 的自我約束——每一條規範都要對應到技術防護、行政規範或人工審查其中至少一層。

13.1 適用人員與角色權責

角色職責不可兼任
使用者(開發者)在核准的主機與沙盒中使用 Agent;審查 AI 產出;維護交付報告不得自行核准自己的白名單申請
主機操作者安裝、升級、備份、openshell term 核准;官方定義的「單一受信任操作者」通常與使用者同一人(一人一台主機)
政策審查者審查 preset 與白名單申請(6.16)不得是申請人本人
平台管理者標準映像、標準 preset、版本基準、盤點—
資安資料分級、事件處理、例外核准—
專案負責人決定專案是否可用 AI、資料能否送外部模型—
Code Reviewer審查 AI 參與的 PR不得是該 PR 的唯一作者

📌 註記:NemoClaw 沒有操作者 RBAC(官方:Out of scope)。主機上能執行 nemoclaw 的帳號就擁有全部操作權。角色分離只能靠「一人一台主機」加上行政與審查流程達成。

13.2 開發環境申請與初始化

申請單必填欄位:

欄位範例
申請人/主管—
用途新開發/逆向工程/升級
專案與資料分級order-service/內部(13.6)
主機專用 VM:Ubuntu 24.04、8 vCPU、32 GB、100 GB
NemoClaw 版本v0.0.139(依平台管理者公告的基準)
AgentLangChain Deep Agents Code
推理服務企業私有端點/外部(需資料擁有者核准)
政策層級與 presetRestricted+corp-maven-readonly+corp-git-order-read
到期日最長 90 天,可續約

初始化完成的證據(附在申請單):

  • 3.9 預檢腳本輸出(結束碼 0)。
  • nemoclaw host probe --json 輸出。
  • 4.10 控制有效性驗證輸出。
  • 6.12 V1~V6 輸出。
  • ~/.bashrc 已含 export NEMOCLAW_DISABLE_TELEMETRY=1。
  • 12.2 盤點表。

13.3 專案目錄與檔案存取規範

規範技術防護行政規範人工審查
工作副本只放在沙盒 /sandbox/work/<專案>沙盒檔案系統限制本規範—
原始碼以 git clone 進沙盒;逆向工程以 --host-mount 唯讀掛入唯讀掛載、Git preset 的 repo 路徑本規範環境申請時審查
⛔ 不得以 share mount 掛家目錄或多個專案—本規範抽查 share status
⛔ 不得把 .env、金鑰、憑證檔放進沙盒部分:rebuild 的憑證掃描本規範交付報告的 FORBIDDEN 檢查
⛔ 不得以 docker exec 操作沙盒—本規範—
一個沙盒只處理一個專案Git preset 綁定 repo本規範—

範例與驗證:

# 🖥️ Host:抽查沙盒內有沒有不該出現的檔案(🧪 未實機執行;預期沒有任何輸出)
nemoclaw dev-order exec -- sh -c \
  'find /sandbox -maxdepth 4 \( -name ".env" -o -name ".env.*" -o -name "*.pem" -o -name "*.key" -o -name "id_rsa*" -o -name "id_ed25519*" \) 2>/dev/null'
# 抽查共享掛載:應只有核准過的唯讀來源,或沒有任何掛載
nemoclaw dev-order share status
# 一個沙盒一個專案:工作目錄下應只有一個專案
nemoclaw dev-order exec -- ls /sandbox/work
情境判定
✅ /sandbox/work/order-service 是唯一的專案,由 git clone 建立符合
❌ share mount 掛了 ~/projects,裡面有 5 個專案違反「一個沙盒一個專案」,也讓 Agent 能寫主機目錄
❌ find 找到 /sandbox/work/order-service/.env.local違反憑證檔規範;同時檢查它是否已進入 Git 歷史(13.5)

13.4 網路白名單申請與審查

flowchart LR
    A["申請人<br/>填寫申請單"] --> B["撰寫 preset YAML<br/>可請 AI 草擬"]
    B --> C["lint<br/>nemoclaw-policy-lint.py"]
    C -- ERROR --> B
    C -- 通過 --> D["政策審查者<br/>6.16 人工清單"]
    D -- 退回 --> B
    D -- 核准 --> E["合併到 presets/ repo<br/>PR+CODEOWNERS"]
    E --> F["套用<br/>policy add --dry-run 後套用"]
    F --> G["驗證<br/>V1~V6 拒絕測試"]
    G --> H["結案<br/>附驗證輸出"]

申請單欄位:

欄位說明
目的地精確主機名與連接埠
方法與路徑例如 GET /repository/maven-public/**
發起程式openshell term 回報的 binary
讀或寫寫入另需專案負責人核准
資料敏感度可能送出的資料類型
私有位址是否需要 --trusted-private-host
到期日預設與環境同步

13.5 API Key 與憑證管理

規範說明
來源一律由企業密碼庫取得;⛔ 不得使用個人帳號的 Key
範圍專案專屬、最小權限、有額度上限
輸入方式read -r -s 讀入環境變數,onboarding 後 unset(6.6);⛔ 不得貼在 Agent 對話、Prompt、文件中
保存只存在 OpenShell Gateway;⛔ 不得寫入 openclaw.json、.env、Git
輪替每 90 天,或人員異動、主機轉移、疑似外洩時
撤銷主機停用前在上游撤銷(12.8)
正式環境憑證⛔ 一律禁止進入任何沙盒或主機

範例與驗證:

❌ 壞例:在 Agent 對話中貼上「這是我的 key sk-proj-…,幫我測一下 API」。Key 會成為推理請求的一部分送到推理服務,也會留在 Agent 的對話紀錄裡。這把 Key 要當成已外洩,立刻在上游撤銷。

▶️ 驗證 1:主機上的設定檔與 shell 歷史沒有明文 Key(🖥️ Host;只印檔名、不印內容;🧪 樣式依你使用的供應商調整):

grep -rlE 'nvapi-[A-Za-z0-9_-]{20,}|sk-[A-Za-z0-9_-]{20,}' ~/.nemoclaw ~/.bash_history ~/.zsh_history 2>/dev/null \
  && echo "❌ 發現疑似明文 Key(只列檔名)" || echo "✅ 未發現"

▶️ 驗證 2:沙盒內拿到的是 placeholder,不是真實值(🧪)。做法是不印出值,只比對雜湊的前 8 碼:

# 📦 透過 exec 在沙盒內執行:列出名稱含 KEY/TOKEN 的變數,只印長度與雜湊前 8 碼
nemoclaw dev-order exec -- sh -c 'for v in $(env | cut -d= -f1 | grep -iE "key|token"); do
  printf "%s len=%s sha=%s\n" "$v" "$(printenv "$v" | wc -c)" "$(printenv "$v" | sha256sum | cut -c1-8)"; done'
# 🖥️ Host:用同樣算法算真實 Key 的雜湊(Key 由 read -r -s 讀入,算完立刻 unset)
read -r -s REAL_KEY; printf '%s\n' "$REAL_KEY" | sha256sum | cut -c1-8; unset REAL_KEY

判讀方式:兩邊雜湊不同才是正確的,代表沙盒內只有 placeholder。雜湊相同,代表真實 Key 進了沙盒,立即依 6.6 輪替並通報資安。

▶️ 驗證 3:CI 擋下進入 Git 的 Key,以 gitleaks 為例:gitleaks detect --source . --redact,結束碼非 0 就擋下 PR。

13.6 原始碼、個資、客戶資料與機密資料處理

資料分級例子可放進沙盒可送外部推理服務可送企業私有模型
公開開源程式碼、公開文件✅✅✅
內部一般內部系統原始碼、設計文件✅需專案負責人核准✅
機密核心系統原始碼、資安設定、架構細節需資安核准⛔需資安核准
極機密/受法規保護客戶個資、帳務資料、正式環境憑證⛔⛔⛔

⚠️ 警告:明確禁止將生產環境憑證、客戶個資、未授權的原始資料或機密文件提供給外部模型服務。Prompt 的內容、Agent 讀進來的檔案、工具回傳的結果,全部都會成為送給推理服務的資料。

分級練習(答案在表格右欄,先遮住自己判斷):

情境判定理由
把開源的 Spring PetClinic 放進沙盒,用 NVIDIA Endpoints 分析✅ 可以公開等級
把核心帳務系統的原始碼放進沙盒,用外部託管模型做逆向⛔ 不可以機密等級禁止送外部推理;改用企業私有模型並經資安核准
從正式環境匯出 100 筆客戶資料當測試資料⛔ 不可以受法規保護的資料不得進沙盒;改用合成資料
內部系統原始碼,但其中的測試資料檔有真實身分證號⛔ 先去敏檔案分級以「最高等級的內容」為準(8.9)

▶️ 放進沙盒前的快篩(🖥️ Host;只計數、不印內容;📖 標準 grep)。以台灣身分證字號與 Email 樣式為例:

grep -rEoh '\b[A-Z][12][0-9]{8}\b' ./src-copy | wc -l      # 疑似身分證字號筆數
grep -rEoh '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' ./src-copy | sort -u | wc -l   # 不重複 Email 數

數字大於 0 不一定違規(測試碼裡可能是假資料),但每一筆都要有人確認來源。快篩只能找出「有樣式的資料」,客戶名稱、地址、帳號這類沒有固定樣式的資料,仍要靠 8.9 的人工去敏流程。

13.7 AI 產出程式碼的審查責任

原則說明
作者責任提交 PR 的人對 AI 產出負完全責任,等同自己寫的程式
完整閱讀Reviewer 必須看完整 diff,不能只看交付報告或 AI 的自我 review
小 PR單一 PR 建議不超過 400 行有效變更;超過要拆
可追溯Commit trailer 標示 AI 參與(10.3)
不降標準AI 產出的程式碼適用同一套品質與安全門檻

PR 描述範例:

✅ 好例❌ 壞例
「新增 UC-01 下單 API。AI 參與:dcode 產生 Service 與測試初稿,我改寫了庫存檢查的並行處理。驗證:mvn verify 綠燈、check-change-report.py 0 項、手動測了庫存不足的情境。風險:OrderRepository 新增一個查詢,請 DBA 看索引。」「依 AI 產出完成需求,測試皆通過。」
說清楚 AI 做了什麼、人改了什麼、用什麼證據驗證、哪裡需要別人注意沒有範圍、沒有證據、沒有風險;Reviewer 無從判斷

Reviewer 的機械檢查(🔧 CI 或本機;📖 標準 Git 指令):

git diff --shortstat origin/main...HEAD                         # 有效變更是否 ≤ 400 行
git log --format=%B origin/main..HEAD | grep -c '^AI-Assisted:'  # AI 參與的 commit 是否都有 trailer(10.3)
python3 check-change-report.py .ai-reports/$(git branch --show-current).md origin/main   # 報告是否誠實(7.10)
python3 check-test-weakening.py origin/main                      # 有沒有弱化測試(13.8)

⚠️ 警告:機械檢查全部通過,只代表「沒有明顯的作弊跡象」,不代表程式正確。Reviewer 仍然要讀完整個 diff。

13.8 測試與品質驗證要求

  • 每個 AI 參與的 PR 必須通過第 10.4 節的 CI 關卡;不接受「本機已測」或「Agent 已測」。
  • 新增或修改的商業規則必須有對應的單元測試;邊界值必測。
  • 禁止停用、刪除既有測試或降低斷言;確需調整時另開 PR 並說明理由。
  • 交付報告必須通過 check-change-report.py。

「不得停用、刪除測試或降低斷言」這條規範要能被自動檢查,否則只靠 Reviewer 的眼睛。check-test-weakening.py(🏢 本手冊自行撰寫;✅ 已實測;完整原始碼見 18.10.5)比對基準分支與工作目錄,找出五種弱化測試的跡象:

代號抓什麼
DELETED測試檔被刪除,或被改名到非測試路徑
FEWERTESTS測試檔中的測試案例(@Test、it(、test()變少
FEWERASSERT斷言(assert*、assertThat、expect(、verify()變少
DISABLED新增 @Disabled、@Ignore、.skip(、xit(、.only(
SKIPBUILDpom.xml、build.gradle、package.json 等新增 skipTests、testFailureIgnore、passWithNoTests

好例:只新增一個測試案例(✅ 實際輸出):

$ python3 check-test-weakening.py base
檢查 1 個變更檔案,發現 0 項
exit=0

❌ 壞例:Agent 為了讓 CI 變綠,刪掉一個測試檔、拿掉一個測試案例與兩個斷言、加上 @Disabled 與 it.skip,還在 pom.xml 加了 skipTests(✅ 實際輸出):

$ python3 check-test-weakening.py base
SKIPBUILD   pom.xml: 略過測試設定 0 → 1
DELETED     src/test/java/demo/LegacyTest.java: 測試檔被刪除
FEWERTESTS  src/test/java/demo/OrderServiceTest.java: 測試案例 2 → 1
FEWERASSERT src/test/java/demo/OrderServiceTest.java: 斷言 3 → 1
DISABLED    src/test/java/demo/OrderServiceTest.java: 停用標記 0 → 1
FEWERTESTS  web/src/order.spec.ts: 測試案例 2 → 1
DISABLED    web/src/order.spec.ts: 停用標記 0 → 1
檢查 4 個變更檔案,發現 7 項
exit=1

放進 10.4 的 CI 關卡(🔧 CI;GitHub Actions 片段,需要 fetch-depth: 0 才拿得到基準分支):

      - name: 測試弱化檢查
        run: python3 tools/check-test-weakening.py "origin/${{ github.base_ref }}"

處理原則:工具回報的是「需要人看」的清單,不是自動定罪。重構時合併兩個測試案例,也會出現 FEWERTESTS;這種情況由 Reviewer 在 PR 留言說明理由後放行。但 SKIPBUILD 一律退回。

13.9 日誌、稽核與事件通報

事件通報對象時限(🏢 建議)保全證據
憑證疑似外洩資安立即logs、debug 包、時間點
未知目的地的連線嘗試異常增加資安、平台管理者當日logs --since、openshell term 截圖
AI 產出含惡意或可疑程式碼資安、專案負責人當日PR、交付報告、對話紀錄
沙盒內出現主機檔案或非預期掛載資安立即4.10 輸出
推理費用異常專案負責人當日供應商報表

處理流程見 6.10。NemoClaw 自身的安全漏洞依 SECURITY.md 的私密管道回報,⛔ 不開公開 Issue。

證據保全範例(🖥️ Host;🧪 未實機執行)。重點是先保全、再處理,並且記下雜湊值,證明證據事後沒被改過:

case_id=INC-$(date +%Y%m%d-%H%M)
mkdir -p ~/evidence/$case_id && cd ~/evidence/$case_id
date -Iseconds > collected-at.txt
nemoclaw dev-order logs --since 24h > sandbox.log 2>&1
nemoclaw dev-order status --json > status.json 2>&1
nemoclaw dev-order policy list > policy.txt 2>&1
nemoclaw debug --sandbox dev-order --output ./debug.tgz
sha256sum * > SHA256SUMS            # 移交資安時一併附上

通報內容範例:

欄位✅ 好例❌ 壞例
事件dev-order 沙盒 10:05~10:20 對 paste.example.net 有 37 次被拒連線沙盒怪怪的
影響未成功連出;工作副本含內部原始碼(內部等級)不知道
已採取動作10:25 stop 沙盒;證據在 ~/evidence/INC-20261027-1025,附 SHA256SUMS重開了,現在好了

❌ 最常見的錯誤是先 destroy 或 rebuild「讓它恢復正常」。這兩個動作都會毀掉證據。

13.10 版本管理、更新與停用程序

項目規範
版本基準平台管理者公告「核准版本」;主機只能安裝核准版本
更新依 12.4 演練、12.5 程序;個人不得自行升級
例外安全修補可加速,但仍需 12.9 驗收
停用依 12.8;憑證撤銷是必要步驟
逾期環境到期未續約,平台管理者通知後停用

核准版本公告範例(🏢;放在平台管理者的公告頁或 presets repo 的 APPROVED.md):

NemoClaw 核准版本:v0.0.139(a08ae7a)/OpenShell 0.0.116
核准日期:2026-10-27 下次檢視:2026-11-10 或新安全公告發布時
安裝指令:NEMOCLAW_INSTALL_REF= NEMOCLAW_INSTALL_TAG=v0.0.139 bash nemoclaw.sh(先依 4.3 審查)
已知限制:管線輸入可能卡住(5.6);OpenShell 0.1.5 遷移尚未發布(12.11)
安全下限:check-security-floor.sh 須通過(6.17.1)

▶️ 驗證主機符合公告:11.2 的 nemoclaw-daily.sh(版本)加上 6.17.1 的 check-security-floor.sh(安全下限),兩者結束碼都要是 0。

13.11 允許/禁止/需經核准的行為

類別行為
✅ 允許在核准主機上以核准版本建立 Restricted 層沙盒
✅ 允許使用已核准的標準 preset
✅ 允許以合成資料或公開資料進行開發與測試
✅ 允許讓 Agent 草擬文件、程式、測試,並提交到 ai/* 分支
✅ 允許以 --host-mount 唯讀掛入去敏後的原始碼快照進行逆向工程
✅ 允許使用 status、logs、doctor、debug 等唯讀診斷
⛔ 禁止將生產環境憑證、客戶個資、未授權原始資料或機密文件提供給外部模型服務
⛔ 禁止使用 Personal 或 Open 政策層級
⛔ 禁止在 openshell term 使用「全部核准」(A)或核准未申請的目的地
⛔ 禁止單獨升級 OpenShell、在沙盒內就地更新 Agent
⛔ 禁止以 docker exec 操作沙盒;繞過 NemoClaw 受管入口啟動 Agent
⛔ 禁止把 API Key 貼進對話、Prompt、文件或寫入沙盒設定檔
⛔ 禁止多人共用同一台 NemoClaw 主機
⛔ 禁止沙盒有任何通往正式環境的網路路徑
⛔ 禁止讓 Agent 修改 CI 設定、政策 preset、AGENTS.md 後未經 CODEOWNERS 審查即合併
⛔ 禁止啟用訊息通道(Slack、Discord、Telegram、WhatsApp 等)與 Dashboard 對外綁定
⚠️ 需經核准新增網路目的地(13.4)
⚠️ 需經核准任何寫入類 preset(例如 corp-git-order-write)
⚠️ 需經核准把「內部」等級資料送外部推理服務(13.6)
⚠️ 需經核准使用自訂映像檔(--from)
⚠️ 需經核准開啟 Deep Agents 的 --dcode-auto-approval thread-opt-in
⚠️ 需經核准使用 share mount 雙向掛載
⚠️ 需經核准開啟 NEMOCLAW_EXPERIMENTAL=1 的實驗功能
⚠️ 需經核准託管 MCP Server 的新增

13.12 技術防護、行政規範與人工審查的分層

風險技術防護(NemoClaw/OpenShell/CI)行政規範(本章)人工審查
資料外洩到網際網路Deny-by-default、preset、SSRF 防護白名單申請、資料分級preset 審查、openshell term 核准
憑證外洩Gateway 保管、placeholder、rebuild 憑證掃描憑證管理規範交付報告 FORBIDDEN 檢查
誤改主機檔案沙盒檔案系統、唯讀掛載目錄規範—
惡意依賴Restricted 層、內部代理庫依賴新增需核准SCA 結果審查
錯誤或惡意程式碼CI、ArchUnit、SAST審查責任Code Review
報告不實check-change-report.py交付報告格式Reviewer 看完整 diff
版本漂移版本範圍檢查(max_openshell_version)核准版本盤點表
濫用推理預算—(NemoClaw 不控管)額度規範每週費用檢視

用這張表做稽核的範例:抽一列風險,三層各提出一個證據。只要缺一層,就要說明為什麼可以接受。

風險:憑證外洩證據
技術防護13.5 驗證 2 的輸出:沙盒內的雜湊與真實 Key 不同
行政規範同仁簽署的使用規範,以及 13.2 申請檢查表中的憑證管理項目
人工審查最近 10 個 AI 參與的 PR 中,check-change-report.py 沒有出現 FORBIDDEN 的紀錄

13.13 本章實務案例與注意事項

案例:專案負責人想讓外包廠商的工程師也用部門的 NemoClaw 主機。

評估:官方不支援多使用者共用主機,也沒有 RBAC;外包人員能執行 nemoclaw 就能改政策、看到所有沙盒的日誌與對話。

建議:由外包廠商依本章規範自行申請獨立主機(或企業提供獨立 VM),資料分級與憑證完全分開;不得共用主機或 Gateway。

注意事項:

  • 規範要隨 NemoClaw 版本調整;每次核准新版本時,平台管理者檢查 13.11 是否需要更新。
  • 「需經核准」的項目要有到期日;核准不是永久的。
  • 規範的有效性要量測(第 15 章),而不是只看簽署率。

第14章 企業共用平台建議架構

本章提出適用大型企業與金融業的 NemoClaw 試行架構(🏢 全章為本手冊的建議設計,不是 NVIDIA 官方架構)。設計前提來自官方的產品邊界:單一主機、單一受信任操作者、無 RBAC、無多租戶、無集中管理、無 SLA。因此「共用平台」的意思是共用標準與周邊服務,不是共用 NemoClaw 主機。

14.1 設計原則

原則對應的官方限制設計
一人一主機不支援多使用者主機每位使用者一台 VM(VDI 或開發用 VM 池)
一專案一沙盒沙盒以名稱隔離、同主機共用 Gateway不同專案用不同沙盒;不同敏感等級用不同主機
共用的是標準無集中管理標準 VM 映像、標準 preset repo、版本基準、盤點腳本
只通非正式環境alpha、無 SLA網路區段與正式環境完全隔離
周邊服務做治理無 SIEM、無成本控管企業 AI Gateway、日誌平台、密碼庫

每條原則的驗證方式(🖥️ Host;📖 標準 Linux 指令):

原則▶️ 驗證指令通過標準
一人一主機getent group docker只列出這台 VM 的申請人一個帳號
一專案一沙盒nemoclaw list 對照專案登記表每個沙盒名稱都對得到一個已登記的專案
共用的是標準nemoclaw --version 與核准公告比對(13.10)版本一致
只通非正式環境14.8 的連線測試到正式網段的連線全部失敗

14.2 企業部署架構圖

flowchart TB
    subgraph USERZ["使用者區"]
        U1["開發者筆電<br/>瀏覽器、SSH"]
    end
    subgraph DEVZ["AI 開發隔離區(非正式網段)"]
        direction TB
        subgraph VM1["個人 VM:dev-host-07(開發者 A)"]
            N1["NemoClaw v0.0.139<br/>OpenShell 0.0.116"]
            S1["沙盒 dev-order"]
            S2["沙盒 re-legacy"]
        end
        subgraph VM2["個人 VM:dev-host-08(開發者 B)"]
            N2["NemoClaw"]
            S3["沙盒 up-billing"]
        end
        AGENTLOG["日誌轉送代理<br/>logs 定時匯出"]
    end
    subgraph SVCZ["共用服務區"]
        GIT["內部 Git<br/>ai/* 分支權限"]
        NEXUS["Nexus/Artifactory<br/>代理庫+弱點掃描"]
        AIGW["企業 AI Gateway<br/>私有模型、額度、稽核"]
        CI["CI/CD Runner<br/>建置、測試、掃描"]
        VAULT["密碼庫<br/>API Key、Token"]
        SIEM["日誌平台/SIEM"]
        PRESET["presets repo<br/>標準政策與版本基準"]
    end
    subgraph EXTZ["外部(經企業 Proxy)"]
        EXTLLM["外部推理服務<br/>需核准"]
        GHCR["ghcr.io、github.com<br/>安裝與映像檔"]
    end
    PROD["正式環境<br/>⛔ 無任何路徑"]
    U1 -->|"SSH"| VM1
    U1 -->|"SSH"| VM2
    S1 -->|"corp-git preset"| GIT
    S1 -->|"corp-maven preset"| NEXUS
    S1 -->|"推理"| AIGW
    S3 -->|"推理"| AIGW
    AIGW -.->|"核准後"| EXTLLM
    N1 -.->|"安裝與升級"| GHCR
    GIT --> CI
    CI --> NEXUS
    AGENTLOG --> SIEM
    VAULT -.->|"操作者取用"| N1
    PRESET -.->|"標準 preset"| N1
    DEVZ -.-x PROD

14.3 個人開發沙盒與共用測試環境的隔離

項目個人開發主機共用測試環境
使用者一人多人(但 NemoClaw 不在此)
NemoClaw有沒有
用途Agent 開發、逆向、升級部署 CI 產物、UAT、整合測試
資料合成資料遮罩後測試資料
連線只到共用服務區由 CI 部署,不由沙盒直連

✅ 建議:沙盒不直連共用測試環境。Agent 的產出經 Git → CI → 部署到測試環境;測試結果回到 PR。這樣 Agent 永遠只碰得到「程式碼」,碰不到「環境」。

▶️ 驗證「沙盒不直連測試環境」(🖥️ Host 透過 exec 在沙盒內執行;🧪 主機名稱請換成貴單位實際的測試環境):

nemoclaw dev-order exec -- sh -c \
  'curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 https://uat-api.corp.example/health; echo "exit=$?"'

通過標準:連線被沙盒代理拒絕(4.10 的拒絕樣態),或 curl 以非 0 結束碼失敗。如果得到 200,代表有某個 preset 放行了測試環境,要用 policy list 找出是哪一個。

14.4 不同專案的檔案、網路與憑證權限分離

隔離面做法
檔案一專案一沙盒;工作副本只在該沙盒
網路preset 綁定 repo 路徑(/scm/<project>/<repo>.git/…);不同專案不共用寫入 preset
憑證Git Token 一專案一個、只授權該 repo;推理 Key 依專案分開以利成本歸屬
敏感等級機密專案用獨立主機與私有模型;不與內部等級專案共用主機

⚠️ 警告:同一主機上的沙盒共用同一個 OpenShell Gateway 與憑證庫。官方說明 nemoclaw credentials add 註冊的 Provider 是 Gateway 範圍,會附掛到之後建立或重建的每一個沙盒;credentials reset 也會從所有使用中的沙盒卸除。不同敏感等級的專案若共用主機,憑證邊界就無法分開。

▶️ 驗證 Git Token 只能動自己的 repo 與 ai/* 分支(🔧 在沙盒外,用該 Token 執行;🧪 依 Git Server 的權限模型而定):

# 預期:讀自己的 repo 成功
git ls-remote https://git.corp.example/scm/order/order-service.git >/dev/null && echo "OK 可讀自己的 repo"
# 預期:讀別的專案失敗(403/404)
git ls-remote https://git.corp.example/scm/pay/payment-core.git >/dev/null 2>&1 || echo "OK 讀不到別的專案"
# 預期:推送到 main 被拒
git push --dry-run origin HEAD:main 2>&1 | grep -qiE 'denied|forbidden|protected' && echo "OK main 受保護"

❌ 壞例:為了方便,整個部門共用一把有「所有 repo 寫入權」的 Token。只要任何一個沙盒被 Prompt Injection,Agent 就能推送到所有專案。

14.5 私有模型服務與外部託管推理服務的選擇

面向企業私有模型(vLLM/NIM/企業 AI Gateway)外部託管(NVIDIA Endpoints、OpenAI、Anthropic 等)
資料外送不出企業送到供應商
NemoClaw 支援「Other OpenAI-compatible endpoint」(Tested with limitations)或本地 vLLM/NIMTested
能力取決於自建模型通常較強
成本GPU 資本支出與維運依 token 計費
工具呼叫相容性需實測(官方 Troubleshooting 有「Tool calls appear as assistant text」)官方驗證
稽核企業 AI Gateway 可記錄每次請求依供應商
適用資料等級內部、機密(經核准)公開、內部(經核准)

✅ 建議:所有推理流量經企業 AI Gateway(統一入口、額度、稽核、模型路由),NemoClaw 只設定一個「OpenAI 相容端點」指向它。這也補上 NemoClaw 沒有成本控管與集中稽核的缺口。

14.6 企業 Proxy、TLS、DNS 與防火牆整合

項目設定點說明
主機出口主機的 HTTP(S)_PROXYNemoClaw 會把 localhost、inference.local 等加入 NO_PROXY
沙盒出口 ProxyNEMOCLAW_PROXY_HOST/PORT(建置期)預設 10.200.0.1:3128(OpenShell 注入)
TLS 攔截NEMOCLAW_CORPORATE_CA_BUNDLE只接受 CA 憑證,拒絕整包 OS 信任庫
DNSDocker daemon 的 dns 設定企業封鎖 UDP 53 時必要(11.3)
防火牆VM 網段 ACL只允許到共用服務區與核准的外部端點;明確拒絕正式網段
UFW 自動修復NEMOCLAW_AUTO_FIX_FIREWALL=1⛔ 企業主機由網管管理防火牆,不開啟

14.7 稽核、日誌保存與異常通報

NemoClaw 官方把集中稽核與 SIEM 整合列為 Manual or admin-only。🏢 建議的補強:

資料收集方式頻率偵測規則範例
沙盒日誌每台 VM 以 cron 執行 nemoclaw <名稱> logs --since 1h,送日誌平台每小時單一沙盒每小時拒絕 > 50 次
版本盤點12.2 腳本每日版本與核准基準不符
政策漂移policy list 與 presets repo 比對每日出現未在 repo 中的 preset
推理流量企業 AI Gateway即時單一 Key 的 token 用量超過基準 3 倍
Git 推送Git Server 稽核即時AI Token 推送到 ai/* 以外的分支(應被權限擋下)

排程範例(🏢;🧪 未實機執行)。cron 的 PATH 很短,一定要寫絕對路徑:

command -v nemoclaw    # 先查出絕對路徑,例如 /home/dev/.local/bin/nemoclaw
# crontab -e
0 * * * * NEMOCLAW_DISABLE_TELEMETRY=1 /home/dev/.local/bin/nemoclaw dev-order logs --since 1h >> /var/log/nemoclaw/dev-order.log 2>&1

偵測規則怎麼驗證:規則寫好後,一定要故意觸發一次,確認告警真的會發出來。沒有被觸發測試過的規則,等於沒有規則。

  1. 在沙盒內對一個未放行的網址發出請求(例如 4.10 的拒絕測試),重複 60 次,超過「每小時 50 次」的門檻。
  2. 等下一次排程把日誌送到日誌平台。
  3. 確認日誌平台出現告警,並把告警截圖附在 14.12 的風險接受文件中。
  4. 如果沒有告警:先看日誌平台裡被拒那一行的實際格式,再修正規則的比對條件(日誌格式不是穩定介面,標 🧪 就是這個原因)。

14.8 開發、測試與正式環境的權限分離

權限開發(NemoClaw 主機)測試正式
AI Agent 可存取工作副本、內部 Git(限 repo)、代理庫、AI Gateway⛔⛔
部署權限⛔CI 服務帳號變更管理流程
資料合成遮罩真實
憑證開發用、低權限CI 密碼庫正式密碼庫

▶️ 驗證網路層的分離(🖥️ Host,在 NemoClaw VM 上沙盒外執行;這一層靠的是企業防火牆,不是 NemoClaw):

for t in prod-db.corp.example:1521 prod-api.corp.example:443; do
  timeout 5 bash -c "</dev/tcp/${t%:*}/${t#*:}" 2>/dev/null && echo "❌ 連得到 $t" || echo "✅ 連不到 $t"
done

這個測試要在主機上做,原因是:沙盒內連不到正式環境,可能只是政策擋住了;主機連不到,才證明網段真的隔離。兩層都要通過。

14.9 共用設定範本與政策版本管理

presets repo 結構建議:

nemoclaw-platform/
├── VERSION-BASELINE.md          核准的 NemoClaw/OpenShell 版本
├── presets/
│   ├── corp-maven-readonly.yaml
│   ├── corp-npm-readonly.yaml
│   ├── corp-ai-gateway.yaml
│   └── projects/
│       └── order-service/
│           ├── corp-git-order-read.yaml
│           └── corp-git-order-write.yaml
├── tools/
│   ├── nemoclaw-policy-lint.py
│   ├── check-change-report.py
│   ├── check-layering.py
│   ├── check-evidence.py
│   ├── preflight-nemoclaw.sh
│   └── nemoclaw-inventory.sh
├── templates/
│   ├── AGENTS.md
│   └── pull_request_template.md
└── .github/
    ├── CODEOWNERS               presets/ 由政策審查者審查
    └── workflows/lint.yml       每個 PR 跑 nemoclaw-policy-lint.py

版本規則:preset 每次變更打 tag(例如 presets-2026.10.27);主機盤點表記錄套用的 tag;NemoClaw 版本基準更新時,所有 preset 要在測試主機重跑 6.12 驗證。

14.10 資源成本、模型使用量與維運責任

成本項目量測責任
VM(CPU、記憶體、磁碟)虛擬化平台報表平台管理者
GPU(若自建模型)GPU 使用率AI 平台團隊
外部推理費用AI Gateway 或供應商報表,依專案 Key 歸屬專案負責人
維運人力升級、事件、支援工時平台管理者
教育訓練時數各部門

推理成本估算範例(🏢;以下單價與用量都是虛構的教學數字,實際請以供應商報價與 AI Gateway 的報表為準):

項目數值
每個開發任務的平均輸入 token1,200,000(Agent 反覆讀檔,輸入遠大於輸出)
每個開發任務的平均輸出 token60,000
假設單價輸入每百萬 token 3 元、輸出每百萬 token 15 元
每任務成本1.2 × 3 + 0.06 × 15 = 4.5 元
每人每月 60 個任務 × 20 人4.5 × 60 × 20 = 5,400 元/月

審查這類估算時要問三件事:(1) token 數是實測值還是猜的?(以第一階段的 AI Gateway 數據為準)(2) 有沒有算到重試與失敗的任務?(3) 單價是不是最新報價?

14.11 分階段導入計畫

flowchart LR
    P1["第一階段<br/>個人 PoC<br/>2~3 位資深同仁<br/>合成資料"] --> G1{"安全驗收<br/>4.10、6.12"}
    G1 -- 通過 --> P2["第二階段<br/>隔離測試環境試辦<br/>標準 VM、preset repo、日誌轉送"]
    G1 -- 不通過 --> P1
    P2 --> G2{"維運演練<br/>升級、回復、事件"}
    G2 -- 通過 --> P3["第三階段<br/>選定專案試行<br/>1~2 個內部等級專案"]
    P3 --> P4["第四階段<br/>安全與效益評估<br/>第 15 章指標"]
    P4 --> G3{"導入決策<br/>風險接受"}
    G3 -- 核准 --> P5["第五階段<br/>依核准結果擴大<br/>仍限非正式環境"]
    G3 -- 不核准 --> X["暫停或調整範圍"]
階段目標範圍退出條件
1. 個人 PoC確認安裝、控制有效性、基本開發流程2~3 人、合成資料、各自 VM4.10 與 6.12 全通過;完成第 16 章三個演練
2. 隔離試辦建立標準與周邊服務標準 VM 映像、presets repo、AI Gateway、日誌轉送完成一次升級演練與一次事件演練
3. 專案試行在真實(非正式、內部等級)專案驗證1~2 個專案、5~10 人連續 4 週收集第 15 章指標
4. 評估安全與效益資安、架構、專案代表書面評估報告
5. 擴大依核准範圍依決策每季重新評估;NemoClaw 脫離 alpha 前不進正式環境工作負載

14.12 Alpha 階段的風險接受程序

步驟內容
1. 風險說明列出官方限制(1.5)、本企業的補強控制(13.12)、剩餘風險
2. 範圍限定非正式環境、資料等級上限、人數上限、期限
3. 簽核專案負責人、資安主管、資訊主管
4. 監控14.7 的偵測規則
5. 重新評估每次 NemoClaw 大版本或每季
6. 中止條件重大事件、官方停止維護、出現未修補的高風險漏洞

風險接受單範例:

欄位✅ 好例❌ 壞例
範圍訂單組 3 人、3 台 VM、資料等級上限「內部」、只開 Restricted 層研發處
期限2026-11-01~2027-01-31,到期自動失效無
補強控制13.12 全表;14.7 偵測規則已觸發測試(附截圖)依公司規範
剩餘風險無 RBAC:VM 擁有者可自行改政策;以每日巡檢的政策比對(11.2)偵測無
中止條件任一憑證外洩事件;出現影響核准版本的 Critical 公告且 7 天內無法修補(6.17.2)發生重大事件時
簽核專案負責人、資安主管、資訊主管(三人)專案負責人

14.13 本章實務案例與注意事項

案例:金融業資訊處想用一台高規 GPU 伺服器讓 20 位同仁共用 NemoClaw。

評估:官方不支援多使用者主機、沒有 RBAC 與多租戶隔離、Provider 憑證是 Gateway 範圍。20 人共用等於 20 人共享同一組憑證、互相看得到沙盒與日誌。

建議架構:GPU 伺服器改當企業私有模型服務(vLLM 或 NIM,經企業 AI Gateway 對外),20 位同仁各自一台輕量 VM 跑 NemoClaw,推理統一指向 AI Gateway。這樣 GPU 被共用、NemoClaw 主機仍是一人一台。

注意事項:

  • 架構圖中的「正式環境無任何路徑」要以網段 ACL 實際驗證,而不是只畫在圖上。
  • 第五階段的「擴大」仍限非正式環境;是否允許處理更高等級資料,要等 NemoClaw 有正式版與企業驗證後重新評估。
  • 本章架構是試行建議,各企業需依自身網路、資安與法規調整。

第15章 效益衡量與導入決策

本章提供可量化的評估指標(🏢 全章為本手冊設計的方法)。原則:不憑空宣稱生產力提升百分比。所有數字都要有基準值、有取得方法、有適用限制;沒有基準值的指標,不能拿來比較。

15.1 衡量原則

原則說明
先有基準導入前用相同類型的任務量測「不用 AI」或「用既有工具」的數字
同類比較新開發、逆向、升級分開統計;不同規模的任務不混在一起平均
品質與速度一起看只看速度會鼓勵跳過審查;每個速度指標都配一個品質指標
安全指標獨立安全事件與政策誤阻擋不能被效益抵銷
樣本足夠第三階段至少 4 週、每類任務至少 10 件才下結論
記錄限制模型版本、Agent 版本、任務難度都會影響結果,要一併記錄

15.2 指標定義

指標定義計算方式基準值取得適用限制
需求分析與文件產製時間從原始需求到 SRS 經需求方簽核的工時Σ(人員實際投入工時),不含等待時間導入前 3~5 份同類 SRS 的工時紀錄需求複雜度差異大;以功能點或 UC 數正規化
逆向工程工時完成一個模組的盤點、呼叫鏈、商業規則、文件並通過人工確認的工時Σ 人員工時 ÷ 模組數(或 ÷ 千行程式)過去人工逆向的工時紀錄;沒有時以首個模組人工完成作基準程式碼品質、編碼、文件殘缺程度影響大
Framework 升級工時一次升級從盤點到驗收的工時Σ 人員工時(含 review 與修正)過去同類升級的工時依賴數量、測試覆蓋率影響大
測試覆蓋率變化導入後新增程式碼的行覆蓋率與分支覆蓋率CI 覆蓋率報告(JaCoCo、Vitest)導入前 3 個月同專案新增程式碼的覆蓋率覆蓋率高不代表斷言有效;搭配突變測試更佳
缺陷發現率每千行新增程式碼在 Code Review、CI、測試、UAT、上線後各階段發現的缺陷數缺陷數 ÷ KLOC,依階段分列導入前同專案的缺陷追蹤資料越早發現越好;上線後缺陷是最重要的負向指標
AI 產出審查退回率AI 參與的 PR 被退回(Request changes)的比例退回次數 ÷ AI 參與 PR 數同期人工 PR 的退回率退回率低可能代表審查變鬆,要搭配抽查
交付報告不實率check-change-report.py 回報 UNREPORTED/PHANTOM/TESTFAIL 的比例有問題的報告數 ÷ 報告總數無(新指標),以第一階段數據為基準反映 Agent 與 Prompt 品質
安全政策阻擋次數沙盒每日被拒絕的連線數logs 中的拒絕紀錄計數第一階段穩定後的每日中位數突然增加可能是攻擊或誘導,也可能是新需求
政策誤阻擋必要服務被擋、需要申請白名單的次數與等待時間白名單申請單數;從阻擋到開通的時間第二階段數據誤阻擋多代表標準 preset 不足;不能因此放寬層級
Agent 任務完成率任務在不需人工大幅重寫下被接受的比例被合併的任務數 ÷ 指派任務數無;以第一階段為基準任務切割大小影響很大
模型推理成本每個任務、每個 PR 的推理費用AI Gateway 或供應商報表 ÷ 任務數第一階段模型價格變動要正規化
平均處理時間從指派到交付報告的時間時間戳差第一階段含等待人工核准的時間要分開
升級失敗率NemoClaw 升級需要回復或大量手動修復的比例失敗次數 ÷ 升級次數第二階段演練樣本少時以個案檢討為主
復原時間從發現故障到 4.10 驗收重新通過的時間時間戳差第二階段演練—

15.3 資料收集方法

資料來源自動化程度
工時工時系統,任務單加上「AI 參與」標籤半自動
PR 與審查Git Server API(PR、review 狀態、commit trailer)自動
CI 結果、覆蓋率、掃描CI artifact自動
交付報告檢查結果CI 中 check-change-report.py 的輸出自動
拒絕紀錄14.7 的日誌轉送自動
推理費用AI Gateway自動
缺陷缺陷追蹤系統,加註發現階段與是否為 AI 參與的程式半自動

15.4 導入決策門檻

第四階段的決策建議以「必要條件+效益條件」兩段判斷:

類型條件不符時
必要(安全)試行期間無憑證外洩、無資料外送事件不擴大
必要(安全)4.10、6.12 驗收在每次升級後都通過不擴大
必要(品質)AI 參與程式碼的上線後缺陷率不高於基準不擴大
必要(治理)交付報告不實率呈下降趨勢且低於 10%改善 Prompt 與流程後再評估
效益至少一類任務(新開發、逆向、升級)的工時中位數低於基準,且品質指標不變差縮小範圍到有效的任務類型
成本推理+維運成本低於節省的工時成本調整模型或範圍

決策計算範例(🏢;以下為虛構的教學數字):

指標基準試行 8 週是否達標
憑證外洩、資料外送事件—0✅ 必要條件
升級後 4.10/6.12 驗收—2 次升級都通過✅ 必要條件
上線後缺陷率(每 KLOC)0.80.7✅ 必要條件
交付報告不實率—第 1~4 週 22%,第 5~8 週 8%✅ 下降且 < 10%
新開發任務工時中位數16 小時(n=12)11 小時(n=14)✅ 效益
逆向工程工時中位數40 小時(n=3)38 小時(n=4)⚠️ 樣本太少,不下結論
每月推理+維運成本—5,400+(0.2 人月)與節省工時比較

結論寫法:「新開發任務達到擴大條件;逆向工程樣本不足,延長試行 4 週再評估;不擴大到機密等級專案。」❌ 錯誤寫法是「整體效率提升 31%」:這個數字混了不同任務類型,而且沒有附上樣本數。

15.5 本章實務案例與注意事項

案例:試行 4 週後,專案經理報告「逆向工程工時下降 60%」。

審查:

  1. 基準是什麼?——是另一個規模小一半的模組的人工工時,基準不可比。
  2. 品質呢?——check-evidence.py 通過,但業務人員抽查 [事實] 的錯誤率是 18%(8.11 那類錯誤),修正工時沒算進去。
  3. 改善:以同一模組的另一半作人工基準;工時計入「人工確認與修正」;把抽查錯誤率列為品質指標。

注意事項:

  • 指標是用來改善流程的,不是用來評比個人;否則會鼓勵隱瞞問題。
  • 模型或 Agent 版本變更後,指標要重新建立基準。
  • 對外報告效益時,附上樣本數、期間、基準來源與限制。

第16章 實作演練與驗收

本章設計四個演練:演練 0 驗證安全控制(其他演練的前提),案例 A、B、C 分別對應新開發、逆向工程、Framework 升級。全部使用小型、可重現、合成資料的專案,⛔ 不得使用真實客戶資料或正式系統原始碼。每個案例都包含:實作目標、前置條件、操作步驟、Prompt、預期輸出、驗收標準、常見錯誤、安全檢查、人工審查點。

16.1 演練 0:安全控制驗證(必做)

項目內容
目標證明沙盒的檔案、網路、憑證控制在你的主機上真的有效
前置條件已依第 4 章建立 dev-order(Deep Agents、Restricted 層)
操作步驟1. 執行 4.10 的驗收腳本 2. 套用 6.11 的兩份唯讀 preset 3. 執行 6.12 的 V1~V6 4. 在 openshell term 觀察 V5 的待審請求並按 x 拒絕 5. logs --tail 50 截取拒絕紀錄
預期輸出4.10 表格全部符合;V1 成功、V2~V5 被拒;V6 看得到拒絕紀錄
驗收標準全部符合才可進行 A、B、C
常見錯誤選了 Balanced 層導致 pypi 等可通;忘了 Deep Agents 基準的 github 是 access: full
安全檢查檢查 6 的 NO-RAW-KEY
人工審查點政策審查者確認 preset 與驗證輸出

16.2 案例 A:新建 Web Application

項目內容
目標以 AI Agent 完成「建立訂單」功能:SRS → SDD → OpenAPI → 後端 → 前端 → 測試 → 交付
前置條件演練 0 通過;內部 Git 有空 repo demo/order-service(含 7.5 的 AGENTS.md 與 docs/spec/requirements-raw.md);CI 已設定 10.4 的關卡
合成需求「業務人員可建立訂單,輸入客戶編號與金額;金額需大於 0;金額超過 5 萬元需主管覆核;可依訂單編號查詢。」

操作步驟:

步驟動作位置
A1git clone repo 到 /sandbox/work/order-service📦(經 connect)
A2執行範本 P1(7.6.1)產生 SRS📦 dcode TUI
A3人工審查 SRS、回答 Q 清單、commit👤
A4執行 P2、P3 產生 SDD 與 OpenAPI📦
A5執行 P4:審查計畫 → 回覆「核准」→ 實作📦
A6執行 P6 補測試📦
A7本機跑 check-layering.py、check-change-report.py🖥️ 或 📦
A8套用寫入 preset(經核准)、push ai/uc-01-place-order🖥️ policy add;📦 git push
A9開 PR、等 CI👤/🔧
A10Code Review、合併;移除寫入 preset👤;🖥️ policy remove corp-git-order-write --yes

Prompt:使用 7.6.1~7.6.6,Prompt 中的需求以上述合成需求為準。

預期輸出:

docs/spec/SRS.md                    UC-01、UC-02;FR 約 6~10 條;Q 至少 2 條(例如「主管覆核流程」「金額幣別」)
docs/design/SDD.md                  元件圖、序列圖、DDL 草稿
docs/api/openapi.yaml               2 個路徑、problem+json 錯誤
src/main/java/com/example/order/... domain、application、adapter
src/test/java/...                   OrderTest(含 50000/50000.01 邊界)、ArchitectureTest
web/src/views/OrderCreate.vue       表單與錯誤顯示
.ai-reports/uc-01-place-order.md    交付報告

驗收標準:

  • CI 全綠:mvn verify(含 ArchUnit)、前端 lint 與 unit test。
  • check-change-report.py 0 問題;check-layering.py 0 違規。
  • 邊界測試包含 50000(不需覆核)與 50000.01(需覆核)。
  • OpenAPI 通過 linter;錯誤格式為 application/problem+json。
  • 沒有新增未核准的依賴(git diff origin/main -- pom.xml web/package.json)。
  • 前端沒有 v-html、金額以字串傳送。

常見錯誤:

錯誤如何發現
SRS 自行加入 SSO、權限角色7.6.1 的抽查
>= 50000 寫成覆核條件邊界測試
domain 放了 JPA annotationArchUnit domainIsFrameworkFree
報告宣稱跑過 mvn test,但沙盒沒有 JDK7.13 案例;以 CI 為準
寫入 preset 用完沒移除policy list

安全檢查:寫入 preset 只在 A8~A10 期間存在;推送的分支名稱符合 ai/*;.ai-reports 中沒有憑證或內部 URL 以外的敏感資料。

人工審查點:A3(SRS 簽核)、A5(計畫核准)、A10(Code Review 合併)。

16.3 案例 B:既有系統逆向工程

項目內容
目標對一個小型「舊系統」完成盤點、呼叫鏈、資料存取、商業規則、文件與回歸測試草稿
前置條件演練 0 通過;準備合成的舊系統原始碼(🏢 建議:以案例 A 產出的 order-service 為底,刻意加入 MS950 編碼的註解檔、一支 Stored Procedure 檔與一支排程批次,作為「舊系統」)
環境依 8.2 建立 re-legacy:--host-mount 唯讀、Restricted、排除 github 與 pypi

操作步驟:

步驟動作對應
B1主機端轉碼並建立凍結快照(8.8)🖥️
B2建立 re-legacy、驗證唯讀8.2
B3R1 盤點,主機端重算數字比對8.5.2
B4R2 呼叫鏈、R3 資料存取8.5.3、8.5.4
B5R4 商業規則 → check-evidence.py → 人工抽查8.5.5、8.6
B6R5 批次與介接、R6 圖8.5.6、8.5.7
B7R7 文件草稿8.5.8
B8R8/R9 行為案例與 characterization tests 草稿8.5.9
B9在測試環境實際執行行為案例,填寫差異報告8.10
B10download /sandbox/re-out/ 交付🖥️

預期輸出:inventory.md、modules.csv、call-graph.md、data-access.md、business-rules.md、integration.md、architecture.md、SRS.md、SDD.md、api.md、data-dictionary.md、behavior-cases.csv、tests/、regression-report.md。

驗收標準:

  • check-evidence.py business-rules.md 0 問題。
  • [事實] 抽查 ≥ 20%,金額相關 100%;錯誤率 < 5%。
  • 盤點數字與主機端 find/wc 結果一致。
  • 刻意埋入的 SP 與批次都有被找到(找不到要在文件寫「未找到」並列出搜尋過的關鍵字)。
  • /sandbox/src 內容未變(主機端比對快照的 sha256sum)。

常見錯誤:同一數值多處出現只取第一個(8.11);把註解內容當成 [事實];MS950 亂碼被猜成內容。

安全檢查:快照已跑過 gitleaks;沙盒 policy list 只剩推理相關項目;re-out 中的遮蔽字串(***)位置有列出。

人工審查點:B3(盤點正確性)、B5(商業規則抽查)、B9(行為比對判定)。

16.4 案例 C:Framework 升級

項目內容
目標把小型專案從舊版本升級,完成差異分析、計畫、分批修改、測試、報告與回復方案
前置條件演練 0 通過;🏢 準備一個「Spring Boot 2.7+Java 11+javax.*」的合成專案(可請 Agent 依 7.7 的領域模型產生,再由人確認可在舊版建置)
環境up-order 沙盒、Restricted+corp-maven-readonly+該 repo 的 Git 讀 preset

操作步驟:

步驟動作對應
C1舊版基線:tag pre-upgrade,CI 全綠截圖9.2 步驟 5
C2U1 差異分析 → 人工以 grep 驗證數字9.4.1
C3U2 計畫 → 架構師核准9.4.2
C4每批執行 U3 → PR → CI9.4.3
C5行為比對(9.5):至少 API 回應與錯誤格式9.5
C6升級報告與回復方案9.6
C7在測試環境演練回復到 pre-upgrade9.6

Prompt:9.4.1~9.4.3。

預期輸出:docs/upgrade/impact-analysis.md、docs/upgrade/plan.md、每批一個 PR、docs/upgrade/report.md。

驗收標準:

  • 每個批次 PR 的 CI 全綠;沒有停用測試。
  • grep -rn "import javax\." src/main/java 只剩 JDK 本身的 javax(例如 javax.crypto),不剩 Jakarta EE 相關的 javax.persistence、javax.validation、javax.servlet。
  • 每批 git diff --stat 的檔案數與計畫預估差異 < 20%,或有書面解釋。
  • 錯誤回應格式的差異已在報告中記錄與判定。
  • 回復演練成功。

常見錯誤:一次改完所有批次;混入格式化;註解掉找不到 Jakarta 版本的依賴(9.4.3 壞例);Agent 自行挑選依賴版本。

安全檢查:升級沙盒沒有公開 Maven Central 的出口(只走內部 Nexus);新依賴經 SCA 掃描。

人工審查點:C3(計畫核准)、C4(每批 Code Review)、C6(報告簽核)。

16.5 演練評分表

項目配分評分標準
演練 0 安全驗證20全部符合才給分;任一項不符 0 分
流程遵循(先計畫、等核准、小步)20依 commit 與對話紀錄
工具驗證(lint、check-*、CI)20全部通過
審查品質(找到刻意埋的錯誤)20講師在案例中埋 3 個錯誤,找到 1 個 6 分
文件與報告10交付報告、升級報告、差異報告完整
安全操作10無禁止行為(13.11)

16.6 本章實務案例與注意事項

案例:教育訓練中,一位學員在案例 A 的 A8 之後忘了移除寫入 preset,隔天繼續用同一沙盒做案例 C。

影響:案例 C 期間 Agent 仍能推送到 order-service repo。雖然 Git Server 的 ai/* 分支權限擋住了主線,但仍可能推送與案例 C 無關的分支。

改善:寫入 preset 的套用與移除寫進同一個腳本(套用、push、移除);每日巡檢(11.2)比對 policy list 與核准清單。

注意事項:

  • 演練用的合成專案放在獨立的 Git 群組,與真實專案隔離。
  • 講師可以預先在案例 B 的「舊系統」裡埋入矛盾的註解與重複的魔術數字,訓練學員抓出 Agent 的錯誤。
  • 演練產出(交付報告、工具輸出)可作為 15 章指標的第一批基準資料。

第17章 常見問題 FAQ

所有回答以 v0.0.139 官方文件與原始碼為準;有平台或版本限制的地方會註明。

17.1 NemoClaw 是否等於 OpenShell?

不是。NemoClaw 是參考堆疊(主機 CLI、Blueprint、Agent 整合層、preset、生命週期流程),OpenShell 是底層執行環境(Gateway、沙盒、L7 代理、政策執行、憑證保管)。NemoClaw 呼叫 OpenShell 的 API 與 CLI 來建立並設定沙盒。v0.0.139 綁定 OpenShell 0.0.116;你可以不用 NemoClaw 而直接用 OpenShell(「OpenShell 路徑」),但那就要自己準備映像檔、政策、Provider 與整合(1.2、1.9)。

🔍 自己驗證:nemoclaw --version 與 openshell --version 會印出兩個不同的版本號(v0.0.139 與 0.0.116),證明它們是兩套軟體。

17.2 NemoClaw 是否會自動保證 AI 產出程式碼安全?

不會。NemoClaw 控制的是 Agent「能碰什麼」(檔案、網路、程序、憑證),不判斷 Agent「寫了什麼」。程式碼的正確性與安全性要靠測試、SAST/SCA、ArchUnit 與人工 Code Review(第 7、10 章)。

🔍 自己驗證:拿一個 AI 產出的 PR,跑一次 check-change-report.py 與 check-test-weakening.py(7.10、13.8),看看沙盒之外還需要多少層檢查。

17.3 Agent 能否讀取沙盒以外的檔案?

在正常設定下不能:沙盒只看得到自己的檔案系統,系統路徑唯讀,Landlock 在核心層限制。例外:(1) 你以 --host-mount 掛入的主機目錄(唯讀);(2) 你以 share mount 建立的 SSHFS 雙向掛載;(3) 核心低於 5.13 或 macOS Docker VM 不支援 Landlock 時,OpenClaw 的 best_effort 會降級為只靠容器掛載(Deep Agents 是 strict,無法執行會直接啟動失敗)。用 4.10 的檢查 4 驗證。

🔍 自己驗證:nemoclaw <名稱> exec -- ls /home /mnt /Users 2>&1 不應看到主機的家目錄內容;nemoclaw <名稱> share status 應沒有非預期的掛載。

17.4 如何限制 Agent 的網路連線?

網路預設拒絕。onboarding 時選 Restricted 層,之後只用 nemoclaw <名稱> policy add 套用審查過的 preset(6.11~6.12);必要時以 policy exclude 移除不需要的基準項目(例如 Deep Agents 的 github)。一次性需求在 openshell term 核准單一規則。避免 openshell policy set 整份替換,除非 preset 無法表達(6.13)。

🔍 自己驗證:nemoclaw <名稱> policy list 看目前套用的 preset;在沙盒內 curl 一個未放行的網址,應被拒絕(4.10)。

17.5 能否使用私有模型或本地模型?

可以,但支援程度不同:企業私有的 OpenAI 相容端點走「Other OpenAI-compatible endpoint」(Tested with limitations,相容性需實測);本地 Ollama 為 Tested with limitations;本地 vLLM 在 DGX Spark 為 Tested、在一般 Linux GPU 主機需 NEMOCLAW_EXPERIMENTAL=1 或 NEMOCLAW_PROVIDER=install-vllm;本地 NIM 與 llama.cpp 為 Experimental。只支援 NVIDIA GPU。私有 IP 端點需以 NEMOCLAW_TRUSTED_PRIVATE_HOSTS 明確信任(3.7、14.5)。

🔍 自己驗證:nemoclaw <名稱> status --json | jq '{provider, model, recordedRoute, inferenceHealth}',確認 Provider 是你預期的私有端點,再照 4.9 送一次請求。

17.6 如何管理外部 API Key?

在 onboarding 前以 read -r -s 讀入環境變數,onboarding 完成後 unset;NemoClaw 把它註冊到 OpenShell Gateway,沙盒內只有 placeholder。用 nemoclaw credentials list 查看名稱、nemoclaw <名稱> status 實際驗證、以新值重跑 nemoclaw onboard --name <名稱> 輪替、nemoclaw credentials reset 移除。外洩時先在上游撤銷(6.6)。注意:Provider 憑證是 Gateway 範圍,同一主機的沙盒共用(14.4)。

🔍 自己驗證:照 13.5 的驗證 2,比對沙盒內變數的雜湊與真實 Key 的雜湊,兩者必須不同。

17.7 可以在 Windows 環境使用嗎?

可以,但只有「Windows 10(build 19041+)或 11 + WSL 2 + Docker Desktop(WSL backend)或合格的 rootless Podman」這條路,平台矩陣狀態是 Tested with limitations、沒有專屬 CI,官方以 x86-64 測試。所有 NemoClaw 指令都在 WSL 的 Ubuntu 裡執行,不在 PowerShell。原生 Windows 沒有安裝路徑;--host-mount 在 WSL 2 的 Docker 上可用(3.4)。

🔍 自己驗證:在 PowerShell 執行 wsl -l -v,Ubuntu 的 VERSION 要是 2;在 WSL 內執行 docker info 能成功,才繼續安裝(3.4)。

17.8 如何切換或更新 Agent?

官方規則是「每個沙盒名稱只對應一種 Agent」,同名 onboarding 另一種 Agent 會被拒絕(Sandbox 'X' already exists as OpenClaw)。要換 Agent,建議以新名稱 onboarding(例如 nemohermes onboard --name my-hermes),讓兩者並存;若一定要沿用名稱,官方做法是先 nemoclaw <名稱> destroy 再以新 Agent onboarding(⛔ destroy 不可復原,先 download 需要的檔案)。要更新 Agent 版本,升級 NemoClaw 後執行 nemoclaw <名稱> rebuild;⛔ 不要在沙盒內就地更新 Agent(例如 openclaw update),因為 Agent 版本綁在映像檔(12.1)。

🔍 自己驗證:nemoclaw list 確認沙盒名稱與 Agent 的對應;rebuild 後 nemoclaw <名稱> status 的 Agent 版本應是新版。

17.9 如何保留工作狀態?

日常的 stop/start/reconnect/Gateway 重啟,OpenShell 會保留 Agent 的原生 home 與工作區。rebuild 會封存、驗證並還原整棵原生 home。destroy 會刪除,無法復原。🏢 建議再加一層:工作副本推送到 Git,重要檔案以 nemoclaw <名稱> download 做獨立備份;升級前 nemoclaw backup-all(5.10、12.3)。憑證不在任何封存中。

🔍 自己驗證:用 12.7 的檔案指紋比對,確認 rebuild 前後工作區一致。

17.10 如何避免 AI 修改錯誤的程式碼?

多層防護:(1) 技術上,工作副本只在沙盒、Git 寫入 preset 只放行特定 repo、Token 只能推 ai/* 分支、主線受保護;逆向工程以唯讀掛載;(2) 流程上,Prompt 要求先計畫、等核准、小步修改;Deep Agents 互動模式逐次核准 shell 指令;(3) 驗證上,check-change-report.py 比對報告與 git diff、ArchUnit、CI 測試;(4) 最後由人 Code Review(7.6、10.3)。

🔍 自己驗證:用 AI Token 執行 git push --dry-run origin HEAD:main,應被拒絕(14.4)。

17.11 如何確認模型或 Agent 版本相容?

NemoClaw 版本:nemoclaw --version;OpenShell 範圍:nemoclaw-blueprint/blueprint.yaml 的 min_openshell_version/max_openshell_version;Agent 版本:nemoclaw <名稱> status 的 Agent 行(Deep Agents 的 manifest 期望 dcode 0.1.71);模型:onboarding 會驗證 Provider 與模型,nemoclaw <名稱> status 會實際送一次推理請求。平台與 Provider 的相容狀態以 Platform Support 頁為準(12.2)。

🔍 自己驗證:curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/v0.0.139/nemoclaw-blueprint/blueprint.yaml | grep openshell_version,比對 openshell --version。

17.12 Alpha 階段是否適合企業正式上線?

不適合處理正式環境工作負載或真實客戶資料。官方標示 alpha/Early preview、無 SLA、介面可能變動,且明列無 RBAC、無 SSO、無多租戶、無集中稽核、不支援離線。適合的是:在隔離的非正式環境、以合成或內部等級資料、經明確風險接受後試行(14.11、14.12)。

🔍 自己驗證:讀官方 Platform Support 頁頂端的 Stage/Label,再對照 14.12 的風險接受單是否已簽核。

17.13 lkg 與 latest 有什麼不同?

lkg(last known good)是管理者推進的標籤,官方安裝程式預設安裝它;研究當日 lkg 指向 v0.0.137,而官方文件站 latest 已是 v0.0.139。企業應一律以 NEMOCLAW_INSTALL_TAG=<版本> 指定版本,並清空 NEMOCLAW_INSTALL_REF(4.4)。

🔍 自己驗證:git ls-remote https://github.com/NVIDIA/NemoClaw.git 'refs/tags/lkg^{}' 'refs/tags/v0.0.139^{}',兩行的 commit 不同,就代表 lkg 不是最新版(12.11 有研究日的輸出)。

17.14 網路上看到的 nemoclaw plan/nemoclaw apply 是什麼?

那是 Rust 重寫的 v1 預覽線(v1 分支、v0.1.0-rc*、v1.0.0-rc1 標籤),採宣告式 YAML 的 plan/apply/destroy,搭配 OpenShell 0.1.4,官方明言尚無支援政策與企業部署驗證。與本手冊的 v0.0.x 不相容;可用 nemoclaw config export 為將來的遷移保留設定(1.7)。

🔍 自己驗證:nemoclaw --help 中沒有 plan/apply;v1 的狀態用 1.7 的指令確認。

17.15 可以讓 Agent 直接用我在主機上的 IDE 專案目錄嗎?

不建議。--host-mount 只能唯讀;share mount 雖然雙向,但等於讓 Agent 寫入主機目錄。建議在沙盒內 git clone 工作副本,Agent 在 ai/* 分支上工作,你在 IDE 端 checkout 該分支檢視(7.2)。

🔍 自己驗證:nemoclaw <名稱> share status 應沒有掛載;若用了 --host-mount,在沙盒內 touch 該目錄下的檔案應失敗(唯讀)。

17.16 NemoClaw 會把我的資料送給 NVIDIA 嗎?

安裝程式與 CLI 預設會嘗試送出匿名的操作完成遙測到 NVIDIA 的固定接收端;以 export NEMOCLAW_DISABLE_TELEMETRY=1 在每個 shell 停用。推理請求的內容則送到你選擇的推理服務(若選 NVIDIA Endpoints 就是 NVIDIA)。Prompt、Agent 讀進來的檔案、工具結果都會成為推理請求的一部分,依 13.6 資料分級決定推理服務。

🔍 自己驗證:echo $NEMOCLAW_DISABLE_TELEMETRY 在每個新 shell 都應印出 1;把它寫進 ~/.bashrc 後,開一個新終端機再確認一次。

17.17 NemoClaw 有已知的安全漏洞嗎?

有,而且是集中公告的。NVIDIA Security Bulletin 5872(2026-08-25)一次公告 18 個 CVE,影響 NemoClaw 0.0.25 以前與 OpenShell 0.0.33 以前的版本,最高為 CVSS 9.9 的沙盒逃逸。v0.0.139/OpenShell 0.0.116 已不在受影響範圍內。企業要訂閱 NVIDIA Product Security 公告,並用版本下限腳本盤點所有主機(6.17)。

🔍 自己驗證:執行 bash check-security-floor.sh(6.17.1),兩行都要是 OK,結束碼 0。

17.18 下一版會換成 OpenShell 0.1.5 嗎?

很可能,但研究日還沒有。main 的 PR #12603 正在把 OpenShell 升到 0.1.5,PR 自己標示「尚未可以核准或合併」,完整 E2E 仍有失敗。發布後,推理路由、Gateway、舊 volume 的處理都會改變,舊 volume 不會自動複製。核准前要照 12.11 的影響表在測試主機演練(12.4)。

🔍 自己驗證:gh pr view 12603 -R NVIDIA/NemoClaw --json state,mergedAt,以及 main 的 blueprint.yaml 中的 max_openshell_version(12.11)。

17.19 status --json 的 liveRoute 是 null,是不是壞了?

如果沙盒用的是原生附掛的 Provider(NVIDIA、固定託管或原生本地),liveRoute 與 routeDrift 永遠是 null,這是設計如此,不是故障。改看 recordedRoute 與 inferenceHealth(5.9)。

🔍 自己驗證:nemoclaw <名稱> status --json | jq '{provider, recordedRoute, liveRoute, inferenceHealth}';再照 4.9 送一次測試請求,能得到回應就代表推理正常。

第18章 參考資料與附錄

研究日期:2026-10-27。下表的「適用版本」以研究當日可確認者為準;外部標準與框架文件以該站最新版為準。

18.1 官方儲存庫

名稱網址用途適用版本/研究日期
NemoClawgithub.com/NVIDIA/NemoClaw原始碼、Issue、Discussionsmain@bafe6cc(2026-10-26)
NemoClaw v0.0.139 原始碼tree/v0.0.139本手冊核對基準v0.0.139(a08ae7a)
安裝程式install.sh(v0.0.139)bootstrap 行為與參數v0.0.139
Blueprintblueprint.yaml(v0.0.139)OpenShell 版本範圍、映像檔 digestv0.0.139
政策與 presetnemoclaw-blueprint/policies(v0.0.139)基準政策、層級、preset 原始檔v0.0.139
Agent 整合agents/(v0.0.139)各 Agent 的 manifest 與政策v0.0.139
平台矩陣ci/platform-matrix.json支援狀態唯一來源main
安全政策SECURITY.md漏洞私密回報管道main
NVIDIA 安全公告原始資料NVIDIA/product-security機器可讀的 CSAF 公告(2026/5872 為 NemoClaw/OpenShell 2026 年 8 月公告)研究日
OpenShell 0.1.5 升級 PRNVIDIA/NemoClaw#12603下一版預警(12.11)研究日:OPEN
v1 預覽線tree/v1Rust 重寫、desired-state YAMLv1@c2a71f8(2026-10-27)
社群範例NVIDIA/nemoclaw-community社群範例與 Blueprint 模式研究日
OpenShellgithub.com/NVIDIA/OpenShell底層執行環境最新 v0.1.5;NemoClaw 使用 0.0.116
OpenShell 0.0.116Release v0.0.116NemoClaw v0.0.139 綁定版本2026-08-28 發布
DGX Spark PlaybooksNVIDIA/dgx-spark-playbooksDGX Spark 上的 NemoClaw 流程研究日

18.2 官方安裝與快速入門文件

名稱網址用途
NemoClaw 文件首頁docs.nvidia.com/nemoclaw/latest文件入口(latest=v0.0.139)
Overviewabout/overview定位與能力
Architecture Overviewabout/how-it-works元件、保護層
Ecosystemabout/ecosystemNemoClaw 與 OpenShell 路徑比較
Architecture Detailsreference/architectureBlueprint、推理路由、主機狀態
Prerequisitesget-started/prerequisites硬體、軟體、平台
Windows Preparationadditional-setup/windows-preparationWSL 2 與 Docker Desktop
Quickstart(OpenClaw)get-started/quickstart首次安裝
Quickstart(Hermes)hermes/get-started/quickstartHermes
Quickstart(Deep Agents)deepagents/get-started/quickstartDeep Agents Code
Run Deep Agents Coderun-deep-agents-codedcode 互動與無頭模式
Platform Supportreference/platform-support支援狀態
Enterprise Readinessreference/enterprise-readiness企業能力邊界
CLI Commandsreference/commands指令參考
CLI Selection Guidereference/cli-selection-guidenemoclaw 與 openshell 分工
System Readinessreference/system-readinesshost probe
Host Files and Statereference/host-files-and-state~/.nemoclaw/
Troubleshootingreference/troubleshooting故障排除
Update Sandboxesupdate-sandboxes升級
Recover and Rebuildrecover-and-rebuild-sandboxes復原與重建
Uninstalluninstall-nemoclaw解除安裝
Understand Runtime Changesunderstand-runtime-changes執行期 vs 重建
Persist Sandbox Statecreate-and-restore-snapshots狀態保存
Transfer State Manuallytransfer-state-manually手動備份
Understand Sandbox Stateunderstand-sandbox-state--host-mount、工作區
Deploy to a Headless Serverdeploy-to-headless-server遠端主機
Release Notesrelease-notes版本變更
Use Docs with Coding Agentsresources/agent-skills給 Coding Agent 的文件入口

18.3 安全與政策文件

名稱網址用途
Network Policiesreference/network-policies基準政策、層級
Customize Network Policycustomize-network-policy政策工作流程選擇
Apply Policy Presetsapply-policy-presetspreset 套用
Create Custom Policy Presetscreate-custom-policy-presets自訂 preset 規則
Replace the Live Network Policyreplace-live-network-policy整份替換
Approve Network Requestsapprove-network-requestsopenshell term 核准
Security Best Practicessecurity/best-practices控制與風險取捨
Filesystem Controlsfilesystem-controls檔案系統
Process Controlsprocess-controls程序
Credential Storagecredential-storage憑證儲存
Credential Rotationcredential-rotation輪替與緊急處置
Corporate CA Trustconfigure-corporate-ca-trust企業 CA
Trusted Computing Basetrusted-computing-base信任邊界
Review Sandbox Hardeningreview-sandbox-hardening容器強化
Monitor Sandbox Activitymonitor-sandbox-activity監控與除錯
NVIDIA Product Securitynvidia.com/security安全公告訂閱、漏洞回報
Security Bulletin 5872a_id/58722026-08 NemoClaw/OpenShell 公告(6.17)
Canadian Centre for Cyber Security AV26-849AV26-849第三方對公告 5872 的轉述與影響範圍
OpenShell 文件docs.nvidia.com/openshell/latest⚠️ latest 為 v0.1.5,與 NemoClaw 使用的 0.0.116 不同
OpenShell 原始碼 docsNVIDIA/OpenShell/docs文件原始檔
OpenShell 範例NVIDIA/OpenShell/examples政策範例

18.4 Agent 官方文件

名稱網址用途
OpenClawopenclaw.ai預設 Agent
OpenClaw Docsdocs.openclaw.aiOpenClaw 設定與指令
Hermesget-hermes.aiHermes Agent
LangChain Deep Agents CodeDeep Agents Code Overviewdcode

📌 註記:openclaw.ai 與 docs.openclaw.ai 取自官方 NemoClaw README 與 Ecosystem 頁;研究當日在撰寫環境連線時被 TLS 層拒絕(TLSV1_ALERT_ACCESS_DENIED),無法驗證頁面內容(🧪)。其餘本章連結皆已逐一確認回應 200。

18.5 模型與推理服務

名稱網址用途
NVIDIA Build(NVIDIA Endpoints)build.nvidia.com託管模型與 API Key
DGX Spark NemoClaw Playbookbuild.nvidia.com/spark/nemoclawDGX Spark 本地推理流程
vLLMdocs.vllm.ai本地/私有推理伺服器
Ollamaollama.com本地模型

18.6 容器與作業系統

名稱網址用途
Docker Engine Securitydocs.docker.com/engine/securitydaemon 攻擊面、docker 群組風險
Docker seccompseccomp profiles系統呼叫過濾
Docker Desktop WSL 2Docker Desktop WSLWSL backend
WSL 安裝Install WSLWindows 前置
LandlockLandlock LSM核心檔案系統限制

18.7 軟體安全與 SSDLC 標準

名稱網址用途
OWASP Top 10owasp.org/Top10Web 風險
OWASP ASVSASVS安全驗證標準(7.6.8)
OWASP SAMMowaspsamm.org成熟度模型
OWASP Top 10 for LLMgenai.owasp.org/llm-top-10LLM 應用風險(Prompt Injection 等)
OWASP Top 10 for Agentic Applications 2026genai.owasp.orgAgent 風險 ASI01~ASI10(6.18)
gitleaksgithub.com/gitleaks/gitleaks偵測進入 Git 的祕密(13.5)
NIST SSDF SP 800-218csrc.nist.gov安全開發框架
SLSAslsa.dev供應鏈完整性
CycloneDXcyclonedx.orgSBOM
SPDXspdx.devSBOM/授權
gitleaksgitleaks/gitleaks機密掃描
OWASP Dependency-CheckDependency-Check依賴弱點
Trivytrivy.dev映像檔與依賴掃描

18.8 Framework 與測試工具官方指南

名稱網址用途
Oracle JDK 21 Migration GuideJDK 21 MigrationJava 升級
Spring Boot 3.0 Migration GuideSpring Boot 3.0 MigrationSpring Boot 升級
Spring Framework VersionsSpring Framework Versions支援矩陣
Vue 3 Migration Guidev3-migration.vuejs.orgVue 升級
Angular Update Guideangular.dev/update-guideAngular 升級
TypeScript Release NotesTypeScript Release NotesTS 升級
Node.js ReleasesNode.js ReleasesLTS 時程
Maven Release HistoryMaven HistoryMaven 版本
Gradle UpgradingUpgrading Gradle 8Gradle 升級
OpenRewritedocs.openrewrite.org確定性重構 recipe
JUnit 5 User GuideJUnit 5單元測試
ArchUnit User GuideArchUnit架構測試(7.8)
Testcontainers for Javajava.testcontainers.org整合測試
Playwrightplaywright.devE2E

18.9 附錄

18.9.1 附錄 1:安裝前檢查清單

  • 平台為 Ubuntu 24.04(或 WSL 2 Ubuntu 24.04/Apple Silicon macOS),已確認 3.1 的支援狀態。
  • 主機為個人專用(非多使用者共用)。
  • CPU ≥ 4、RAM ≥ 8 GB(建議 16 GB 以上)、可用磁碟 ≥ 20 GB(建議 40 GB 以上)。
  • 核心 ≥ 5.13(Landlock)。
  • Docker 可用;docker 群組的使用符合公司規範。
  • git、strings(binutils)、sha256sum、curl 已安裝。
  • 容器內 DNS 正常(docker run --rm busybox nslookup registry.npmjs.org)。
  • 可連 www.nvidia.com、github.com、ghcr.io、registry.npmjs.org 與推理端點。
  • 企業 Proxy 與 CA 已準備(NEMOCLAW_PROXY_HOST、NEMOCLAW_CORPORATE_CA_BUNDLE)。
  • 已取得專案專屬、低額度的推理 API Key(存於密碼庫)。
  • 已決定版本(NEMOCLAW_INSTALL_TAG)與 Agent。
  • 環境申請單已核准(13.2)。

18.9.2 附錄 2:安裝後驗收清單

  • nemoclaw --version 為核准版本;openshell --version 為 Blueprint 指定版本。
  • nemoclaw host probe 結束碼 0。
  • nemoclaw doctor 全部通過。
  • nemoclaw <名稱> status:Ready、Inference healthy、Agent 版本正確。
  • 4.9 的測試請求回覆預期字串。
  • 4.10 控制有效性驗證 7 項全部符合。
  • ~/.bashrc 含 export NEMOCLAW_DISABLE_TELEMETRY=1。
  • 12.2 盤點表已存檔並附在申請單。

18.9.3 附錄 3:沙盒安全檢查清單

  • 政策層級為 Restricted(不是 Balanced、Open、Personal)。
  • policy list 只有核准的 preset。
  • Deep Agents 的 github 基準項目已依需求排除或保留並記錄理由。
  • 所有自訂 preset 通過 nemoclaw-policy-lint.py(0 ERROR)。
  • 6.12 V1~V6 全部符合。
  • 沒有寫入 preset 長期掛著。
  • 沙盒內沒有 .env、私鑰、正式環境憑證。
  • 未啟用訊息通道、Dashboard 未對外綁定、未開 NEMOCLAW_EXPERIMENTAL。
  • 沒有 share mount 掛家目錄。
  • 沙盒無任何通往正式環境的路徑。

18.9.4 附錄 4:AI Agent 開發工作流程(一頁版)

  1. 規格放進 docs/spec/;AGENTS.md 就位(7.5)。
  2. Agent 讀規格與程式 → 提出計畫(不改檔)。
  3. 人工核准計畫。
  4. Agent 在 ai/<任務> 分支小步實作、補測試。
  5. Agent 輸出交付報告(修改清單、測試結果、未完成與待確認)。
  6. 工具驗證:check-change-report.py、check-layering.py。
  7. 套用寫入 preset(經核准)→ push → 移除寫入 preset。
  8. 開 PR → CI(建置、測試、ArchUnit、SAST、SCA、機密掃描)。
  9. 人工 Code Review(看完整 diff)→ 合併或退回。

18.9.5 附錄 5:逆向工程 Prompt 範本(一頁版)

【逆向工程共同規則】原始碼在 /sandbox/src(唯讀),輸出寫到 /sandbox/re-out/。禁止修改原始碼、禁止連線資料庫或外部系統。
每條結論標 [事實](來源:路徑:起-迄)或 [推測](依據:…;待確認 Q-xx)。找不到寫「未找到」並列出搜尋過的路徑與關鍵字。
MS950 亂碼回報檔名不猜內容;疑似機密以 *** 遮蔽並列出位置。最後輸出:檔案清單、[事實]/[推測] 數量、待確認問題。

R1 盤點:目錄樹(深度 3)、檔案數與行數、建置工具與框架版本、設定檔清單 → inventory.md、modules.csv
R2 呼叫鏈:URL → JSP → Action/Controller → Service → DAO → SQL/SP(表格附路徑:行)→ call-graph.md
R3 資料存取:DAO 方法、SQL 原文、資料表、SP 與參數、動態 SQL 位置 → data-access.md、tables.csv
R4 商業規則:條件、例外、錯誤碼;未實作的命名暗示標 [推測];規則衝突另列 → business-rules.md
R5 批次與介接:排程、MQ、檔案交換、外部 URL、重跑與失敗處理 → integration.md
R6 圖:系統架構圖、端到端資料流圖(節點都要能追溯到 R1~R5)→ architecture.md
R7 文件:SRS、SDD、api、data-dictionary(開頭註明快照日期與 commit)
R8 行為案例:每條 [事實] 規則的輸入與預期輸出 → behavior-cases.csv(不執行)
R9 回歸測試:characterization tests 草稿(_currentBehavior)與 regression-report.md 範本

18.9.6 附錄 6:Framework 升級 Prompt 範本(一頁版)

U1 差異分析(不改檔):依官方 Migration Guide 逐條列出 章節|檔案:行號|目前寫法|需要的修改|自動化可行性;
   列出 javax.* 數量;列出沒有 Jakarta 版本的依賴(查不到寫「未確認」);列出測試覆蓋不足的模組 → impact-analysis.md
U2 計畫(不改檔):分批(每批可獨立建置與測試)、每批範圍、預估檔案數、驗證、回復、風險與緩解、需人工決策處 → plan.md
U3 單批修改:只做計畫中的批次 N;在 ai/upgrade-batch-N 分支;不順手重構、不改格式、不升級計畫外依賴;
   每類修改一個 commit;遇到計畫外問題停下回報;完成後輸出交付報告與 git diff --stat

18.9.7 附錄 7:故障排除紀錄範本

欄位填寫內容
紀錄編號/日期時間
主機/沙盒/版本NemoClaw(填寫)/OpenShell(填寫)/Agent(填寫)
症狀(錯誤訊息原文)
問題卡分類(11.3.x)
診斷步驟與輸出(已遮蔽)
根因
解決方法
驗證結果
預防措施
是否更新規範或 preset(PR)

18.9.8 附錄 8:版本升級與回復檢查清單

  • 已閱讀 release notes 與 Platform Support 變更。
  • 已確認新版 min/max_openshell_version。
  • 測試主機演練(12.4)通過。
  • 12.2 盤點、backup-all、獨立備份、policy get 匯出完成。
  • 回復計畫(12.6)已填寫並指定決策者。
  • 以固定 tag 執行已審查的安裝程式。
  • upgrade-sandboxes --check 結束碼 0。
  • 12.9 升級後驗收全部通過;若不通過,依回復計畫執行。
  • 維護紀錄表(12.10)已更新。

18.9.9 附錄 9:企業使用規範檢查清單

  • 我只在核准的個人主機上、以核准版本使用 NemoClaw。
  • 我沒有把生產環境憑證、客戶個資、未授權原始資料或機密文件提供給外部模型服務。
  • 我的 API Key 來自密碼庫,沒有貼在對話、Prompt、文件或沙盒設定檔中。
  • 我只使用 Restricted 層與核准的 preset;新目的地都有申請單。
  • 我沒有在 openshell term 使用全部核准,也沒有核准未申請的目的地。
  • 我沒有用 docker exec 操作沙盒,也沒有單獨升級 OpenShell 或在沙盒內更新 Agent。
  • 我提交的 AI 參與 PR 都附交付報告,並已親自閱讀完整 diff。
  • 我沒有停用或刪除既有測試。
  • 發現異常時,我知道依 13.9 通報。
  • 主機停用前,我會撤銷上游憑證(12.8)。

18.10 企業自訂審查工具原始碼

以下 5 支工具皆為 🏢 本手冊自行撰寫(不是 NVIDIA 官方工具),✅ 已在撰寫環境(Python 3.12.8、PyYAML 6.0.3、Git 2.45.2)以合成資料實測。授權依企業內部規範使用。

18.10.1 nemoclaw-policy-lint.py

用途:靜態檢查自訂 preset 與整份 policy(6.16)。需要 python3 -m pip install pyyaml。

#!/usr/bin/env python3
"""nemoclaw-policy-lint.py — 企業自訂檢查:NemoClaw 自訂 preset 與整份 OpenShell policy 的審查輔助工具。

不是 NVIDIA 官方工具。規則依 NemoClaw v0.0.139 文件(Create Custom Policy Presets、
Network Policies、Security Best Practices)整理,並加上本手冊的企業收斂規則。
它只做靜態檢查,不連線、不呼叫 nemoclaw/openshell。

用法:
  python3 nemoclaw-policy-lint.py preset  my-api.yaml [...]
  python3 nemoclaw-policy-lint.py policy  current-policy.yaml
結束碼:0=無 ERROR;1=有 ERROR;2=用法或檔案錯誤。
"""
import re
import sys

try:
    import yaml
except ImportError:
    print("需要 PyYAML:python3 -m pip install pyyaml", file=sys.stderr)
    sys.exit(2)

MAINTAINED = {
    "brave", "brew", "brew-balanced", "claude-code", "discord", "github", "gmail",
    "huggingface", "jira", "local-inference", "local-memory", "npm", "openclaw-pricing",
    "outlook", "personal-open-internet", "public-reference", "pypi", "slack", "tavily",
    "teams", "telegram", "weather", "wechat", "whatsapp",
}
RESERVED_KEYS = {"npm_yarn", "personal_open_internet"}
RFC1123 = re.compile(r"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$")
CATCH_ALL = {"*", "0.0.0.0", "0.0.0.0/0", "::", "::/0", "**"}
WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
BROAD_BINARIES = {"/**", "/usr/bin/*", "/usr/bin/**", "/usr/local/bin/*", "/usr/local/bin/**", "/bin/*"}
INTERPRETER = re.compile(r"/(python3?[^/]*|node|bash|sh|curl|wget)$")
SECRET = re.compile(
    r"(nvapi-[A-Za-z0-9_-]{8,}|sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|"
    r"xox[abp]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|Bearer\s+[A-Za-z0-9._-]{16,})"
)

findings = []


def report(level, rule, where, msg):
    findings.append((level, rule, where, msg))


def walk_strings(node, path=""):
    if isinstance(node, dict):
        for k, v in node.items():
            yield from walk_strings(v, f"{path}.{k}" if path else str(k))
    elif isinstance(node, list):
        for i, v in enumerate(node):
            yield from walk_strings(v, f"{path}[{i}]")
    elif isinstance(node, str):
        yield path, node


def check_endpoint(where, ep):
    host = str(ep.get("host", ""))
    if not host:
        report("ERROR", "N03", where, "endpoint 缺少 host")
    elif host in CATCH_ALL or "/" in host:
        report("ERROR", "N03", where, f"host '{host}' 是全開或 CIDR 目的地,官方會拒絕")
    elif host.startswith("*.") and host.count(".") < 2:
        report("ERROR", "N03", where, f"host '{host}' 萬用字元範圍過大(只到頂級網域)")
    if "allowed_ips" in ep and host != "host.openshell.internal":
        report("ERROR", "N04", where, "自訂 preset 不得宣告 allowed_ips(改用 --trusted-private-host)")
    if ep.get("tls") == "skip":
        report("WARN", "N14", where, "tls: skip 會關閉 L7 檢查,需附 Raw TLS Passthrough 核准紀錄")
    protocol = ep.get("protocol")
    if protocol is None:
        report("WARN", "N06", where, f"'{host}' 沒有 protocol(L4-only,access={ep.get('access')});只看主機與程式,不檢查方法與路徑")
        return
    if ep.get("enforcement") != "enforce":
        report("ERROR", "N07", where, f"'{host}' 有 protocol 但未明確寫 enforcement: enforce")
    rules = ep.get("rules") or []
    if not rules and not ep.get("access"):
        report("ERROR", "N07", where, f"'{host}' 有 protocol 但沒有 rules")
    for j, r in enumerate(rules):
        allow = (r or {}).get("allow") or {}
        method = str(allow.get("method", "")).upper()
        path = str(allow.get("path", ""))
        rw = f"{where}.rules[{j}]"
        if method == "*":
            report("ERROR", "N08", rw, f"'{host}' method '*' 等於允許所有方法")
        elif method in {"PUT", "PATCH", "DELETE"} and path in {"/**", "/*", "**"}:
            report("ERROR", "N08", rw, f"'{host}' {method} {path}:寫入/刪除方法不可配全路徑")
        elif method == "POST" and path in {"/**", "**"}:
            report("WARN", "N08", rw, f"'{host}' POST /**:請收斂到實際 API 路徑")


def check_policies(where_root, policies):
    if not isinstance(policies, dict) or not policies:
        report("ERROR", "N05", where_root, "缺少 network_policies 或內容為空")
        return
    for key, pol in policies.items():
        where = f"{where_root}.{key}"
        if key in RESERVED_KEYS:
            report("ERROR", "N02", where, f"'{key}' 是官方保留鍵")
        pol = pol or {}
        bins = pol.get("binaries") or []
        if not bins:
            report("WARN", "N05", where, "沒有 binaries:此規則不授權任何程式,請求仍會失敗")
        for b in bins:
            p = str((b or {}).get("path", ""))
            if p in BROAD_BINARIES:
                report("ERROR", "N10", where, f"binary '{p}' 範圍過大")
            elif INTERPRETER.search(p.rstrip("*")):
                report("WARN", "N10", where, f"binary '{p}' 是直譯器或通用下載工具,等於沙盒內任何腳本都能用")
        for i, ep in enumerate(pol.get("endpoints") or []):
            check_endpoint(f"{where}.endpoints[{i}]", ep or {})


def lint(mode, path):
    try:
        with open(path, encoding="utf-8") as fh:
            text = fh.read()
        doc = yaml.safe_load(text) or {}
    except (OSError, yaml.YAMLError) as exc:
        print(f"{path}: 無法讀取或解析:{exc}", file=sys.stderr)
        sys.exit(2)
    for where, value in walk_strings(doc):
        if SECRET.search(value):
            report("ERROR", "N11", where, "疑似明文憑證;改用 OpenShell provider/placeholder")
    if "[STRIPPED_BY_MIGRATION]" in text:
        report("ERROR", "N12", path, "仍有 [STRIPPED_BY_MIGRATION],不可直接 openshell policy set")
    if mode == "preset":
        meta = doc.get("preset") or {}
        name = str(meta.get("name", ""))
        if not RFC1123.match(name):
            report("ERROR", "N01", "preset.name", f"'{name}' 不是小寫 RFC 1123 label")
        elif name in MAINTAINED:
            report("ERROR", "N01", "preset.name", f"'{name}' 與官方維護的 preset 同名")
        if not meta.get("description"):
            report("WARN", "N01", "preset.description", "缺少 description(審查與 policy list 時難以辨識)")
    else:
        if "preset" in doc:
            report("ERROR", "N13", path, "openshell policy set 不接受 preset 格式檔")
        if "version" not in doc:
            report("ERROR", "N13", path, "整份 policy 缺少 version")
        if "managed_inference" not in (doc.get("network_policies") or {}):
            report("ERROR", "N13", path, "整份替換會移除 managed_inference(推論路由會中斷)")
    check_policies("network_policies", doc.get("network_policies"))


def main(argv):
    if len(argv) < 3 or argv[1] not in {"preset", "policy"}:
        print(__doc__, file=sys.stderr)
        return 2
    for path in argv[2:]:
        before = len(findings)
        lint(argv[1], path)
        for level, rule, where, msg in findings[before:]:
            print(f"{level:5} {rule} {path} {where}: {msg}")
    errors = sum(1 for f in findings if f[0] == "ERROR")
    warns = sum(1 for f in findings if f[0] == "WARN")
    print(f"結果:{errors} ERROR,{warns} WARN")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

18.10.2 check-change-report.py

用途:比對 AI 交付報告與實際 Git 變更(7.10)。

#!/usr/bin/env python3
"""check-change-report.py — 企業自訂檢查:比對 AI Agent 交付報告與實際 Git 變更。

AI 說「我改了這些檔案、測試都通過」不是證據。本工具檢查:
  UNREPORTED  實際有變更、報告卻沒列出的檔案(最危險:沒人審)
  PHANTOM     報告列出、實際沒有變更的檔案(報告不可信)
  NOEVIDENCE  「測試結果」表沒有任何指令與結束碼
  TESTFAIL    測試結果有非 0 結束碼
  FORBIDDEN   變更碰到禁止路徑(預設:.env*、*.pem、*.key、正式環境設定)

報告格式(Prompt 範本要求 Agent 輸出):
  ## 修改清單          表格第一欄為檔案路徑
  ## 測試結果          表格欄位:指令|結束碼|摘要
用法:
  python3 check-change-report.py REPORT.md [BASE_REF]   (BASE_REF 預設 origin/main)
結束碼:0=通過;1=有問題;2=用法錯誤。
"""
import fnmatch
import re
import subprocess
import sys

FORBIDDEN = [".env", ".env.*", "*.pem", "*.key", "*application-prod*.yml", "*application-prod*.properties"]


def section_rows(text, title):
    rows, inside = [], False
    for line in text.splitlines():
        if line.startswith("## "):
            inside = line[3:].strip().startswith(title)
            continue
        if inside and line.strip().startswith("|"):
            cells = [c.strip() for c in line.strip().strip("|").split("|")]
            if cells and not re.fullmatch(r":?-{3,}:?", cells[0]) and cells[0] not in {"檔案", "指令"}:
                rows.append(cells)
    return rows


def git_changed(base):
    def run(*args):
        out = subprocess.run(["git", *args], capture_output=True, text=True, encoding="utf-8")
        if out.returncode != 0:
            print(out.stderr.strip(), file=sys.stderr)
            sys.exit(2)
        return {l.strip() for l in out.stdout.splitlines() if l.strip()}
    changed = run("diff", "--name-only", f"{base}...HEAD")
    changed |= run("diff", "--name-only")              # 未 commit 的修改
    changed |= run("ls-files", "--others", "--exclude-standard")  # 新增未追蹤
    return changed


def main(argv):
    if len(argv) < 2:
        print(__doc__, file=sys.stderr)
        return 2
    base = argv[2] if len(argv) > 2 else "origin/main"
    with open(argv[1], encoding="utf-8") as fh:
        text = fh.read()
    reported = {r[0].strip("`") for r in section_rows(text, "修改清單") if r[0]}
    report_path = argv[1].replace("\\", "/").lstrip("./")
    actual = {f for f in git_changed(base) if f != report_path and not f.startswith(".ai-reports/")}
    problems = []
    for f in sorted(actual - reported):
        problems.append(("UNREPORTED", f, "實際有變更,報告未列出"))
    for f in sorted(reported - actual):
        problems.append(("PHANTOM", f, "報告列出,但 Git 沒有這個變更"))
    for f in sorted(actual):
        name = f.rsplit("/", 1)[-1]
        if any(fnmatch.fnmatch(name, p) or fnmatch.fnmatch(f, p) for p in FORBIDDEN):
            problems.append(("FORBIDDEN", f, "變更碰到禁止路徑"))
    tests = [r for r in section_rows(text, "測試結果") if len(r) >= 2 and r[0]]
    if not tests:
        problems.append(("NOEVIDENCE", "-", "測試結果表沒有任何指令與結束碼"))
    for r in tests:
        code = r[1].strip("`")
        if not re.fullmatch(r"-?\d+", code):
            problems.append(("NOEVIDENCE", r[0], f"結束碼 '{r[1]}' 不是數字"))
        elif code != "0":
            problems.append(("TESTFAIL", r[0], f"結束碼 {code}"))
    for kind, f, msg in problems:
        print(f"{kind:10} {f}: {msg}")
    print(f"報告列出 {len(reported)} 檔、實際變更 {len(actual)} 檔、測試 {len(tests)} 筆、問題 {len(problems)} 項")
    return 1 if problems else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

18.10.3 check-layering.py

用途:Java 專案 Hexagonal 依賴方向快篩(7.8)。

#!/usr/bin/env python3
"""check-layering.py — 企業自訂檢查:Java 專案 Clean/Hexagonal 依賴方向快篩。

套件命名慣例(依專案調整 LAYERS):
  <root>.domain..        核心:實體、值物件、領域服務、Port 介面
  <root>.application..   Use Case:協調 domain、呼叫 Port
  <root>.adapter..       轉接:Web Controller、JPA Repository、外部 API Client
規則:
  L01 domain 不得 import application/adapter
  L02 domain 不得 import 框架(Spring、JPA、Jackson、Servlet)
  L03 application 不得 import adapter
  L04 application 不得 import Web/持久化框架(允許 jakarta.transaction 等可另行調整)
用法:python3 check-layering.py src/main/java com.example.order
結束碼:0=無違規;1=有違規;2=用法錯誤。
這是 CI 前的快篩,正式守門請用 ArchUnit(見手冊 7.8)。
"""
import pathlib
import re
import sys

IMPORT = re.compile(r"^\s*import\s+(static\s+)?([\w.]+)")
FRAMEWORK = ("org.springframework.", "jakarta.persistence.", "javax.persistence.",
             "com.fasterxml.jackson.", "jakarta.servlet.", "org.hibernate.")
WEB_PERSIST = ("org.springframework.web.", "org.springframework.data.", "jakarta.persistence.",
               "javax.persistence.", "jakarta.servlet.", "org.hibernate.")


def layer_of(pkg, root):
    rest = pkg[len(root) + 1:] if pkg.startswith(root + ".") else ""
    head = rest.split(".", 1)[0]
    return head if head in {"domain", "application", "adapter"} else None


def main(argv):
    if len(argv) != 3:
        print(__doc__, file=sys.stderr)
        return 2
    src, root = pathlib.Path(argv[1]), argv[2]
    violations = 0
    for java in sorted(src.rglob("*.java")):
        text = java.read_text(encoding="utf-8", errors="replace")
        m = re.search(r"^\s*package\s+([\w.]+);", text, re.M)
        if not m:
            continue
        layer = layer_of(m.group(1), root)
        if layer not in {"domain", "application"}:
            continue
        for no, line in enumerate(text.splitlines(), 1):
            im = IMPORT.match(line)
            if not im:
                continue
            target = im.group(2)
            tl = layer_of(target, root)
            rule = None
            if layer == "domain" and tl in {"application", "adapter"}:
                rule = "L01"
            elif layer == "domain" and target.startswith(FRAMEWORK):
                rule = "L02"
            elif layer == "application" and tl == "adapter":
                rule = "L03"
            elif layer == "application" and target.startswith(WEB_PERSIST):
                rule = "L04"
            if rule:
                violations += 1
                print(f"{rule} {java.as_posix()}:{no}: {layer} → {target}")
    print(f"結果:{violations} 項違規")
    return 1 if violations else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

18.10.4 check-evidence.py

用途:逆向工程文件的事實/推測引用檢查(8.6)。

#!/usr/bin/env python3
"""check-evidence.py — 企業自訂檢查:逆向工程文件的「事實/推測」引用檢查。

Prompt 範本要求 Agent 在文件中這樣標示:
  - [事實] 訂單金額超過 50,000 需主管覆核。(來源:src/main/java/x/OrderService.java:88-97)
  - [推測] 狀態 9 可能代表人工結案。(依據:OrderStatus.java:12 只有常數、無註解;待確認 Q-07)
規則:
  MISSING   [事實] 沒有「來源:路徑:行號」
  BADFILE   來源檔案不存在
  BADLINE   行號超出檔案長度,或起訖顛倒
  NOBASIS   [推測] 沒有「依據:」或沒有待確認編號(Q-xx)
  UNTAGGED  條列看起來是結論(含「必須/會/一律」)卻沒有標示 [事實] 或 [推測]
用法:python3 check-evidence.py docs/SDD.md <原始碼根目錄>
結束碼:0=通過;1=有問題;2=用法錯誤。
"""
import pathlib
import re
import sys

CITE = re.compile(r"來源:\s*([\w./\\-]+?):(\d+)(?:-(\d+))?\s*[))]")
CLAIM_WORDS = ("必須", "一律", "會自動", "禁止", "只能")


def main(argv):
    if len(argv) != 3:
        print(__doc__, file=sys.stderr)
        return 2
    doc, root = pathlib.Path(argv[1]), pathlib.Path(argv[2])
    problems = 0
    facts = guesses = 0
    for no, line in enumerate(doc.read_text(encoding="utf-8").splitlines(), 1):
        s = line.strip()
        if not s.startswith(("-", "*", "|")):
            continue
        where = f"{doc.as_posix()}:{no}"
        if "[事實]" in s:
            facts += 1
            cites = CITE.findall(s)
            if not cites:
                print(f"MISSING  {where}: [事實] 沒有來源")
                problems += 1
            for path, start, end in cites:
                target = root / path
                if not target.is_file():
                    print(f"BADFILE  {where}: {path} 不存在")
                    problems += 1
                    continue
                total = len(target.read_text(encoding="utf-8", errors="replace").splitlines())
                a, b = int(start), int(end or start)
                if a < 1 or b > total or a > b:
                    print(f"BADLINE  {where}: {path}:{start}{'-' + end if end else ''} 超出 1–{total}")
                    problems += 1
        elif "[推測]" in s:
            guesses += 1
            if "依據:" not in s or not re.search(r"Q-\d+", s):
                print(f"NOBASIS  {where}: [推測] 需要「依據:」與待確認編號 Q-xx")
                problems += 1
        elif any(w in s for w in CLAIM_WORDS) and not s.startswith("|"):
            print(f"UNTAGGED {where}: 疑似結論但未標示 [事實]/[推測]")
            problems += 1
    print(f"結果:事實 {facts} 條、推測 {guesses} 條、問題 {problems} 項")
    return 1 if problems else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

18.10.5 check-test-weakening.py

用途:找出 AI 變更中刪除或弱化測試的跡象(13.8)。只用 Python 標準函式庫與 Git。

#!/usr/bin/env python3
"""check-test-weakening.py — 企業自訂檢查:找出 AI 變更中「刪除或弱化測試」的跡象。

Agent 想讓 CI 變綠時,最便宜的做法是改測試而不是改程式。本工具比對 BASE 與工作目錄:
  DELETED    測試檔被刪除或改名到非測試路徑
  FEWERTESTS 測試檔中的測試案例數減少(@Test、@ParameterizedTest、it(、test()
  FEWERASSERT 測試檔中的斷言數減少(assert*、assertThat、expect(、verify()
  DISABLED   新增停用標記(@Disabled、@Ignore、.skip(、xit(、xdescribe(、.only()
  SKIPBUILD  建置設定新增略過測試(skipTests、maven.test.skip、testFailureIgnore、--passWithNoTests)

它只看文字差異,不執行測試;結果是「需要人看」的清單,不是定罪。
用法:
  python3 check-test-weakening.py [BASE_REF]   (BASE_REF 預設 origin/main;在 repo 根目錄執行)
結束碼:0=沒有發現;1=有發現;2=用法或 Git 錯誤。
"""
import re
import subprocess
import sys

TEST_PATH = re.compile(r"(^|/)(src/test/|tests?/|__tests__/)|(Test|Tests|IT)\.java$|\.(test|spec)\.[cm]?[jt]sx?$")
BUILD_FILE = re.compile(r"(^|/)(pom\.xml|build\.gradle(\.kts)?|package\.json|vitest\.config\.[cm]?[jt]s|jest\.config\.[cm]?[jt]s)$")
CASE = re.compile(r"@(Test|ParameterizedTest|RepeatedTest)\b|(^|[^\w.])(it|test)\s*\(")
ASSERT = re.compile(r"\bassert\w*\s*\(|\bassertThat\s*\(|\bexpect\s*\(|\bverify\s*\(")
DISABLE = re.compile(r"@Disabled\b|@Ignore\b|\.(skip|only)\s*\(|\bx(it|describe|test)\s*\(")
SKIP = re.compile(r"skipTests|maven\.test\.skip|testFailureIgnore|passWithNoTests|-x\s+test\b")


def git(*args, check=True):
    out = subprocess.run(["git", *args], capture_output=True, text=True, encoding="utf-8")
    if check and out.returncode != 0:
        print(out.stderr.strip(), file=sys.stderr)
        sys.exit(2)
    return out


def old_text(base, path):
    out = git("show", f"{base}:{path}", check=False)
    return out.stdout if out.returncode == 0 else ""


def new_text(path):
    try:
        with open(path, encoding="utf-8") as fh:
            return fh.read()
    except FileNotFoundError:
        return ""


def count(pattern, text, per_line=False):
    lines = [l for l in text.splitlines() if not l.lstrip().startswith(("//", "*", "#"))]
    if per_line:
        return sum(1 for l in lines if pattern.search(l))
    return sum(len(pattern.findall(l)) for l in lines)


# (代號, 樣式, 以行計數, 增加才算問題, 訊息);前三條只看測試檔,最後一條只看建置設定
RULES = [
    ("FEWERTESTS", CASE, False, False, "測試案例"),
    ("FEWERASSERT", ASSERT, False, False, "斷言"),
    ("DISABLED", DISABLE, False, True, "停用標記"),
]
BUILD_RULE = ("SKIPBUILD", SKIP, True, True, "略過測試設定")


def compare(rules, path, before, after):
    found = []
    for code, pattern, per_line, worse_if_more, label in rules:
        b, a = count(pattern, before, per_line), count(pattern, after, per_line)
        if (a > b) if worse_if_more else (a < b):
            found.append((code, path, f"{label} {b} → {a}"))
    return found


def inspect(base, row):
    parts = row.split("\t")
    kind, old_path, path = parts[0][0], parts[1], parts[-1]
    if kind == "D" and TEST_PATH.search(old_path):
        return [("DELETED", old_path, "測試檔被刪除")]
    if kind == "R" and TEST_PATH.search(old_path) and not TEST_PATH.search(path):
        return [("DELETED", old_path, f"測試檔改名到非測試路徑 {path}")]
    before, after = old_text(base, old_path), new_text(path)
    if TEST_PATH.search(path):
        return compare(RULES, path, before, after)
    if BUILD_FILE.search(path):
        return compare([BUILD_RULE], path, before, after)
    return []


def main(argv):
    base = argv[1] if len(argv) > 1 else "origin/main"
    git("rev-parse", "--verify", base)
    status = git("diff", "--name-status", "-M", base).stdout.splitlines()
    status += [f"A\t{p}" for p in git("ls-files", "--others", "--exclude-standard").stdout.splitlines()]
    findings = [f for row in status for f in inspect(base, row)]
    for kind, path, msg in findings:
        print(f"{kind:11} {path}: {msg}")
    print(f"檢查 {len(status)} 個變更檔案,發現 {len(findings)} 項")
    return 1 if findings else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

18.11 上游變更追蹤表(v0.0.139 → main@bafe6cc)

main 領先 v0.0.139 共 18 個 commit,都還沒有發布。下表說明每一項對 v0.0.139 使用者的意義,以及手冊在哪裡說明。追蹤方法:gh api repos/NVIDIA/NemoClaw/compare/v0.0.139...main --jq '.commits[].commit.message | split("\n")[0]'。

PR類別內容對 v0.0.139 使用者的意義手冊章節
#13635、#13763E2E讓受信任的 E2E 控制器能驗證 OpenShell 0.1.3/0.1.5 候選版無直接影響;是 0.1.5 遷移的前置工作12.11
#13646agent管線輸入改由主機端計時(30 秒或 --timeout,上限 4 MiB)v0.0.139 上,不關閉的管線會讓指令卡住5.6
#13567onboard不支援的 --dcode-auto-approval thread-opt-in 在 onboarding 前就拒絕v0.0.139 會半途才失敗5.6
#13648文件說明原生 Provider 沙盒的 liveRoute/routeDrift 為 null行為在 v0.0.139 已存在,監控不要誤報5.9、17.19
#13134sandboxstatus 與 recovery 失敗時會顯示 Gateway 名稱或埠號v0.0.139 的錯誤訊息較難判斷是哪個 Gateway11.3.4
#13748inferenceOllama 回報 0 MB 可用 GPU 記憶體時,不再誤當成整張 VRAM 可用GPU 被占滿時可能選到放不下的模型3.2
#13137inference託管 vLLM 的 Key 改為原子寫入,中斷不再留下空檔v0.0.139 中斷後可能留下壞的 Key 檔,之後 onboarding 一直失敗11.3.7
#13237inference只換模型時,從沙盒內驗證沿用的 HTTPS adapter 路由inference set 只換模型時,驗證可能誤判5.7
#13591dcode編輯核准卡顯示完整路徑v0.0.139 只顯示檔名,核准前要自己確認路徑6.18
#13620hermes沒有搜尋 Provider 時,不再提供 web_search/web_extractv0.0.139 的 Hermes 會嘗試匿名搜尋、被政策擋下,回覆可能是空的或沒有依據6.15
#13696hermes下載 Hermes 原始碼封存遇到 HTTP 429 時,退避時間拉長到 60/120 秒建置映像檔時偶發 429 失敗,重跑即可11.3.3
#12813configHermes Dashboard 停用且埠號被重新配置時,config export 也能匯出v0.0.139 的 config export 對這種沙盒會失敗12.11
#13630、#13446、#13645uninstall無 systemd user manager 的 Linux 能正確移除 unit;多 Gateway 清理不再誤判預設埠;Docker 沒在跑時給出正確提示v0.0.139 解除安裝可能留下殘餘或給出誤導的訊息12.8
#13772文件改用核准過的遙測說明文字行為不變,仍以 NEMOCLAW_DISABLE_TELEMETRY=1 停用4.4、17.16
#13753CI調整專案 CI 設定無—

✅ 建議:每次核准新版本前,用同樣的方式產生「上一個核准版本 → 新版本」的追蹤表,逐列判斷影響,存進維護紀錄(12.10)。

18.12 名詞表

名詞說明
Agent Runtime沙盒內執行的 Agent 程式(OpenClaw、Hermes、dcode)
BlueprintNemoClaw 的版本化沙盒定義:映像檔 digest、政策、推理 profile
dcodeLangChain Deep Agents Code 的執行檔
Express 安裝DGX Spark、DGX Station、WSL 上的推薦預設安裝模式
Gateway(OpenShell)主機上的 OpenShell 控制程序:憑證、政策、推理代理、生命週期
Gateway(Agent)沙盒內 OpenClaw/Hermes 自己的 Gateway(Dashboard、API)
inference.localOpenShell 0.0.x 的共享推理路由虛擬主機名
lkglast known good,安裝程式預設安裝的標籤
onboardingnemoclaw onboard 的引導式初始化流程
Placeholder沙盒內代替真實憑證的佔位值,於核准出口替換
Preset可套用到沙盒的政策片段(YAML,preset: 開頭)
ProviderOpenShell 中的外部服務憑證與存取定義
Sandbox-first 文法nemoclaw <沙盒名稱> <動作>
Tier政策層級:Restricted、Balanced、Open、Personal
附掛式 Provider附掛到沙盒、限制主機/路徑/程式的原生推理 Provider
ASIOWASP Top 10 for Agentic Applications 的條目代號(ASI01~ASI10)
CSAFCommon Security Advisory Framework,機器可讀的安全公告格式;NVIDIA 公告以此格式發布
liveRoute/recordedRoutestatus --json 中「目前共享路由」與「沙盒紀錄的路由」;原生附掛 Provider 的 liveRoute 永遠是 null
PSIRTProduct Security Incident Response Team,廠商的產品資安事件處理小組

18.13 版本紀錄

版本日期變更
1.02026-10-27初版。基準 NemoClaw v0.0.139(a08ae7a)/OpenShell 0.0.116;main 追蹤至 bafe6cc。附 4 支已實測的審查工具與 ArchUnit 範例
1.12026-10-27同一基準再核對(無新 tag;lkg 仍為 v0.0.137;main 仍為 bafe6cc)。新增:6.17 安全公告與弱點修補(Bulletin 5872、版本下限腳本)、6.18 OWASP Agentic Top 10 對照、12.11 OpenShell 0.1.5 遷移預警、18.11 上游變更追蹤表、第 5 支審查工具 check-test-weakening.py;第 3、5、11~15、17 章的規範補上範例與驗證方法;FAQ 新增 17.17~17.19 並為每題加入自我驗證

新進成員快速檢查清單(Checklist)

第一週照這張表做,每一項都做完才開始在專案中使用 AI Agent。

第 1 天:理解:

  • 讀完「重要聲明」與第 1 章,能說出 NemoClaw 與 OpenShell 的差別。
  • 讀完 13.11 允許/禁止/需經核准表。
  • 知道自己專案的資料分級(13.6),以及能不能用外部推理服務。

第 2 天:環境:

  • 提出環境申請(13.2),取得個人主機。
  • 跑 3.9 預檢腳本,結束碼 0。
  • 依 4.3 下載並比對安裝程式,以固定 tag 安裝。
  • ~/.bashrc 加入 export NEMOCLAW_DISABLE_TELEMETRY=1。

第 3 天:驗收:

  • 以 Restricted 層建立 Deep Agents 沙盒。
  • 完成 4.9 測試請求與 4.10 控制有效性驗證。
  • 套用標準唯讀 preset,完成 6.12 V1~V6。
  • 在 openshell term 練習拒絕一個未核准請求。

第 4 天:開發流程:

  • 完成 16.1 演練 0 與 16.2 案例 A 的 A1~A7。
  • 親手跑一次 check-change-report.py、check-layering.py、check-test-weakening.py,看懂輸出。
  • 找出講師在案例中埋入的至少一個錯誤。

第 5 天:維運與收尾:

  • 練習 stop、start、logs、doctor、download 備份。
  • 讀 11.3 的 12 張問題卡,知道遇到 403 與 unauthorized 時先看哪裡。
  • 讀 6.17、6.18,知道去哪裡查安全公告,以及 OWASP Agentic Top 10 中哪些風險要靠人補強。
  • 簽署 18.9.9 企業使用規範檢查清單。

每天開工:

  • nemoclaw status、nemoclaw <名稱> status 正常(或直接跑 11.2 的 nemoclaw-daily.sh,結束碼 0)。
  • nemoclaw <名稱> policy list 沒有多出未核准的 preset。
  • 寫入 preset 用完就移除。