Skip to main content

​
入門精靈（CLI）

入門精靈是在 macOS、 Linux 或 Windows（透過 WSL2；強烈推薦）上設定 OpenClaw 的推薦方式。 它在一個引導流程中設定本地 Gateway 或遠端 Gateway 連線，加上頻道、技能和 工作區預設值。 
openclaw onboard
最快的第一次聊天：開啟 Control UI（不需要頻道設定）。執行 openclaw dashboard 並在瀏覽器中聊天。文件：Dashboard。
稍後重新設定： 
openclaw configure
openclaw agents add <name>
--json 不代表非互動式模式。對於指令碼，請使用 --non-interactive。
入門精靈包含一個網路搜尋步驟，其中你可以選擇一個提供者 （Perplexity、Brave、Gemini、Grok 或 Kimi）並貼上你的 API key，以便代理 可以使用 web_search。你也可以稍後透過 openclaw configure --section web 設定。文件：Web tools。

​
QuickStart vs Advanced（進階）

精靈以 QuickStart（預設值）vs Advanced（進階）（完整控制）開始。
  • 本地 gateway（環回）
  • 工作區預設（或現有工作區）
  • Gateway 連接埠 18789
  • Gateway 認證 Token（自動產生，即使在環回上）
  • 新本地設定的工具政策預設：tools.profile: "coding"（現有明確設定檔予以保留）
  • DM 隔離預設：本地入門在未設定時寫入 session.dmScope: "per-channel-peer"。詳情：CLI 入門參考
  • Tailscale 曝露 關閉
  • Telegram + WhatsApp DM 預設為允許清單（系統會提示您輸入電話號碼）

​
精靈設定的內容

**本地模式（預設）**引導您完成這些步驟：
  1. 模型/認證 — 選擇任何支援的提供者/認證流程（API key、OAuth 或 setup-token），包括自訂提供者 （OpenAI 相容、Anthropic 相容或未知自動偵測）。選擇預設模型。 安全說明：如果此代理程式將執行工具或處理 webhook/hooks 內容，請優先使用最強的最新一代模型並保持嚴格的工具政策。較弱/較舊的層更容易受到提示注入攻擊。 對於非互動式執行，--secret-input-mode ref 將 env 支援的 refs 儲存在認證設定檔中，而非明文 API key 值。 在非互動式 ref 模式中，必須設定提供者環境變數；未設定該環境變數而傳入內聯 key 標誌會快速失敗。 在互動式執行中，選擇 secret reference 模式讓您指向環境變數或已設定的提供者 ref（file 或 exec），在儲存前進行快速預檢驗證。
  2. 工作區 — 代理程式檔案的位置（預設 ~/.openclaw/workspace）。植入引導檔案。
  3. Gateway — 連接埠、綁定位址、認證模式、Tailscale 曝露。 在互動式 token 模式中，選擇預設明文 token 儲存或選用 SecretRef。 非互動式 token SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
  4. 頻道 — WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
  5. Daemon — 安裝 LaunchAgent（macOS）或 systemd 使用者單元（Linux/WSL2）。 如果 token 認證需要 token 且 gateway.auth.token 由 SecretRef 管理，daemon 安裝會驗證它，但不會將解析後的 token 持久化到監督服務環境中繼資料中。 如果 token 認證需要 token 且已設定的 token SecretRef 未解析，daemon 安裝會被封鎖並提供可操作的指引。 如果同時設定了 gateway.auth.token 和 gateway.auth.password 且 gateway.auth.mode 未設定，daemon 安裝會被封鎖直到明確設定模式。
  6. 健康檢查 — 啟動 Gateway 並驗證它正在執行。
  7. 技能 — 安裝推薦的技能和選用相依套件。
重新執行精靈不會清除任何內容，除非您明確選擇重設（或傳入 --reset）。 CLI --reset 預設為設定、憑證和會話；使用 --reset-scope full 包含工作區。 如果設定無效或包含舊版金鑰，精靈會要求您先執行 openclaw doctor。
遠端模式僅設定本地客戶端連接到其他地方的 Gateway。 它不會在遠端主機上安裝或變更任何東西。

​
新增另一個代理程式

使用 openclaw agents add <name> 建立具有自己工作區、 會話和認證設定檔的獨立代理程式。不使用 --workspace 執行會啟動精靈。 設定的內容：
  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir
說明：
  • 預設工作區遵循 ~/.openclaw/workspace-<agentId>。
  • 新增 bindings 路由入站訊息（精靈可執行此操作）。
  • 非互動式標誌：--model、--agent-dir、--bind、--non-interactive。

​
完整參考

如需詳細的逐步說明、非互動式腳本、Signal 設定、 RPC API 和精靈寫入的完整設定欄位清單，請參閱 精靈參考。

​
相關文件