新手設定重新設計實作計畫

持續更新的文件。 本頁以實作層級追蹤系統管理員新手設定的重新設計， 並隨各階段完成而更新。最後一個階段合併後，本頁將改寫為面向使用者的 新手設定指南，並加入文件導覽。在此之前，本頁刻意不列入 docs.json。

核心願景

非技術使用者輸入 openclaw onboard（或開啟應用程式）後，會由單一對話式角色迎接： OpenClaw，也就是系統管理員（「custodian」僅為內部名稱；使用者一律看到 「OpenClaw」）。它會找出使用者的 AI，以事先告知的預設值取代提問來完成所有設定， 讓代理程式以可見的身分誕生時刻孵化，並從此持續可供聯絡，擔任系統的照管者。 預設即如魔法般順暢、只有一道同意界線，且絕無死路。

設計原則（已決定，請勿隨意重新爭論）：

• 事先告知且可輕鬆復原的預設值取代阻礙流程的提問。唯一的 硬性要求是推論功能可正常運作；其餘一切都只是選項。
• 第零個問題是同意界線：「Full access」（建議）表示 探索會以靜默方式自動進行；「Ask first」則會在每一項探索前要求一次 明確同意，包括 AI 掃描、應用程式掃描及記憶來源掃描，並提供完全不進行 掃描的全手動路徑。
• 以對話作為介面，並逐步啟用智慧功能：系統管理員介面會在 任何 AI 可運作前就已存在（使用指令碼式對話），並在路由驗證成功的那一刻 改由模型支援，且會明確告知。它絕不假裝具備智慧：若在路由驗證前輸入 自由文字，系統會得體地回應「讓我先把大腦啟動起來」。
• 孵化是一場儀式：維持在同一對話串中、切換頭像，由代理程式 為自己命名並選擇自己的形象。系統管理員只會說明一次層級關係：「你可以向我 詢問系統相關事項，也可以直接詢問你的代理程式，它會代為轉達。」
• 依來源區分信任層級：官方目錄項目可以預先選取； 無論模型排名如何，第三方 ClawHub Skills 絕不會預先選取，且其標籤會註明 將安裝發佈者的程式碼。
• 已設定的安裝不可侵犯：重新執行新手設定只會進行驗證。 它絕不會重新套用設定，也絕不會重新啟動閘道服務。
• 終端機是備援方案，而不是一道問題：當閘道可連線時， 優先使用瀏覽器儀表板；絕不詢問「終端機還是瀏覽器？」。
• 較弱的模型會使用精簡介面（自動 localModelLean），並以 淺顯文字說明，絕不使用工具、程式碼模式或內容視窗等術語。

目前已發布的流程（完成第 1～3 階段後）

在全新 macOS 安裝上執行 openclaw onboard 的順利路徑，總共按四次 Enter：

1. 安全性注意事項 → 按一次 Enter 確認（會保存；之後絕不再詢問）。
2. 第零個問題：「How should I set things up?」— Full access（建議） 或 Ask first。選擇會保存為 wizard.accessMode；重新執行時預設使用已儲存的 選項。受限模式搭配「configure manually」可在不進行任何掃描的情況下 進入供應商選擇器，並略過記憶來源掃描。
3. 探索過場：偵測程式設計命令列介面、環境變數金鑰與本機執行環境； 發現程式設計代理程式時會顯示簡短趣味訊息；依序即時測試候選項目，並將失敗項目 靜默彙整成單行摘要（詳細資料位於「See other options」之後）。第一條可用路由會被 宣布為預設值，且只需按一次按鍵即可前往完整選擇器；探索其他選項或略過時仍會 保留該可用路由。
4. 記憶匯入選項（Claude Code / Codex / Hermes）；若拒絕探索則略過。
5. 僅限全新安裝：自動套用標準設定計畫（工作區、閘道服務、工作階段， 與對話式「yes」所執行的計畫相同）。已設定的安裝會顯示「already set up」， 且絕不變更服務。
6. 應用程式建議：由已驗證模型根據官方目錄與 ClawHub，比對已安裝的 應用程式；官方頻道外掛會預先勾選，第三方 Skills 則須主動選取並附有警告標籤。 可略過；停用開關為 wizard.appRecommendations。
7. 孵化：閘道可連線時，瀏覽器交接會開啟（GUI）或顯示 （無頭模式／SSH）儀表板 URL，並等待控制介面連線—— 「Dashboard connected — continuing in your browser.」否則，或使用 --tui 時，會開啟已預先填入啟動孵化訊息的終端介面， 並由代理程式自我介紹。

遠端閘道的新手設定會保留既有的對話式交接 （handoffMode: "chat"）；設定必須套用於遠端閘道。

階段

各階段實作備註

第 1 階段——應用程式建議（PR #109668）

• 掃描器：src/infra/installed-apps.ts（不需 TCC 的 macOS 列舉；會追蹤 符號連結的 .app 套件）。
• 候選項目：官方目錄＋ClawHub 搜尋，總時間上限為 20 秒； 離線時會平順降級為僅使用目錄候選項目。目錄項目是沒有頂層 id 的套件資訊清單——候選項目以解析後的外掛 ID 為鍵 （已使用實際隨附目錄進行迴歸測試；曾經改用 entry.id 作為鍵時， 整個目錄被折疊，所有官方建議皆遭捨棄）。
• AI 配對器：在已驗證路由上執行一次補全 （src/system-agent/setup-app-recommendations.ts）；不使用人工整理的套件組合 ID 對照表—— 模型會排除名稱偶然重疊的項目。輸出受解析後模型本身的 maxTokens 預算限制（未傳入明確上限時，由串流層套用）。
• 供應鏈防護：ClawHub 列表文字由發佈者控制，且會進入 配對器提示，因此列表可能將自己推廣為「recommended」。只有官方目錄項目 可以預先選取；ClawHub Skills 一律需要明確勾選，並標示為 「third-party ClawHub skill; installs its publisher's code」。
• 節點命令 device.apps（TS 節點主機，與 Android 封裝格式一致）， 預設不共用；閘道停用開關為 wizard.appRecommendations。
• 傳遞功能位於傳統精靈與引導式系統管理員流程 （src/wizard/setup.app-recommendations.ts）中；重新導向至啟動流程尾端仍屬於第 5 階段 （該服務已接受可注入的資源清單來源）。單次語意（只在接受前提供， 並儲存掃描結果）也會隨第 5 階段的儲存區一併推出；目前重新執行仍會再次提供。
• 另已修正：自訂 completeSetupInference 提示不再繼承 驗證探測的 32 個 token 輸出上限（SETUP_INFERENCE_TEST_MAX_TOKENS 僅套用於「reply OK」探測）。

第 2 階段——命令列介面系統管理員主幹（PR #109841）

• 流程於 src/commands/onboard-guided.ts 中重製；遠端閘道新手設定 透過 handoffMode: "chat" 保留既有的聊天交接。
• 第零個問題會保存 wizard.accessMode（"full" | "guarded"）； 重新執行時預設使用已儲存的選項（接受預設值絕不會在未告知的情況下， 將受限模式降級為完整模式）。受限模式搭配手動設定會使用 listManualSetupInferenceOptions（僅限設定／資訊清單，不進行探測），並略過 記憶來源掃描。
• 探索：靜默收集失敗項目（單行摘要；詳細資料位於 「See other options」之後）、程式設計代理程式趣味訊息，以及事先告知的 路由預設值。趣味訊息中的工作階段數量將延後實作（目前僅提供定性描述）， 直到有低成本的工作階段計數介面可用。
• 全新安裝：applySystemAgentSetup（確定性的對話式 「yes」），接著透過 launchTuiCli 進行孵化，並預先填入啟動訊息。 已設定的安裝（預先存在模型或閘道設定——精靈時間戳記無法證明任何事， 因為設定／診斷也會共用這些時間戳記）只進行驗證，不套用任何項目， 也不重新啟動閘道服務。套用失敗時會退回對話式聊天。

第 3 階段——瀏覽器優先交接（PR #110054，已合併）

• src/commands/onboard-browser-handoff.ts 負責純圖形工作階段 偵測（SSH_CONNECTION/SSH_TTY；Linux 上為 DISPLAY/WAYLAND_DISPLAY） 以及 60 秒 GUI／300 秒 SSH 等待。目前引導式初始設定 僅在 macOS 上啟用移交；--tui 和其他平台保留 終端機出口。Linux／Windows 的啟用將於後續處理。
• 儀表板連結使用與傳統完成流程相同的 resolveAdvertisedControlUiLinks、 resolveLocalControlUiProbeLinks 和 buildOnboardingControlUiUrl 輔助函式。 瀏覽器啟動使用共用的 openUrl 輔助函式。
• 就緒狀態會輪詢現有的 system-presence RPC，並作為呈現已設定共用密鑰的命令列介面模式 回送用戶端——這是每個 openclaw 命令使用的受信任路徑。 在 SecretRef 閘道上，使用原始共用驗證的控制介面用戶端會因 “需要裝置身分”而遭拒。連線能力預檢會解析與等待迴圈相同的 目標（及密鑰），因此關卡與等待流程絕不會對驗證結果產生分歧。 僅當連線的 openclaw-control-ui/webchat 存在狀態資料列 相較於啟動前基準為新資料時，移交才會完成（已開啟的儀表板 無法完成移交）。
• gateway.controlUi.enabled: false 會在顯示任何 URL 前短路。
• 已針對使用相同設定的隔離閘道完成端對端驗證：列印 URL → 真實 瀏覽器連線 → “儀表板已連線——請在瀏覽器中繼續” → 不顯示 終端機出口。先前的“權杖不相符”停滯是測試框架 造成的假象——請參閱下方的測試操作手冊。

階段 4——網頁管理員介面（已合併：#110141、#110242）

• 在 openclaw.chat 上提供 /custodian 頁面，並使用選項卡片元件 （2-4 張卡片、最多一個建議選項、永遠可略過）；透過 ?onboarding=1 提供初始設定框架；模型設定的首次執行完成後會移交至此。
• 結構化問題是 SystemAgentChatResult 上具型別且可加成的 question 欄位 （每個選項均有 reply 文字；macOS 應用程式／終端介面 一律另行顯示散文說明）。產生端：兩種初始設定歡迎畫面，以及具有 2-4 個封閉選項的託管精靈選取／確認步驟——實際頻道精靈會呈現為卡片。 PR1 的字串標記權宜方案已刪除。
• 工作階段擁有權以閘道 URL 加上所有呈現的認證資訊為範圍 （權杖、密碼、啟動權杖、已儲存的裝置權杖——在短暫的 hello 中斷期間仍會保留）；失敗的使用者回合絕不可重播；敏感輸入 會逐字傳送，並在逐字稿中遮蔽。

階段 5——出口與啟動（已合併：#110173、#110331）

• 管理員會建立未命名的代理程式（工具呼叫）；代理程式的啟動流程 以自行命名開始。PR1 提供的儀式限制為三個節拍（名稱 → 靈魂 描述 → 技能問題），並將自繪頭像／圖像生成階梯 （模型生成候選項目 → 預設標記 → 保留標誌）延至後續處理。同一個 對話串中更換頭像；爪印保留給管理員使用。議定的身分會儲存兩次： 寫入 IDENTITY.md/SOUL.md（代理程式讀取的內容），以及透過 openclaw agents set-identity（頻道和 UI 顯示的內容）。
• 建議項目（階段 1 服務、具有僅一次語意的已儲存掃描）會成為 移除啟動檔案前的最後一個啟動步驟：“最精簡組合 還是最大便利性？”啟動流程會透過 openclaw onboard recommendations --json 讀取已儲存的提議（僅限不透明的安裝 ID），並在處理選擇後 確認該提議，因此絕不會再次詢問。頻道連線按鈕會附帶各頻道的 設定操作手冊；代理程式會以對話方式收集認證資訊，並將設定寫入 轉交給管理員（“正在詢問 OpenClaw……”是標準用語）。
• 自我學習應以詢問方式提出，而非直接宣告，並同時作為技能工作坊的 同意確認；說明 ClawHub 的發行信任、掃描、驗證和完整性 檢查，以及發布者程式碼警告——絕不可暗示每個版本都經過簽署。
• 自動出口已推出：全新安裝的設定套用流程會宣告出口並 進行移交（終端介面／閘道用戶端使用 open-agent）；網頁會進入 代理程式聊天，並預先填入“醒來吧，我的朋友！”草稿。 只有寫入後驗證完全通過時才會觸發移交。刪除後代理程式數量為零時 提供選項（而非自動處理）仍屬後續潤飾項目。

階段 6——管理員存在狀態（PR1 已合併：#110269；評論／召喚屬於 PR2）

• PR1 已推出：預設釘選的“OpenClaw”側邊欄項目（全新設定檔； 現有使用者會保留已儲存的釘選項目，並可透過自訂／More 存取）、 作為第一個設定項目的“詢問 OpenClaw”，以及使用一般框架的 /custodian 造訪流程，該流程會要求照管者問候（不使用初始設定歡迎畫面）， 且僅在初始設定模式下顯示「結束設定」。停駐式行內設定窗格 需要抽取共用的對話檢視（後續處理）。
• 具備防 Clippy 護欄的事件反應式評論：僅針對影響重大或 失敗的變更，除非有人詢問，否則每次造訪設定最多一次。相同的 事件接縫也能讓管理員日後為驗證功能降級或頻道故障代言。
• 頻道：日常使用時不可見（由代理程式轉交）；可透過明確 召喚及同一對話串中的代理程式離線事件觸及，並在平台允許時 使用自己的名稱與爪印頭像。
• 設定期間偵測到較弱的模型：自動設定 localModelLean，且管理員 會以直白文字說明，並提供升級選項。
• 管理員知道自己的內部暱稱（“有些人稱我為管理員——叫我 OpenClaw 也可以”），且一律以名稱稱呼代理程式。

階段 7——韌性（建置前需要擁有者決策）

原始草案——“無論設定損壞得多嚴重，都必須能觸及管理員”—— 與儲存庫的安全性政策衝突：根目錄指南指出，當設定在結構上無效時， 閘道會拒絕啟動，且只有 SecretRef 擁有者故障才會降級為 已設定但不可用的功能。從無效設定提供任何介面都屬於政策變更， 而非實作細節。有兩種範圍，請選擇其一：

• 選項 A（建議採用，符合政策）：命令列介面端自動執行 doctor。 當 閘道或命令列介面因已知形式的無效設定而啟動失敗時，命令列介面會提議執行 openclaw doctor --fix（或在取得同意後執行），接著重試一次並 清楚回報結果。不變更閘道行為；管理員仍可透過 現有的降級 SecretRef 路徑和終端機存取。
• 選項 B（需要擁有者明確核准與安全性審查）：閘道 最小介面模式。 遇到結構無效的設定時，啟動一個嚴格鎖定的 介面，只提供管理員對話和 doctor 操作。這會 改寫啟動時的失敗即關閉合約，且在撰寫任何程式碼前，必須定義其自身的入口 保護方案。

第 4 至第 6 階段的其餘後續工作（已追蹤，尚未排程）：用於艙口的頭像／圖片生成 階梯；macOS 應用程式對具型別 question 欄位的算繪；供管理員使用的 停駐式行內「設定」窗格（需要抽取共用對話檢視）； 事件反應式評論，以及頻道召喚／代理程式中斷復原 （第 6 階段 PR2）；針對能力較弱模型自動執行 localModelLean；現有 使用者已儲存的側邊欄釘選項目是否應採用 OpenClaw 項目。

測試與合併操作手冊（得來不易；進行第 4 至第 6 階段前請先閱讀）

• OPENCLAW_STATE_DIR 不會隔離閘道服務。 LaunchAgent 標籤（ai.openclaw.gateway）是全機器共用的：使用隔離狀態目錄進行全新安裝 的新手引導測試，會改寫並重新啟動實際 機器的服務（包裝函式指令碼會放在隔離目錄內；清除該目錄後， 下次服務啟動就會中斷）。進行任何全新安裝 測試後，請從實際環境執行 openclaw gateway install --force && openclaw gateway restart 來還原，並驗證 plist。產品後續工作： 使用狀態目錄範圍的服務標籤，或讓新手引導偵測外來服務。

• 安全的端對端測試框架：預先在隔離設定中加入 gateway 區段（讓新手引導採用已設定的安裝路徑，且絕不觸碰 服務），並在備用連接埠上，以一般權杖將 openclaw gateway run 作為一般前景程序執行。 該測試框架驗證了第 3 階段的迴圈， 包括實際的瀏覽器連線。

• 驗證路徑會依用戶端身分而異，不只取決於認證資訊。 狀態資訊和 其他操作員讀取操作會使用命令列介面模式的回送用戶端，認證資訊來自 同一份設定。使用權杖驗證的閘道需要共用密鑰；SecretRef／無驗證 閘道則可在沒有權杖時改用受信任的回送驗證。識別為 Control UI 的瀏覽器用戶端需要裝置身分，或安全環境下的 回送授權。如果探測對提供不同設定的閘道進行驗證 （請參閱 LaunchAgent 陷阱），會因「token mismatch」而失敗——該 問題曾短暫阻礙第 3 階段。

• 完成探測：runSetupInferenceTest 將驗證探測限制為 32 個輸出權杖；自訂提示詞會略過此限制，並受限於 模型自身的 maxTokens。推理模型會先以隱藏 推理消耗該預算——回合文字為空通常表示預算已在該處耗盡。

• 代理程式合併需要精確對應最新提交的託管 CI。 高負載的 CI 工作流程在 組織負載高時可能不會排入佇列；維護者可改為在 PR 分支上 分派 release-gate：

  gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>

  執行作業必須位於 分支參照上，讓 head_sha 相符，且標題會變成 CI release gate <sha>，而 scripts/verify-pr-hosted-gates.mjs 會接受此標題。接著照常使用 scripts/pr 進行準備／合併。

• CI 除了聚焦測試外還會強制執行的關卡：文件對照表 （新增任何文件頁面後執行 pnpm docs:map:gen）、oxlint（no-map-spread、 max-lines — 拆分檔案，絕不抑制）、check:test-types、knip 無效程式碼檢查（只匯出生產環境使用的內容；透過公開 API 執行測試）， 以及即時測試分片分類器 （test/scripts/test-live-shard.test.ts 必須列出所有新的 *.live.test.ts）。

決策紀錄

• 採用附帶終止開關的魔法掃描，而非事先徵得同意（階段 1；揭露資訊顯示於掃描進度列與結果註記中）。
• 完整垂直流程，包括節點 device.apps 命令（階段 1）。
• 第三方 ClawHub Skills 絕不預先選取，並標示為會安裝發布者的程式碼；官方項目則可預先勾選（階段 1，已發布的安全態勢）。
• 提供兩張存取卡片，而非三張；將同意機制前置整合至選擇中（階段 2）。
• 自動孵化並顯示公告，而非使用會造成阻塞的按鈕（階段 2/5）。
• 以瀏覽器為優先：終端孵化流程是備援方案，絕不詢問「使用終端還是瀏覽器？」（階段 3）。
• 管理員可透過頻道互動（召喚與復原），而非僅限網頁／命令列介面（階段 6）。
• 孵化會在同一討論串中進行，並切換頭像；完成後，應用程式會轉換至一般使用者介面（階段 5）。
• 設定介面保留「設定」名稱；管理員位於其中（以及側邊欄），而非取代該介面（階段 6）。
• 選項卡片有所限制：提供 2 至 4 個選項、恰好一個建議選項，且一律可略過；新手引導與代理程式提問工具共用同一元件（階段 4）。
• 「正在詢問 OpenClaw……」是標準的委派用語；靈魂可增添風格，但工具敘述須保持平實（階段 5）。
• 向使用者說明弱模型的內容裁減時，文案絕不使用「程式碼模式」、「工具」或「上下文視窗」（階段 6）。

已知缺口與後續工作

• LaunchAgent 標籤未限定於狀態目錄範圍（上述測試陷阱；也是 實際的多執行個體產品缺口）。
• 建議項目的一次性語意與已儲存的掃描（階段 5）；目前重新執行時 會再次提供。
• 瀏覽器移交僅支援 macOS；Linux/Windows 支援仍待完成。
• 工作階段數量的詼諧說法屬於定性描述；計數需要低成本的工作階段計數介面。
• 瀏覽器移交會進入一般儀表板；新手引導模式管理員的 深層連結將於階段 4 推出。