---
name: openclaw
description: OpenClaw AI agent 平台文檔 - 安裝設定、Gateway、瀏覽器控制、通訊頻道整合、Skills 開發
homepage: https://docs.openclaw.ai/
---

# OpenClaw 完整文檔

> 來源: https://docs.openclaw.ai/
> 完整文檔索引: https://docs.openclaw.ai/llms.txt

---

## 概述

OpenClaw 是一個 AI agent 平台，支援多種通訊頻道（WhatsApp、Telegram、Discord、iMessage 等），提供瀏覽器自動化、多代理路由、OAuth 認證等功能。

### 核心功能

- **Channels**: WhatsApp、Telegram、Discord、iMessage 整合
- **Plugins**: 可擴展插件系統（如 Mattermost）
- **Routing**: 多代理路由與 session 隔離
- **Media**: 圖片、音訊、文件處理
- **Apps**: Web 控制介面與 macOS 應用
- **Mobile nodes**: iOS 和 Android 支援

---

## 快速開始

### 系統需求

- Node.js 22 或更高版本
- pnpm（可選，推薦用於源碼構建）
- Windows 用戶需使用 WSL2 + Ubuntu
- macOS 開發者需要 Xcode/CLT

### 安裝方式

**標準安裝（推薦）：**

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

**Windows PowerShell：**

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

**npm/pnpm：**

```bash
npm install -g openclaw@latest
pnpm add -g openclaw@latest
```

### 設定精靈

```bash
openclaw onboard --install-daemon
```

設定精靈會處理：
- Gateway 類型選擇（local/remote）
- 認證方式（OAuth 或 API keys）
- 通訊頻道設定（WhatsApp、Telegram、Discord、Mattermost）
- 背景服務安裝
- Gateway token 生成

### 啟動 Gateway

```bash
openclaw gateway --port 18789 --verbose
```

存取 Dashboard：`http://127.0.0.1:18789/`

---

## 設定檔

### 位置

`~/.openclaw/openclaw.json`（JSON5 格式）

### 基本設定

```json5
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-5"
      }
    }
  },
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: {
      mode: "token",
      token: "your-long-random-token"
    }
  },
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"]
    }
  }
}
```

### 設定驗證

```bash
openclaw doctor        # 診斷設定問題
openclaw doctor --fix  # 自動修復
```

### 環境變數

- 語法：`${VAR_NAME}`（僅大寫）
- 來源順序：環境變數 → `.env` → `~/.openclaw/.env`

---

## Gateway 管理

### 常用指令

| 指令 | 說明 |
|------|------|
| `openclaw gateway` | 啟動 Gateway |
| `openclaw gateway status` | 查看狀態 |
| `openclaw gateway stop` | 停止 Gateway |
| `openclaw gateway restart` | 重啟 Gateway |
| `openclaw gateway health` | 健康檢查 |

### 啟動選項

```bash
openclaw gateway \
  --port 18789 \
  --bind loopback \
  --auth token \
  --verbose
```

- `--port <port>`: WebSocket port（預設 18789）
- `--bind <mode>`: loopback | lan | tailnet | auto
- `--auth <mode>`: token | password
- `--verbose`: 詳細日誌

### 服務管理

```bash
openclaw gateway install    # 安裝為系統服務
openclaw gateway start      # 啟動服務
openclaw gateway stop       # 停止服務
openclaw gateway uninstall  # 移除服務
```

---

## 通訊頻道

### WhatsApp

**設定：**

```json5
{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["+15551234567"],
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}
```

**登入：**

```bash
openclaw channels login
```

掃描 QR Code 連結 WhatsApp。

**DM 政策：**
- `pairing`: 未知發送者收到驗證碼（1小時過期）
- `allowlist`: 只允許列表中的號碼
- `open`: 公開存取（需設定 `"*"`）
- `disabled`: 停用 DM

### Telegram

**設定：**

1. 透過 @BotFather 建立 bot 取得 token
2. 設定環境變數或設定檔：

```json5
{
  channels: {
    telegram: {
      botToken: "your-bot-token",
      // 或使用環境變數 TELEGRAM_BOT_TOKEN
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}
```

**DM 政策：**
- `pairing`（預設）：新用戶收到驗證碼
- `allowlist`：只允許指定用戶
- `open`：公開存取
- `disabled`：停用

**群組設定：**
- `requireMention`：需要 @ 提及才回應
- `groupPolicy`：open | allowlist | disabled

### 驗證連線

```bash
openclaw channels status --probe
```

---

## 瀏覽器控制

### 概述

OpenClaw 運行獨立的瀏覽器環境，與個人瀏覽器分開。支援：
- Chrome/Brave/Edge/Chromium profiles
- 確定性 tab 控制
- 點擊、輸入、拖曳等操作
- 截圖與 PDF 生成

### 基本指令

```bash
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
```

### 設定

```json5
{
  browser: {
    enabled: true,
    headless: true,
    viewport: {
      width: 1920,
      height: 1080
    },
    locale: "zh-TW",
    timezone: "Asia/Taipei"
  }
}
```

### 安全注意事項

- 瀏覽器控制僅限 loopback
- 使用專用 profile，不要用個人瀏覽 profile
- 保持 Gateway 在私有網路

---

## Skills 系統

### 概述

Skills 是 AgentSkills 相容的資料夾，包含 `SKILL.md` 與 YAML frontmatter。

### 載入位置（優先順序）

1. `<workspace>/skills`（最高）
2. `~/.openclaw/skills`
3. 內建 skills（最低）

### SKILL.md 格式

```markdown
---
name: my-skill
description: 技能描述
homepage: https://example.com
user-invocable: true
---

# 技能內容

...
```

### ClawHub Registry

```bash
clawhub install <skill-slug>
clawhub update --all
clawhub sync --all
```

瀏覽：https://clawhub.com

### 設定覆蓋

```json5
{
  skills: {
    entries: {
      "skill-name": {
        enabled: true,
        apiKey: "KEY_VALUE",
        env: { VAR: "value" }
      }
    }
  }
}
```

---

## 安全性

### 安全審計

```bash
openclaw security audit         # 基本審計
openclaw security audit --deep  # 深度審計（包含 Gateway 探測）
openclaw security audit --fix   # 自動修復
```

### 威脅模型

1. **Inbound access control** - 誰能發訊息給 bot
2. **Tool blast radius** - bot 能執行什麼操作
3. **Network exposure** - Gateway 暴露程度

### 存取控制

**DM 政策：**
- `pairing`: 驗證碼機制
- `allowlist`: 白名單
- `open`: 公開（需明確設定）
- `disabled`: 停用

**群組控制：**
- 使用 mention-gating
- 設定 `groupPolicy`

### 憑證位置

- WhatsApp: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- Bot tokens: 環境變數或設定檔
- Auth profiles: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- Session 記錄: `~/.openclaw/agents/<agentId>/sessions/*.jsonl`

### 網路強化

```json5
{
  gateway: {
    bind: "loopback",
    auth: { mode: "token", token: "your-long-random-token" }
  }
}
```

- 預設 bind: loopback only
- 需要認證: 設定 `gateway.auth.mode: "token"`
- 使用 Tailscale Serve 取代 LAN binds

### 事件回應

1. **Contain**: 停止 Gateway
2. **Rotate**: 更換所有密鑰
3. **Audit**: 檢查日誌和 session 記錄
4. **Report**: 回報問題

---

## 疑難排解

### 診斷指令

| 指令 | 說明 |
|------|------|
| `openclaw status` | 本機摘要 |
| `openclaw status --all` | 完整診斷（包含日誌） |
| `openclaw status --deep` | 深度檢查（包含 provider 探測） |
| `openclaw logs --follow` | 即時日誌 |

### 常見問題

**API Key 遺失：**
```bash
openclaw models auth setup-token --provider anthropic
```

**OAuth Token 失敗：**
改用 setup-token 比 refresh 機制更可靠。

**HTTP 安全問題：**
使用 HTTPS（透過 Tailscale Serve）或本機 `http://127.0.0.1:18789/`

**Port 已被使用：**
```bash
openclaw gateway status
```

### 日誌位置

- 檔案日誌: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`
- macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log`
- Linux: `journalctl --user -u openclaw-gateway.service`

### 啟用 debug 日誌

```json5
{
  logging: {
    level: "debug"
  }
}
```

### 完全重設

```bash
openclaw gateway stop
rm -rf ~/.openclaw
openclaw onboard --install-daemon
```

---

## CLI 指令參考

### 基本指令

| 指令 | 說明 |
|------|------|
| `openclaw onboard` | 初始化設定精靈 |
| `openclaw gateway` | 啟動 Gateway |
| `openclaw doctor` | 檢查設定問題 |
| `openclaw channels login` | 連結通訊頻道 |
| `openclaw agent --message "你好"` | 發送訊息給 AI |
| `openclaw update` | 更新 OpenClaw |
| `openclaw status` | 查看狀態 |
| `openclaw health` | 健康檢查 |

### Gateway 指令

| 指令 | 說明 |
|------|------|
| `openclaw gateway` | 啟動 Gateway |
| `openclaw gateway status` | 查看狀態 |
| `openclaw gateway stop` | 停止 |
| `openclaw gateway restart` | 重啟 |
| `openclaw gateway install` | 安裝為服務 |
| `openclaw gateway uninstall` | 移除服務 |
| `openclaw gateway health` | 健康檢查 |
| `openclaw gateway probe` | 除錯探測 |
| `openclaw gateway call <method>` | RPC 呼叫 |
| `openclaw gateway discover` | 發現 Gateway（Bonjour） |

### Pairing 指令

```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>
```

### 訊息指令

```bash
openclaw message send --target +15555550123 --message "Hello"
```

---

## 更多資源

- [官方文檔](https://docs.openclaw.ai)
- [完整文檔索引](https://docs.openclaw.ai/llms.txt)
- [Getting Started](https://docs.openclaw.ai/start/getting-started)
- [Configuration](https://docs.openclaw.ai/gateway/configuration)
- [Security](https://docs.openclaw.ai/gateway/security)
- [Troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting)
- [Skills 平台](https://docs.openclaw.ai/tools/skills)
- [瀏覽器控制](https://docs.openclaw.ai/tools/browser)
- [Discord 社群](https://discord.gg/clawd)

---

*🦞 EXFOLIATE! EXFOLIATE!*