AI 程式設計教程中文版
官方教程中文版入門與安裝

快速上手 OpenClaw

用 OpenClaw onboarding 跑通模型認證、Gateway、Dashboard 和第一條訊息，確認最小閉環真的可用。

快速開始的目標不是學完所有配置，而是在最短路徑裡確認四件事：OpenClaw 已安裝、模型認證可用、Gateway 正在跑、你能在 Control UI 裡和 Agent 發第一條訊息。

這一章用 10 分鐘換什麼：你不會先陷進 channels、cron、skills 或遠端訪問，而是先得到一個能對話、能診斷、能繼續配置的本機 OpenClaw。

1. 先準備兩樣東西

快速開始只需要兩樣東西：

準備項為什麼需要
Node.jsOpenClaw CLI 和 Gateway runtime 依賴 Node；官方推薦 Node 24，也支援 Node 22.14+
模型供應商 API keyonboarding 會引導你配置 Anthropic、OpenAI、Google 等 provider

檢查 Node：

node --version

Windows 使用者可以用原生 Windows，也可以用 WSL2。需要更完整本地工具鏈時，WSL2 通常更穩定。

API key 先準備好：onboarding 會問模型 provider 和認證資訊。你可以先不接 Telegram / Discord，但不能沒有模型認證。

2. 安裝 OpenClaw

macOS / Linux / WSL2：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

官方安裝指令碼預設會進入 onboarding。如果你安裝時跳過了 onboarding，手動執行：

openclaw onboard --install-daemon

3. 跑 onboarding

openclaw onboard --install-daemon 會引導你完成：

  • 選擇模型 provider。
  • 填入 API key 或完成對應認證。
  • 建立基礎配置。
  • 安裝並配置 Gateway daemon。
  • 建立預設 workspace 和啟動檔案。

普通使用者優先走 onboarding，不要一開始手改 ~/.openclaw/openclaw.json。等跑通後，再用 openclaw configure、openclaw config set 或 Control UI 調整。

sequenceDiagram
    participant U as 你
    participant CLI as OpenClaw CLI
    participant GW as Gateway
    participant UI as Control UI
    participant Agent as Agent

    U->>CLI: openclaw onboard --install-daemon
    CLI->>GW: 寫入基礎配置並安裝 daemon
    U->>CLI: openclaw gateway status
    CLI->>GW: 查詢執行狀態
    U->>UI: openclaw dashboard
    UI->>GW: 連線本機入口
    U->>Agent: 傳送第一條訊息
    Agent-->>U: 返回 AI 回覆

onboarding 的產物不是一條命令：它應該同時留下配置、daemon、workspace 和可用的模型認證。少了任意一個，後面都會表現成“Gateway 跑了但 Agent 不能工作”。

4. 確認 Gateway 正在跑

openclaw gateway status

正常情況下你會看到 Gateway 監聽在 18789 埠。預設本機地址是：

127.0.0.1:18789

Gateway 是 OpenClaw 的中樞。訊息平臺、Web UI、CLI、桌面端和移動端都透過它連線 Agent。

如果狀態異常，先不要繼續配置渠道。先看這些命令：

openclaw doctor
openclaw logs
openclaw health
命令先看什麼
openclaw doctor安裝、配置、環境是否有明顯錯誤
openclaw logsGateway 啟動、schema、認證或埠錯誤
openclaw health當前執行狀態是否能被 Gateway 正常返回

5. 開啟 Dashboard

openclaw dashboard

這會開啟 Control UI。如果瀏覽器能載入，並且能看到聊天入口或配置入口，說明 Gateway 的本地 WebSocket / HTTP 入口可用。

也可以直接訪問：

http://127.0.0.1:18789

如果打不開，按這個順序判斷：

現象先判斷
瀏覽器打不開Gateway 是否真的在跑
埠連線失敗18789 是否被佔用或 Gateway 未啟動
頁面能開啟但不能聊天模型認證或 Agent workspace 是否完整
頁面配置異常openclaw.json 是否透過 schema 校驗

6. 傳送第一條訊息

在 Control UI 聊天框裡發一條簡單訊息，例如：

你现在能正常工作吗？请用一句话说明你的身份和当前 workspace。

能收到 AI 回覆，就說明最小閉環已經跑通。

這條訊息故意問“身份”和“workspace”，因為它能同時驗證三件事：

  • Agent 能呼叫模型生成回覆。
  • workspace 檔案被正確載入。
  • Gateway 到 Control UI 的請求鏈路可用。

第一條訊息不要測試複雜工具呼叫：不要一上來讓它讀全盤、執行 shell、接外部 API。先確認最小聊天鏈路，再逐步開啟工具和渠道。

7. 常見下一步怎麼選

跑通 Dashboard 之後，再決定下一步。

你想做什麼下一步
手機上聊天看 Channels 文件，先從 Telegram 這類 bot token 路徑開始
接團隊群先讀 pairing、allowlist、group mention 和安全邊界
改模型、tools、sandbox讀配置結構和 Gateway 配置
整理長期規則和記憶讀 Agent Workspace
後臺定時任務先讀 Gateway 執行時，再碰 cron、hooks、heartbeat

OpenClaw 支援 Discord、Feishu、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等渠道。每個渠道都要單獨處理 bot token、OAuth、webhook 或平臺側許可權。

下一步只選一個方向：沒跑通 Dashboard 就回到 Gateway；能聊天但身份不穩就看 workspace；準備接外部訊息才進入 Channel。

8. 環境變數什麼時候要動

如果你用服務賬號、要改狀態目錄、或者要指定配置路徑，官方列出幾個關鍵變數：

OPENCLAW_HOME=...
OPENCLAW_STATE_DIR=...
OPENCLAW_CONFIG_PATH=...

普通本機使用不需要一開始就設定它們。只有遷移、多例項、服務化部署時再動。

不要為了“看起來專業”提前改路徑：路徑越多，排障越難。第一臺機器先用預設路徑跑通，再考慮服務化和多例項。

9. 本章自檢

  1. onboarding 應該留下哪幾類產物？
  2. Gateway 預設監聽哪個本機埠？
  3. 第一條訊息為什麼要問身份和 workspace？

過關標準：你能用一句話說清 —— “快速開始不是配置完全部功能，而是驗證安裝、認證、Gateway、Control UI、Agent 回覆這條最小鏈路。”

10. 接下來去哪

理解配置結構

跑通之後，再理解 openclaw.json、schema、熱載入和金鑰邊界。

配置 Agent Workspace

如果第一條訊息能回覆，但身份和規則不穩定，下一步看 workspace。

Gateway 架構

從長期控制面繼續理解 Gateway、Client、Node、WebChat 和遠端入口。

11. 官方資料

安裝 OpenClaw

基於官方 OpenClaw 安裝教程，面向新手講清推薦安裝、Node 要求、替代路徑、原始碼安裝和安裝後驗證。

理解配置結構

理解 OpenClaw 配置結構：openclaw.json、JSON5、strict schema、熱載入、last-known-good、環境變數和金鑰邊界。

本頁目錄

1. 先準備兩樣東西2. 安裝 OpenClaw3. 跑 onboarding4. 確認 Gateway 正在跑5. 開啟 Dashboard6. 傳送第一條訊息7. 常見下一步怎麼選8. 環境變數什麼時候要動9. 本章自檢10. 接下來去哪11. 官方資料