---
title: "快速上手 OpenClaw"
description: "用 OpenClaw onboarding 跑通模型認證、Gateway、Dashboard 和第一條訊息，確認最小閉環真的可用。"
verifiedAt: "2026-05-06"
---

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

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

## 1. 先準備兩樣東西

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

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

檢查 Node：

```bash
node --version
```

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

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

## 2. 安裝 OpenClaw

macOS / Linux / WSL2：

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

Windows PowerShell：

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

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

```bash
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 調整。

```mermaid
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 回覆
```

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

## 4. 確認 Gateway 正在跑

```bash
openclaw gateway status
```

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

```text
127.0.0.1:18789
```

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

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

```bash
openclaw doctor
openclaw logs
openclaw health
```

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

## 5. 開啟 Dashboard

```bash
openclaw dashboard
```

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

也可以直接訪問：

```text
http://127.0.0.1:18789
```

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

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

## 6. 傳送第一條訊息

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

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

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

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

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

> [!CAUTION]
> **第一條訊息不要測試複雜工具呼叫**：不要一上來讓它讀全盤、執行 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 或平臺側許可權。

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

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

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

```bash
OPENCLAW_HOME=...
OPENCLAW_STATE_DIR=...
OPENCLAW_CONFIG_PATH=...
```

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

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

## 9. 本章自檢

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

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

## 10. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/configuration" title="理解配置結構" description="跑通之後，再理解 openclaw.json、schema、熱載入和金鑰邊界。" />
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/workspace" title="配置 Agent Workspace" description="如果第一條訊息能回覆，但身份和規則不穩定，下一步看 workspace。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/architecture" title="Gateway 架構" description="從長期控制面繼續理解 Gateway、Client、Node、WebChat 和遠端入口。" />
</Cards>

## 11. 官方資料

- [Getting started](https://docs.openclaw.ai/start/getting-started)
- [Install](https://docs.openclaw.ai/install)
- [Gateway architecture](https://docs.openclaw.ai/concepts/architecture)
- [Chat channels](https://docs.openclaw.ai/channels)
