統一 Onboarding 與配置協議：讓 CLI、macOS 與 Web 同步的實作指南

你是否遇過這種情況？為了讓使用者順利上手，你得在 CLI 寫一套互動流程，在 Web 介面又要刻一套表單，甚至 macOS App 還要再搞一套。這不僅維護困難，邏輯還容易打架。

要解決這個問題，最好的方式就是建立一套統一的 Protocol。透過共享的 Wizard 引擎與 Gateway RPC，你可以確保不論使用者在哪個平台，都能獲得一致的配置體驗。

需要準備的東西

Gateway RPC 存取權限
支援 JSON Schema 渲染的 UI 環境
CLI 或 App 開發環境

快速開始

要在你的客戶端實作這套流程，只需遵循以下四個步驟：

1. 啟動 Wizard 流程

使用 wizard.start 來初始化一個 Session。你可以指定模式是 local 或 remote。

// Request
{
  "method": "wizard.start",
  "params": {
    "mode": "local",
    "workspace": "my-project"
  }
}

2. 提交答案並推進步驟

根據回傳的 sessionId，使用 wizard.next 傳送使用者的輸入。

// Request
{
  "method": "wizard.next",
  "params": {
    "sessionId": "session-123",
    "answer": {
      "stepId": "api-key-step",
      "value": "your-api-key"
    }
  }
}

3. 檢查狀態與錯誤

每次呼叫後，你會收到包含 done 狀態與 step 資訊的回應。

// Response
{
  "sessionId": "session-123",
  "done": false,
  "step": { ... },
  "status": "active",
  "error": null
}

4. 獲取配置 Schema

如果你需要渲染完整的配置表單，請呼叫 config.schema。這會回傳 JSON Schema 以及 uiHints。

// Request
{
  "method": "config.schema",
  "params": {}
}

UI 渲染邏輯

當你拿到 uiHints 時，請注意以下兩點處理規則：

敏感欄位：如果欄位被標記為敏感（sensitive），請務必將其渲染為密碼輸入框（password input）。
回退機制：如果遇到 UI 引擎不支援的 Schema 節點，請直接回退（fallback）到原始的 JSON 編輯器模式。

疑難排解

Wizard 回傳錯誤：檢查 wizard.next 或 wizard.status 回傳物件中的 error 欄位，這會包含流程中斷的具體原因。
取消流程：如果使用者中途離開，請務必呼叫 wizard.cancel 並帶上 sessionId 以釋放資源。

如果你在整合過程中遇到任何問題，可以直接詢問 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。