openclaw setup

OpenClaw 隨附內建的系統代理程式（以「OpenClaw」身分發言），用於本機設定、修復與組態（先前稱為 Crestodian）。它只會在實際的預設模型完成一次真實對話回合後啟動。 全新安裝會先建立推論；格式錯誤的組態則仍使用傳統的 doctor 流程。

啟動時機

執行不含子命令的 openclaw 時，會根據組態狀態決定流程：

• 組態不存在，或雖存在但不含使用者設定（為空，或僅含 $schema/meta 鍵）：啟動包含即時 AI 驗證的引導式初始設定。
• 組態存在但驗證失敗：啟動傳統初始設定，回報問題並引導你使用 openclaw doctor。
• 組態存在且有效：開啟一般代理程式終端介面。若已設定且可連線的閘道，其預設代理程式已有模型，則會直接進入該介面，不經過初始設定或 OpenClaw。若稍後要進入 OpenClaw，請在終端介面內使用 /openclaw，或直接執行 openclaw setup。

執行 openclaw setup 會先即時測試已設定的預設模型。若對話回合通過，便啟動 OpenClaw。互動模式下若失敗，會開啟引導式推論設定，並在候選項通過後轉交給 OpenClaw。若推論無法使用，單次、JSON 及其他非互動式請求會失敗，並提示執行 openclaw onboard。openclaw --help 與 openclaw --version 仍使用其一般快速路徑。

非互動式直接執行 openclaw（無 TTY）時，會以簡短訊息結束，而非顯示根命令說明：在全新或無效的安裝中，訊息會指向非互動式初始設定；若組態有效，則會指向 openclaw agent --local ...。

openclaw onboard --modern 仍是 OpenClaw 的相容性別名，但使用相同的推論閘門：推論正常時開啟聊天；互動模式下失敗時啟動引導式推論設定；非互動模式下失敗時，則結束並提供初始設定指引。openclaw onboard --classic 會開啟完整的逐步精靈。

OpenClaw 顯示的內容

互動式 OpenClaw 會開啟與 openclaw tui 相同的終端介面外殼，並使用 OpenClaw 聊天後端。啟動問候語涵蓋：

• 組態有效性與預設代理程式
• OpenClaw 正在使用的已驗證模型
• 首次啟動探測所得的閘道連線狀態
• 下一個建議的偵錯動作

它不會傾印密鑰，也不會為了啟動而載入外掛命令列介面命令。

使用 status 可查看詳細清單：組態路徑、文件／原始碼路徑、本機命令列介面探測、金鑰／權杖是否存在、代理程式、模型及閘道詳細資訊。

OpenClaw 使用與一般代理程式相同的參考資料探索機制：在 Git 簽出目錄中，它會指向本機 docs/ 與原始碼樹；在 npm 安裝中，它會使用隨附文件並連結至 https://github.com/openclaw/openclaw，同時在文件不足時建議查看原始碼。

範例

openclawopenclaw setupopenclaw setup --jsonopenclaw setup --message "models"openclaw setup --message "validate config"openclaw setup --message "setup workspace ~/Projects/work" --yesopenclaw setup --message "set default model openai/gpt-5.6" --yesopenclaw onboard --modern

在 OpenClaw 終端介面內：

狀態健康狀況doctor驗證組態設定設定工作區 ~/Projects/workconfig set gateway.port 19001config set-ref gateway.auth.token env OPENCLAW_GATEWAY_TOKEN閘道狀態重新啟動閘道代理程式建立代理程式 work 工作區 ~/Projects/work模型設定模型供應商將預設模型設為 openai/gpt-5.6頻道頻道資訊 slack連線 slack開啟 slack 的頻道精靈外掛清單搜尋 slack 外掛plugin install clawhub:openclaw-codex-app-server與 work 代理程式交談與 ~/Projects/work 的代理程式交談稽核結束

操作與核准

OpenClaw 使用具型別的操作，而非臨時編輯組態。

唯讀操作會立即執行：顯示概覽、列出代理程式、列出已安裝的外掛、搜尋 ClawHub 外掛、顯示模型／後端狀態、執行狀態／健康狀況檢查、檢查閘道連線能力、執行不含互動式修復的 doctor、驗證組態，以及顯示稽核記錄路徑。

啟動引導式頻道設定（connect telegram）也會立即執行。其精靈會收集明確答案，並負責執行由此產生的寫入。

持久性操作需要在對話中核准（直接執行命令時則使用 --yes）：寫入組態、config set、config set-ref、設定／初始設定啟動程序、變更預設模型、啟動／停止／重新啟動閘道、建立代理程式，以及安裝外掛。

OpenClaw 內無法使用 doctor 修復，因為修復可能重寫支撐目前工作階段的供應商、驗證或預設代理程式推論路徑。請結束 OpenClaw，並在終端機執行 openclaw doctor --fix。唯讀的 doctor 在 OpenClaw 內仍可使用。

新代理程式會繼承經即時驗證的預設推論路徑。代理程式 ID openclaw 與 crestodian 保留給系統代理程式，無法建立為一般代理程式。已停用的 ID 仍會遭到封鎖，以免舊組態占用它。

config set 與 config set-ref 無法變更推論路徑狀態， 包括推論供應商的認證資訊、頂層 auth.*、模型目錄、 命令列介面後端、預設／個別代理程式模型路徑、代理程式參數／工具，或根層級 tools.*。也會拒絕直接寫入 env.*、secrets.*、plugins.* 與 $include， 因為這些寫入可能取代認證資訊解析或供應商啟用機制。閘道與頻道驗證仍是一般組態介面。請使用具型別的外掛／頻道工作流程；若路徑已完成設定，則使用 set default model <provider/model>；它會在儲存前即時測試該路徑。若要設定或 修復供應商／驗證存取權，請結束 OpenClaw 並執行 openclaw onboard。

OpenClaw 內會拒絕解除安裝外掛，因為移除供應商外掛可能停用支撐目前工作階段的推論路徑。請結束 OpenClaw，並從終端機執行 openclaw plugins uninstall <id>。

核准可用你自己的話表達：含義明確的回覆（「是」、「當然」、「繼續」、「暫時不要」）會依封閉且具確定性的清單判定。當已設定的路徑支援獨立的完成呼叫時，其他回覆只能根據你的訊息與待處理提案進行分類，絕不會由對話模型本身分類，因為它不能自行核准。無法分類或含義模糊的回覆會讓提案維持待處理狀態，並由對話再次詢問。

已套用的寫入會記錄於 ~/.openclaw/audit/system-agent.jsonl。探索操作不會稽核；只有已套用的操作與寫入會受到稽核。

頻道設定可透過託管對話進行，直到需要輸入機密為止。本機 OpenClaw 終端介面不接受精靈中的敏感答案，因為終端機聊天輸入可被看見。它會立即提供 open channel wizard，將所選頻道帶入具遮罩的終端機精靈；你也可以稍後執行 openclaw channels add --channel <channel>。

切換至具遮罩的頻道設定

本機聊天可將控制權交給具遮罩的頻道精靈：

開啟 slack 的頻道精靈頻道資訊 slack

open channel wizard for <channel> 會在聊天終端介面關閉後，開啟具遮罩的頻道設定。請先使用 channel info <channel> 查看頻道標籤、設定狀態、必要條件摘要及文件連結。

OpenClaw 絕不會在自身工作階段內變更供應商／驗證存取權：該工作階段已依賴此推論路徑。對於模型供應商設定或修復，configure model provider 會傳回結束／初始設定指引，而不啟動精靈或寫入組態。請結束 OpenClaw 並執行 openclaw onboard；初始設定會暫存認證資訊，而且僅儲存能完成真實即時對話回合的路徑。初始設定成功後，再次啟動 OpenClaw。

設定啟動程序

在引導式初始設定已建立推論後，setup 會設定其餘的工作區與閘道狀態。它只會透過具型別的組態操作寫入，並事先要求核准。

設定設定工作區 ~/Projects/work

setup 會保留經驗證的有效模型。它不會設定或 取代推論。

如果缺少推論或即時檢查失敗，請離開 OpenClaw 並執行 openclaw onboard。引導式初始設定會偵測已設定的模型、API 金鑰及已驗證的本機命令列介面，要求每個候選項提供真實回覆，且僅保存通過的路徑。越過此界線後，OpenClaw 會立即啟動，接著便能設定工作區、閘道、頻道、代理程式、外掛及其他選用功能。

當 macOS 應用程式連線至已設定的閘道，且其預設代理程式已有已設定的模型時，會完全略過此階梯流程，直接開啟一般代理程式介面。 對於全新或未完成設定的閘道，應用程式會透過 openclaw.setup.detect 與 openclaw.setup.activate 閘道方法驅動推論階梯流程： detect 會列出找到的所有候選後端；activate 會即時測試一個 候選項（進行真實的「reply with OK」完成呼叫），而且只有在測試通過後，才會保存該路徑所需的模型、 認證資訊及供應商／執行階段狀態。工作區與閘道預設值仍交由 OpenClaw 處理。失敗的候選項絕不會變更組態；應用程式會自動逐級嘗試，最後提供手動金鑰／權杖步驟，其中會填入來自閘道作用中 文字推論供應商外掛的資訊。所選供應商負責其起始模型 與組態，而認證資訊會以相同方式驗證後才儲存。

Codex 監督與其他選用外掛功能不屬於此 推論啟用交易。請只在推論正常運作且 OpenClaw 已啟動後進行設定；推論設定期間，現有的外掛原則與明確的 監督退出設定均不會變更。

AI 對話

互動式 OpenClaw 的自由形式對話會經由與一般 OpenClaw 代理程式相同的代理程式迴圈執行，且僅限使用一個 ring-zero OpenClaw 權限工具 openclaw，用以封裝具型別的操作。讀取動作可自由執行；變更則需針對該項確切操作取得你的對話式核准（請參閱「操作與核准」）；每次套用的寫入都會受到稽核並重新驗證。代理程式工作階段會持續存在，因此 OpenClaw 具備真正的多輪記憶。如果經驗證的推論路徑之後停止運作，請返回 openclaw onboard 修復後再繼續。

主機不會將自然語言請求剖析為操作。自由形式 訊息（包括看似命令的文字，以及「why did my gateway stop?」之類的問題）會傳給 AI，後者可透過 openclaw 工具將請求對應至具型別的操作。

當有變更待處理時，只有封閉清單中含義明確的核准或拒絕語句，才可在無推論的情況下判定。含義模糊的同意會交由 另一個已設定的完成呼叫處理，否則以拒絕為預設。結構化 精靈欄位與精確的主機導覽屬於使用者介面控制項，而非自然語言 操作剖析。其中一項機密衛生例外尤其重要：對敏感路徑（權杖、金鑰、密碼）執行精確的 config set 絕不會傳到 模型。主機會建立已遮蔽的提案，且該值會在 AI 可見的歷程中受到遮罩。機密請優先使用 config set-ref <path> env &lt;ENV_VAR&gt;。

訊息頻道救援模式絕不使用模型輔助的規劃器。遠端救援維持確定性，因此損壞或遭入侵的一般代理程式路徑無法被用作組態編輯器。

命令列介面測試框架信任模型

嵌入式執行階段與 Codex app-server 控制框架會直接強制執行 ring-zero 限制：該次執行會攜帶 OpenClaw 工具允許清單，其中僅包含 openclaw 工具。對 Codex 而言，OpenClaw 也會在該次執行中停用環境、原生 執行、多代理程式、目標、應用程式／外掛、skill/MCP、網頁搜尋，以及 request_user_input 介面。Codex 仍會注入其無作用的原生 update_plan 公用工具；它可以更新模型的暫存檢查清單，但無法寫入檔案 或 OpenClaw 設定。命令列介面控制框架不會使用 OpenClaw 的允許清單， 因此 OpenClaw 僅允許其自身工具選擇合約能證明 相同限制的後端：

• 可選取的後端（包括 Claude Code）會以空白的原生工具 選擇和一個 MCP 工具 openclaw 啟動。Claude 產生的 MCP 設定會 透過 --strict-mcp-config 套用，因此不會載入其他 MCP 伺服器。
• 宣告沒有原生工具的後端會收到相同的專用 OpenClaw MCP 伺服器。
• 原生工具永遠啟用或狀態未知的後端，會在推論前採取封閉式失敗；它們 無法承載 OpenClaw 工作階段。

只有 OpenClaw 工作階段會取得 openclaw MCP 伺服器；一般代理程式執行 永遠不會看到此工具。因此，可選取／無原生工具的命令列介面後端與 API 金鑰模型 會強制執行字面上的單一工具迴圈。Codex app-server 模型會強制使用 一個 OpenClaw 授權工具，加上無作用的原生規劃公用工具。在這 三種情況下，設定寫入仍僅限於 OpenClaw 經稽核的核准 合約。

Gemini CLI 仍可供一般代理程式使用，但它無法強制執行 推論閘門所需的無工具探測，因此無法承載 OpenClaw。

切換至代理程式

使用自然語言選擇器離開 OpenClaw，並開啟一般終端介面：

與代理程式交談與 work 代理程式交談切換至 main 代理程式

openclaw tui、openclaw chat 和 openclaw terminal 會直接開啟一般代理程式終端介面；它們不會啟動 OpenClaw。切換至一般終端介面後，/openclaw 會返回 OpenClaw，並可選擇附帶後續要求：

/openclaw/openclaw restart gateway

訊息救援模式

訊息救援模式是 OpenClaw 的訊息通道進入點：當一般代理程式無法運作，但受信任的通道（例如 WhatsApp）仍能接收命令時，請使用此模式。

這是確定性的緊急命令處理常式，而非對話式 OpenClaw 代理程式。它不會啟動全新的設定流程，也不會放寬 OpenClaw 聊天的推論閘門。

支援的命令：/openclaw <request>。救援功能僅接受完全符合規則的輸入命令語法——自然語言會遭拒絕並顯示提示，絕不會被猜測為某項操作，也絕不會查詢任何模型。

你，在受信任的擁有者私訊中：/openclaw statusOpenClaw：OpenClaw 救援模式。閘道可連線：否。設定有效：否。你：/openclaw restart gatewayOpenClaw：計畫：重新啟動閘道。回覆 /openclaw yes 以套用。你：/openclaw yesOpenClaw：已套用。已寫入稽核項目。

也可在本機或透過救援功能將代理程式建立作業排入佇列：

create agent work workspace ~/Projects/work model openai/gpt-5.6-sol/openclaw create agent work workspace ~/Projects/work

建立代理程式時，只能指定目前經即時驗證的預設模型。省略 模型即可繼承該路由。

遠端救援是管理介面，必須將其視為遠端設定修復，而非一般聊天。

遠端救援的安全性合約：

• 當代理程式／工作階段的沙箱處理啟用時停用；OpenClaw 會拒絕遠端救援，並引導使用本機命令列介面修復。
• 預設有效狀態為 auto：僅允許在受信任的 YOLO 操作中進行遠端救援，此時執行階段已具有不受沙箱限制的本機權限（tools.exec.security 解析為 full，且 tools.exec.ask 解析為 off，沙箱模式則為 off）。
• 需要明確的擁有者身分；不允許萬用字元傳送者規則、開放群組政策、未經驗證的網路鉤子或匿名通道。
• 預設僅限擁有者私訊；群組／通道救援需要明確選擇啟用。
• 外掛搜尋與清單僅供讀取。外掛安裝一律只能在本機執行（即使原本已啟用，仍會在救援模式中遭封鎖），因為它會下載可執行程式碼。本機 OpenClaw 與救援模式都會拒絕解除安裝外掛；請從終端機執行 openclaw plugins uninstall <id>。
• 遠端救援無法開啟本機終端介面，也無法切換至互動式代理程式工作階段；請使用本機 openclaw 進行代理程式交接。
• 即使在救援模式下，持久性寫入仍需要核准。
• 待處理的核准僅能使用一次。同一帳號、通道及傳送者發出的任何較新救援命令，都會撤銷較舊的計畫；執行失敗也會耗用核准，因此若要重試，請重新傳送命令。
• 每項已套用的救援操作都會受到稽核。訊息通道救援會記錄通道、帳號、傳送者及來源位址中繼資料；修改設定的操作也會記錄變更前後的設定雜湊。
• 絕不回顯密鑰。SecretRef 檢查會回報可用性，而非其值。
• 若閘道仍在運作，救援功能會優先使用閘道的型別化操作；若閘道已停止運作，救援功能只會使用不依賴一般代理程式迴圈的最小本機修復介面。

設定結構：

{  "systemAgent": {    "rescue": {      "enabled": "auto",      "ownerDmOnly": true,      "pendingTtlMinutes": 15,    },  },}

• enabled："auto"（預設值）僅在有效執行階段為 YOLO 且沙箱處理關閉時允許救援；false 絕不允許訊息通道救援；true 會在擁有者／通道檢查通過時明確允許救援（仍受沙箱處理拒絕規則約束）。
• ownerDmOnly：將救援限制為擁有者直接訊息。預設值為 true。
• pendingTtlMinutes：待處理的救援寫入在到期前，可保持開放以等待 /openclaw yes 核准的時間長度。預設值為 15。

openclaw doctor --fix 會將舊版 crestodian 設定區塊遷移至 systemAgent。執行階段只會讀取標準區塊。

遠端救援由下列 Docker 測試通道涵蓋：

pnpm test:docker:system-agent-rescue

選擇啟用的即時通道命令介面煙霧測試會檢查 /openclaw status，並透過救援處理常式執行一次持久性核准往返流程：

pnpm test:live:system-agent-rescue-channel

受推論閘門控管的封裝版一次性設定由下列項目涵蓋：

pnpm test:docker:system-agent-first-run

該封裝版命令列介面測試通道會從空白狀態目錄開始，並證明 OpenClaw 在沒有推論時會採取封閉式失敗。接著，它會透過 封裝版啟用模組測試並啟用假的 Claude。只有在此之後，模糊要求才會傳送至 規劃器並解析為型別化設定，接著執行一次性命令，以建立 額外的代理程式、透過啟用外掛及權杖 SecretRef 設定 Discord、驗證設定，並檢查稽核記錄。此測試通道提供 閘門／操作的佐證；它不會測試互動式上線引導或 OpenClaw 代理程式／工具／核准對話。下方的 QA Lab 情境會重新導向 相同的 Docker 測試通道：

pnpm openclaw qa suite --scenario system-agent-ring-zero-setup

相關內容

• 命令列介面參考資料
• Doctor
• 終端介面
• 沙箱
• 安全性