--- read_when: - 你正在實作或審查新手引導重新設計的其中一個階段 summary: 管理員導入流程重新設計的實作計畫（持續更新文件） title: 新手引導重新設計 x-i18n: generated_at: "2026-07-19T14:06:13Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: dc1f049d59cfa2638e7332ab4127905141625de5471144c856c91bfe50c9fa11 source_path: start/onboarding-redesign.md workflow: 16 --- # 新手設定重新設計實作計畫 > **持續更新的文件。** 本頁以實作層級追蹤系統管理員新手設定的重新設計， > 並隨各階段完成而更新。最後一個階段合併後，本頁將改寫為面向使用者的 > 新手設定指南，並加入文件導覽。在此之前，本頁刻意不列入 `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 | 已安裝應用程式的外掛建議（掃描、候選項目、AI 配對器、精靈步驟、`device.apps` 節點命令） | 傳統＋引導式命令列介面 | 已合併（[#109668](https://github.com/openclaw/openclaw/pull/109668)） | | 2 | 命令列介面系統管理員主幹（第零個問題、探索過場、自動套用＋孵化） | 引導式命令列介面 | 已合併（[`a83ed13204f1`](https://github.com/openclaw/openclaw/commit/a83ed13204f118adf1009e5ac88d5afe1905b86c)） | | 3 | 瀏覽器優先交接（GUI 工作階段偵測、等待儀表板連線、以終端介面作為備援） | 命令列介面 → 網頁 | 已合併（[#110054](https://github.com/openclaw/openclaw/pull/110054)） | | 4 | 網頁系統管理員介面（選項卡片、`openclaw.chat` 上的具型別 `question` 欄位、精靈步驟鏡像、首次執行交接） | 控制介面 | 已合併（[#110141](https://github.com/openclaw/openclaw/pull/110141)、[#110242](https://github.com/openclaw/openclaw/pull/110242)） | | 5 | 孵化與啟動（具單次語意的建議儲存區、自我命名的誕生流程、全新設定後自動孵化交接；頭像階梯延後） | 代理程式啟動 | 已合併（[#110173](https://github.com/openclaw/openclaw/pull/110173)、[#110331](https://github.com/openclaw/openclaw/pull/110331)） | | 6 | 系統管理員常駐 PR1（固定於側邊欄的項目、設定中的 Ask OpenClaw、一般介面樣式的照管者問候；事件評論與頻道召喚列入 PR2） | 網頁＋頻道 | 已合併（[#110269](https://github.com/openclaw/openclaw/pull/110269)） | | 7 | 韌性（設定損壞時仍可聯絡系統管理員、部分介面救援、自動診斷） | 閘道 | 後續工作 | ## 各階段實作備註 ### 第 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： ```bash gh workflow run ci.yml --ref -f target_ref= -f release_gate=true -f pull_request_number= ``` 執行作業必須位於 分支參照上，讓 `head_sha` 相符，且標題會變成 `CI release gate `，而 `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 推出。