返回
Openclaw-Series

02. OpenClaw 環境搭建與首次執行

本文詳細介紹 OpenClaw 的安裝設定流程，涵蓋 npm/pnpm/bun 和 Docker 四種安裝方式，設定檔詳解，以及常見問題的排查方法。幫助開發者在 5 分鐘內完成環境搭建，啟動個人 AI 助手。

適用於 OpenClaw v2026.2 | 本文假設你有 Node.js >= 22 環境，以及一個 AI API Key（推薦 Anthropic Claude）。

TL;DR: 5 分鐘完成 OpenClaw 安裝。支援 npm/pnpm/bun/Docker 四種方式，推薦 npm install -g openclaw@latest && openclaw onboard。設定檔位於 ~/.openclaw/openclaw.json，透過 openclaw gateway 啟動。詳細涵蓋 Docker 部署、設定檔結構、常見問題排查。

前置要求

必需環境

環境 版本要求 檢查命令 說明
Node.js >= 22.0.0 node --version 推薦使用 LTS 版本
npm >= 10.0.0 npm --version Node.js 自帶
記憶體 >= 4GB - 推薦 8GB+ 用於複雜任務
磁碟 >= 2GB - 包含相依套件和快取

推薦環境

環境 說明
pnpm 或 bun 比 npm 更快，磁碟佔用更少
Docker 用於沙箱模式或隔離環境
Tailscale 用於遠端存取（可選）

AI API Key

OpenClaw 需要連接 AI 模型才能運作。推薦使用：

提供商 模型推薦 取得方式 價格參考
Anthropic Claude Opus 4.6 / Sonnet 4 console.anthropic.com 按用量計費
OpenAI GPT-4o / GPT-4-turbo platform.openai.com 按用量計費
本地模型 Ollama + Llama 3 本地部署 免費（需硬體）

💡 推薦：Anthropic Claude Opus 4.6 提供最佳的長上下文處理和提示注入防護能力。

環境驗證

# 檢查 Node.js 版本
node --version
# 輸出範例: v22.12.0

# 檢查 npm 版本
npm --version
# 輸出範例: 10.9.0

# 檢查系統資訊
uname -a  # Linux/macOS
# 或
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"  # Windows

安裝方式對比

flowchart TB
    A[選擇安裝方式] --> B{使用場景?}
    B -->|快速體驗| C[npm 全域安裝]
    B -->|日常使用| D[pnpm/bun 安裝]
    B -->|正式部署| E[Docker 部署]
    B -->|開發貢獻| F[原始碼建置]
    
    C --> G[5分鐘完成]
    D --> H[更快的相依管理]
    E --> I[環境隔離 可重現]
    F --> J[可定制 參與開發]

方式對比表

方式 安裝速度 磁碟佔用 更新便捷 隔離性 推薦場景
npm -g ⭐⭐⭐ 較大 簡單 無 快速體驗、臨時測試
pnpm -g ⭐⭐⭐⭐ 小 簡單 無 日常使用、多專案
bun -g ⭐⭐⭐⭐⭐ 小 簡單 無 追求極致速度
Docker ⭐⭐ 中 中等 完全 正式部署、團隊協作
原始碼 ⭐ 大 複雜 無 開發貢獻、深度定制

方式一：npm 全域安裝（推薦新手）

安裝步驟

# 1. 安裝最新穩定版
npm install -g openclaw@latest

# 2. 驗證安裝
openclaw --version
# 輸出範例: 2026.2.26

# 3. 查看說明
openclaw --help

安裝後目錄結構

/usr/local/lib/node_modules/openclaw/  # 全域安裝目錄
├── bin/
│   └── openclaw                        # 可執行檔
├── lib/
│   └── ...                             # 核心函式庫
└── package.json

~/.openclaw/                            # 使用者資料目錄（首次執行建立）
├── openclaw.json                       # 主設定檔
├── credentials/                       # 頻道憑證儲存
├── workspace/                          # Agent 工作區
│   ├── AGENTS.md                      # Agent 行為指導
│   ├── SOUL.md                        # Agent 人格設定
│   └── skills/                        # 自訂技能
└── logs/                              # 日誌目錄

執行入門精靈

# 啟動互動式設定精靈
openclaw onboard --install-daemon

精靈會引導你完成：

sequenceDiagram
    participant U as 使用者
    participant W as 精靈
    participant S as 系統
    
    U->>W: 啟動 onboard
    W->>U: 選擇模型提供商
    U->>W: 選擇 Anthropic
    W->>U: 輸入 API Key
    U->>W: 貼上 Key
    W->>U: 選擇 Gateway 連接埠
    U->>W: 18789（預設）
    W->>U: 是否安裝守護程序？
    U->>W: 是
    W->>S: 建立 systemd/launchd 服務
    S-->>W: 安裝成功
    W-->>U: 設定完成！

方式二：pnpm 安裝（推薦日常）

安裝 pnpm

# 使用 npm 安裝 pnpm
npm install -g pnpm

# 或使用獨立腳本
curl -fsSL https://get.pnpm.io/install.sh | sh -

安裝 OpenClaw

# 使用 pnpm 安裝
pnpm add -g openclaw@latest

# 驗證
openclaw --version

pnpm 的優勢

特性 說明
硬連結儲存 全域儲存，多專案共用相依套件，節省磁碟
更快安裝 比 npm 快 2-3 倍
嚴格相依 避免幽靈相依問題
monorepo 支援 原生支援多套件管理

方式三：bun 安裝（追求極致速度）

安裝 bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# 或使用 npm
npm install -g bun

安裝 OpenClaw

# 使用 bun 安裝
bun add -g openclaw@latest

# 驗證
openclaw --version

bun 的優勢

特性 說明
極速安裝 比 npm 快 20-30 倍
內建打包器 原生支援 TypeScript
內建測試 Jest 相容的測試框架
Node.js 相容 大部分 npm 套件可直接使用

方式四：Docker 部署（推薦正式環境）

取得映像

# 拉取最新映像
docker pull openclaw/openclaw:latest

# 或指定版本
docker pull openclaw/openclaw:2026.2

基礎執行

# 最小化執行
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=your_key_here \
  openclaw/openclaw:latest

# 查看日誌
docker logs -f openclaw

Docker Compose 設定

建立 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # 或使用設定檔
      # - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

啟動服務：

# 建立 .env 檔案
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# 啟動
docker-compose up -d

# 查看狀態
docker-compose ps

# 查看日誌
docker-compose logs -f

Docker 網路設定

# docker-compose.yml 擴充設定
services:
  openclaw:
    # ... 其他設定
    networks:
      - openclaw-net

  # 可選：反向代理
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

方式五：原始碼建置（開發者）

複製倉庫

# 複製主倉庫
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安裝相依套件（推薦 pnpm）
pnpm install

# 建置
pnpm build

# 執行
pnpm openclaw onboard

開發模式

# 開發模式（自動重新載入）
pnpm gateway:watch

# 執行測試
pnpm test

# 程式碼檢查
pnpm lint

設定檔詳解

設定優先順序

CLI 參數 > 環境變數 > 設定檔 > 預設值

目錄結構

~/.openclaw/
├── openclaw.json           # 主設定檔
├── openclaw.json.backup    # 自動備份
├── credentials/            # 敏感憑證（自動加密）
│   ├── telegram.json
│   ├── whatsapp.json
│   └── discord.json
├── workspace/              # Agent 工作區
│   ├── AGENTS.md          # 全域行為指導
│   ├── SOUL.md            # Agent 人格
│   ├── TOOLS.md           # 自訂工具說明
│   ├── USER.md            # 使用者資訊
│   └── skills/            # 技能目錄
│       ├── gmail/
│       │   └── SKILL.md
│       └── calendar/
│           └── SKILL.md
├── sessions/              # 工作階段資料
├── logs/                  # 日誌檔案
│   ├── gateway.log
│   └── agent.log
└── cache/                 # 快取資料

最小設定

~/.openclaw/openclaw.json：

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

完整設定範例

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verboseLevel": "normal"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "guilds": {}
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      }
    ]
  },
  "webhooks": [],
  "cron": []
}

設定項說明

設定項 類型 預設值 說明
agent.model string claude-opus-4-6 使用的 AI 模型
agent.thinkingLevel string normal 思考深度：off/minimal/low/medium/high/xhigh
gateway.port number 18789 Gateway 監聽連接埠
gateway.bind string loopback 綁定位址：loopback/all
channels.*.dmPolicy string pairing DM 策略：pairing/open
agents.defaults.sandbox.mode string off 沙箱模式：off/non-main/always

環境變數

OpenClaw 支援透過環境變數覆蓋設定：

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# 頻道設定
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export DISCORD_BOT_TOKEN="..."

# Gateway 設定
export OPENCLAW_PORT=18789
export OPENCLAW_BIND="loopback"

啟動與驗證

啟動 Gateway

# 前景執行（除錯模式）
openclaw gateway --verbose

# 背景執行（守護程序）
openclaw gateway --daemon

# 指定連接埠
openclaw gateway --port 18790

驗證執行狀態

# 檢查健康狀態
openclaw doctor

# 輸出範例：
# ✓ Node.js version: v22.12.0
# ✓ OpenClaw version: 2026.2.26
# ✓ Gateway running on port 18789
# ✓ API key configured
# ✓ Workspace directory exists

存取 Web 控制台

啟動 Gateway 後，開啟瀏覽器存取：

http://127.0.0.1:18789

你將看到 Web Control UI：

頁面 功能
Chat 與 Agent 對話
Sessions 管理工作階段
Config 設定管理
Nodes 裝置節點管理
Logs 日誌查看

測試對話

# 命令列測試
openclaw agent --message "你好，請介紹一下你自己"

# 輸出範例：
# 你好！我是你的 OpenClaw 助手。我可以幫你...

常見問題排查

問題 1：連接埠被佔用

症狀：

Error: EADDRINUSE: address already in use 127.0.0.1:18789

解決方案：

# 尋找佔用連接埠的程序
lsof -i :18789
# 或
netstat -tlnp | grep 18789

# 終止程序
kill -9 <PID>

# 或使用其他連接埠
openclaw gateway --port 18790

問題 2：API Key 無效

症狀：

Error: Invalid API key

解決方案：

# 驗證設定
openclaw config get agent.model

# 檢查環境變數
echo $ANTHROPIC_API_KEY

# 重新設定
openclaw onboard

問題 3：Node 版本過低

症狀：

Error: OpenClaw requires Node.js >= 22.0.0

解決方案：

# 使用 nvm 切換版本
nvm install 22
nvm use 22
nvm alias default 22

# 驗證
node --version

問題 4：權限問題

症狀：

Error: EACCES: permission denied

解決方案：

# 修復 npm 權限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# 或使用 nvm 管理 Node.js（推薦）

問題 5：Docker 網路問題

症狀：

Error: Cannot connect to Gateway from container

解決方案：

# 檢查網路
docker network ls
docker network inspect bridge

# 使用 host 網路
docker run --network host ...

# 或正確對應連接埠
docker run -p 127.0.0.1:18789:18789 ...

問題 6：憑證遺失

症狀：

Warning: Telegram credentials not found

解決方案：

# 重新登入頻道
openclaw channels login telegram

# 檢查憑證檔案
ls ~/.openclaw/credentials/

# 備份憑證
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

問題 7：記憶體不足

症狀：

Error: JavaScript heap out of memory

解決方案：

# 增加 Node.js 記憶體限制
export NODE_OPTIONS="--max-old-space-size=8192"
openclaw gateway

# 或在 Docker 中
docker run -e NODE_OPTIONS="--max-old-space-size=8192" ...

更新與維護

更新 OpenClaw

# npm 更新
npm update -g openclaw@latest

# pnpm 更新
pnpm update -g openclaw@latest

# Docker 更新
docker pull openclaw/openclaw:latest
docker-compose up -d

# 檢查版本
openclaw --version

切換發布通道

# 穩定版（推薦）
openclaw update --channel stable

# 測試版
openclaw update --channel beta

# 開發版（最新功能，可能不穩定）
openclaw update --channel dev

備份與還原

# 備份設定
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 還原設定
tar -xzvf openclaw-backup-20260226.tar.gz -C ~/

# 僅備份關鍵檔案
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

下一步

恭喜！你已經成功搭建了 OpenClaw 環境。接下來：

  1. 設定第一個頻道 → 下一篇：頻道設定入門
  2. 安裝第一個 Skill → 在 Web UI 中搜尋並安裝
  3. 定制 Agent 人格 → 編輯 ~/.openclaw/workspace/SOUL.md

本篇小結：

  • 掌握了 5 種安裝方式及其適用場景
  • 理解了設定檔結構和優先順序
  • 學會了啟動驗證和常見問題排查
  • 了解了更新維護的基本操作

更新記錄：

  • 2026-02-26：初版發布，基於 OpenClaw v2026.2

系列導航：