OpenClaw 常用指令完整參考：從基礎操作到進階 CLI 技巧

OpenClaw 自 2026 年初正式開源以來，迅速成為最受矚目的 AI 代理框架之一。^[3] 相比於其他依賴網頁介面或桌面應用程式的同類工具，OpenClaw 從設計之初便以命令列介面（CLI）作為主要操作入口，這使得它天然適合與現有的 DevOps 工具鏈、Shell 腳本及自動化排程整合。

然而，許多初次接觸 OpenClaw 的使用者面臨同一個困境：官方文件雖然完整，但指令數量龐大，不同版本之間的旗標也略有差異，很難在短時間內建立系統性的認識。^[1] 本文的目標正是填補這個缺口：從安裝到診斷，從模型管理到 Agent Teams，提供一份兼顧廣度與深度的 OpenClaw 指令完整參考。

無論你是剛剛透過 curl -sSL https://get.openclaw.ai | bash 完成安裝的新手，還是已在生產環境中運行多個 Gateway 的資深用戶，這份參考文件都能幫助你找到需要的指令，並理解它背後的設計邏輯。

一、命令列介面概覽

1.1 OpenClaw CLI 的設計哲學

OpenClaw 的 CLI 設計深受 Unix 哲學影響：每個子指令只做一件事，且做好這件事。^[4] 整體指令架構採用 openclaw <noun> <verb> 的格式，名詞代表操作對象（如 gateway、model、skill），動詞代表執行動作（如 start、add、list）。這種一致性讓使用者在熟悉任何一個子指令後，都能直覺推測其他指令的用法。

與 GUI 工具相比，CLI 的優勢在於：

• 可組合性（Composability）： 透過管道（pipe）與重導向，可以將多個指令串接成複雜的工作流。
• 可腳本化（Scriptability）： 所有操作均可納入 Shell 腳本、Makefile 或 CI/CD Pipeline。
• 可遠端執行： 透過 SSH 即可管理遠端伺服器上的 OpenClaw 實例，無需開放 GUI 遠端桌面。
• 版本可控： 指令與設定檔可納入 Git 版本控制，實現基礎設施即程式碼（IaC）。

1.2 全域說明與版本資訊

在任何子指令後加上 --help 或 -h 旗標，都可取得該指令的說明文字。頂層說明可用以下方式取得：

# 顯示所有可用的頂層指令與簡要說明
openclaw --help

# 縮寫形式，效果相同
openclaw -h

# 顯示特定子指令的說明
openclaw gateway --help
openclaw model add --help

執行 openclaw --help 後，你會看到類似以下的輸出結構：

OpenClaw AI Agent Framework v1.4.2

Usage: openclaw <command> [subcommand] [flags]

Core Commands:
  gateway     Manage the OpenClaw Gateway (WebSocket server)
  model       Configure AI model providers and connections
  channel     Manage communication channels (WhatsApp, Telegram, etc.)
  skill       Install, remove, and manage Skills
  hook        Configure event-driven Hooks
  agent       Manage Agent Teams and task assignments
  doctor      Diagnose and fix environment issues

Utility Commands:
  version     Show version information
  update      Update OpenClaw to the latest version
  config      View and edit global configuration
  logs        View and filter runtime logs

Run 'openclaw <command> --help' for more information on a command.
Documentation: https://docs.openclaw.ai

查詢版本資訊的指令如下：

# 顯示完整版本資訊（含相依套件版本）
openclaw version

# 僅顯示版本號（適合用於腳本判斷）
openclaw version --short

# 輸出範例：
# openclaw v1.4.2 (darwin/arm64, go1.22.1)
# Gateway Protocol: 3.1
# Skills API: 2.0

1.3 全域旗標說明

以下旗標可套用於大多數 OpenClaw 指令：

--config <path>     指定設定檔路徑（預設：~/.openclaw/config.yaml）
--log-level <level> 設定日誌等級（debug|info|warn|error，預設：info）
--output <format>   輸出格式（text|json|yaml，預設：text）
--no-color          停用彩色輸出（適合管道輸出與 CI 環境）
--quiet, -q         只輸出最必要的資訊，抑制進度提示
--verbose, -v       輸出詳細除錯資訊
--timeout <s>       指令逾時秒數（預設：30）

二、安裝與環境管理

2.1 初次安裝

OpenClaw 提供一鍵安裝腳本，支援 macOS（Intel/Apple Silicon）、Linux（x86_64/arm64）及 Windows（WSL2）。^[2]

# 標準一鍵安裝（推薦）
curl -sSL https://get.openclaw.ai | bash

# 指定安裝特定版本
curl -sSL https://get.openclaw.ai | bash -s -- --version 1.4.2

# 僅下載安裝腳本，不立即執行（用於審查腳本內容）
curl -sSL https://get.openclaw.ai -o install.sh
cat install.sh  # 審查完畢後再執行
bash install.sh

# 透過 Homebrew 安裝（macOS）
brew tap openclaw/tap
brew install openclaw

# 透過 apt 安裝（Debian/Ubuntu）
curl -fsSL https://packages.openclaw.ai/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/openclaw.gpg
echo "deb [signed-by=/etc/apt/keyrings/openclaw.gpg] https://packages.openclaw.ai/apt stable main" | sudo tee /etc/apt/sources.list.d/openclaw.list
sudo apt update && sudo apt install openclaw

安裝完成後，執行以下指令確認環境是否就緒：

openclaw doctor

# 正常輸出範例：
# ✓ OpenClaw v1.4.2 installed at /usr/local/bin/openclaw
# ✓ Configuration directory: ~/.openclaw/
# ✓ Gateway binary present
# ✓ Node.js v20.11.0 detected (required for Skills runtime)
# ✓ No port conflicts detected on 18789
# ✓ System ready

2.2 更新與解除安裝

# 更新至最新穩定版
openclaw update

# 更新至指定版本
openclaw update --version 1.5.0

# 查看可用版本清單
openclaw update --list

# 預覽更新內容（不實際執行）
openclaw update --dry-run

# 解除安裝 OpenClaw（保留設定檔）
openclaw uninstall

# 解除安裝並清除所有設定與資料
openclaw uninstall --purge

2.3 環境變數設定

OpenClaw 支援透過環境變數覆蓋設定檔中的參數，這在 Docker 容器化部署或 CI/CD 環境中特別有用：

# 核心環境變數
export OPENCLAW_CONFIG_DIR="~/.openclaw"        # 設定目錄
export OPENCLAW_LOG_LEVEL="info"                # 日誌等級
export OPENCLAW_GATEWAY_PORT="18789"            # Gateway 埠號
export OPENCLAW_GATEWAY_HOST="127.0.0.1"        # Gateway 監聽位址
export OPENCLAW_DEFAULT_MODEL="claude-opus-4"  # 預設模型

# API 金鑰（建議透過環境變數傳入，避免明文寫入設定檔）
export OPENCLAW_ANTHROPIC_API_KEY="sk-ant-..."
export OPENCLAW_OPENAI_API_KEY="sk-..."
export OPENCLAW_DEEPSEEK_API_KEY="sk-..."

# 查看目前所有生效的環境設定
openclaw config env

2.4 全域設定管理

# 查看目前設定（YAML 格式）
openclaw config show

# 以 JSON 格式輸出設定
openclaw config show --output json

# 取得特定設定值
openclaw config get gateway.port
openclaw config get default_model

# 設定特定值
openclaw config set gateway.port 18790
openclaw config set log_level debug

# 重設某項設定為預設值
openclaw config reset gateway.port

# 開啟設定檔（使用 $EDITOR）
openclaw config edit

# 驗證設定檔語法
openclaw config validate

三、Gateway 管理指令

3.1 Gateway 概念說明

Gateway 是 OpenClaw 四層架構的核心樞紐，負責在 WebSocket 端點 ws://127.0.0.1:18789 上接收來自 Channels 的訊息，並將任務分發給對應的 Nodes 執行。^[7] 在使用任何 Channel 或 Skill 之前，Gateway 必須處於運行狀態。

3.2 啟動、停止與重啟

# 在前景啟動 Gateway（按 Ctrl+C 可停止）
openclaw gateway start

# 在背景以 daemon 模式啟動
openclaw gateway start --daemon

# 指定埠號啟動
openclaw gateway start --port 18790

# 指定監聽位址（0.0.0.0 允許外部連線）
openclaw gateway start --host 0.0.0.0 --port 18789

# 停止正在運行的 Gateway
openclaw gateway stop

# 強制終止（若正常停止無效時使用）
openclaw gateway stop --force

# 重啟 Gateway（應用新設定時常用）
openclaw gateway restart

# 優雅重啟（等待現有任務完成後再重啟）
openclaw gateway restart --graceful

3.3 Gateway 狀態查詢

# 查看 Gateway 運行狀態
openclaw gateway status

# 輸出範例：
# Gateway Status: RUNNING
# PID: 12483
# Uptime: 2h 34m 12s
# Endpoint: ws://127.0.0.1:18789
# Connected Nodes: 3
# Active Channels: 2 (telegram, discord)
# Tasks Processed: 847
# Queue Depth: 0

# 監控模式（每 2 秒刷新一次）
openclaw gateway status --watch

# 查看 Gateway 資源使用狀況
openclaw gateway status --resources

# 以 JSON 格式輸出（適合整合監控系統）
openclaw gateway status --output json

3.4 日誌查看

# 查看 Gateway 即時日誌（類似 tail -f）
openclaw gateway logs

# 查看最後 N 行日誌
openclaw gateway logs --tail 100

# 篩選特定等級的日誌
openclaw gateway logs --level error
openclaw gateway logs --level warn

# 依時間範圍篩選
openclaw gateway logs --since "2026-02-22T09:00:00"
openclaw gateway logs --since "1h"    # 最近一小時
openclaw gateway logs --since "30m"   # 最近 30 分鐘

# 搜尋特定關鍵字
openclaw gateway logs --grep "timeout"
openclaw gateway logs --grep "ERROR" --tail 50

# 將日誌輸出到檔案
openclaw gateway logs --tail 1000 > gateway-$(date +%Y%m%d).log

3.5 Gateway 埠號設定與衝突處理

# 檢查埠號是否被占用
openclaw gateway check-port

# 指定特定埠號進行檢查
openclaw gateway check-port --port 18789

# 取得目前 Gateway 的完整連線資訊
openclaw gateway info

# 輸出範例：
# WebSocket Endpoint: ws://127.0.0.1:18789
# REST API: http://127.0.0.1:18788
# Dashboard: http://127.0.0.1:18787 (if enabled)
# TLS: disabled
# Auth: token-based

四、模型設定指令

4.1 新增模型

OpenClaw 支援多種主流 AI 模型供應商，包括 Anthropic Claude、OpenAI GPT、DeepSeek 以及透過 Ollama 運行的本地模型。

# 互動式新增模型（引導式問答流程）
openclaw model add

# 新增 Anthropic Claude 模型
openclaw model add \
--provider anthropic \
--name claude-opus-4 \
--api-key "sk-ant-api03-..." \
--alias "my-claude"

# 新增 OpenAI GPT 模型
openclaw model add \
--provider openai \
--name gpt-4o \
--api-key "sk-proj-..." \
--alias "my-gpt4o"

# 新增 DeepSeek 模型
openclaw model add \
--provider deepseek \
--name deepseek-chat \
--api-key "sk-..." \
--alias "deepseek-v3"

# 新增 Ollama 本地模型（無需 API 金鑰）
openclaw model add \
--provider ollama \
--name llama3.2 \
--endpoint "http://localhost:11434" \
--alias "local-llama"

# 新增自訂 OpenAI 相容端點（如 LM Studio、vLLM）
openclaw model add \
--provider openai-compatible \
--name my-model \
--endpoint "http://localhost:1234/v1" \
--api-key "not-needed" \
--alias "lm-studio"

4.2 列出與管理模型

# 列出所有已設定的模型
openclaw model list

# 輸出範例：
# ALIAS           PROVIDER     NAME                STATUS   DEFAULT
# my-claude       anthropic    claude-opus-4       ✓        ✓
# my-gpt4o        openai       gpt-4o              ✓
# deepseek-v3     deepseek     deepseek-chat       ✓
# local-llama     ollama       llama3.2            ✓

# 以 JSON 格式列出（適合腳本使用）
openclaw model list --output json

# 查看特定模型的詳細資訊
openclaw model info my-claude

# 設定預設模型
openclaw model set-default my-claude

# 移除模型設定
openclaw model remove my-gpt4o

# 移除前確認（互動式）
openclaw model remove my-gpt4o --confirm

4.3 測試模型連線

# 測試預設模型的連線狀態
openclaw model test

# 測試特定模型
openclaw model test my-claude

# 發送自訂測試訊息
openclaw model test my-claude --prompt "請用一句話說明你的功能"

# 測試所有已設定的模型
openclaw model test --all

# 測試並顯示延遲數據
openclaw model test my-claude --benchmark

# 輸出範例：
# Testing model: my-claude (anthropic/claude-opus-4)
# ✓ API connection: OK (latency: 342ms)
# ✓ Token streaming: OK
# ✓ Context window: 200,000 tokens
# ✓ Function calling: supported
# Response: 我是 Claude，由 Anthropic 開發的 AI 助手。

4.4 模型參數調整

# 為特定模型設定預設參數
openclaw model configure my-claude \
--temperature 0.7 \
--max-tokens 4096 \
--top-p 0.95

# 查看模型目前設定的參數
openclaw model info my-claude --params

# 重設模型參數為供應商預設值
openclaw model configure my-claude --reset

五、Channel 管理指令

5.1 Channel 概念與支援清單

Channel 是 OpenClaw 與外部通訊平台的串接層，負責接收用戶訊息並將回覆送出。目前支援的 Channel 包括 Telegram、WhatsApp Business API、Discord、Slack、LINE、Microsoft Teams 及 Web Chat Widget。

5.2 新增 Channel

# 互動式新增 Channel
openclaw channel add

# 新增 Telegram Bot Channel
openclaw channel add \
--type telegram \
--name my-telegram-bot \
--token "7123456789:AAF..." \
--alias "tg-bot"

# 新增 Discord Bot Channel
openclaw channel add \
--type discord \
--name my-discord-bot \
--token "MTIz..." \
--guild-id "123456789" \
--alias "dc-bot"

# 新增 Slack App Channel
openclaw channel add \
--type slack \
--name my-slack-app \
--bot-token "xoxb-..." \
--signing-secret "abc..." \
--alias "slack-app"

# 新增 WhatsApp Business API Channel
openclaw channel add \
--type whatsapp \
--name wa-business \
--phone-number-id "123..." \
--access-token "EAAx..." \
--verify-token "my-verify-token" \
--alias "wa-bot"

# 新增 Web Chat Widget Channel
openclaw channel add \
--type webchat \
--name website-chat \
--allowed-origins "https://example.com,https://www.example.com" \
--alias "web-widget"

5.3 列出與管理 Channel

# 列出所有已設定的 Channel
openclaw channel list

# 輸出範例：
# ALIAS        TYPE        NAME                STATUS    CONNECTED
# tg-bot       telegram    my-telegram-bot     enabled   ✓
# dc-bot       discord     my-discord-bot      enabled   ✓
# slack-app    slack       my-slack-app        disabled
# wa-bot       whatsapp    wa-business         enabled   ✓

# 查看特定 Channel 的詳細資訊
openclaw channel info tg-bot

# 停用 Channel（不刪除設定）
openclaw channel disable slack-app

# 重新啟用 Channel
openclaw channel enable slack-app

# 移除 Channel 設定
openclaw channel remove slack-app

# 更新 Channel 設定（如 Token 過期需更換）
openclaw channel update tg-bot --token "新的 Bot Token"

5.4 測試 Channel 連線

# 測試特定 Channel 的連線狀態
openclaw channel test tg-bot

# 輸出範例：
# Testing channel: tg-bot (telegram)
# ✓ Bot token: valid
# ✓ Webhook registered: OK (https://gateway.example.com/webhook/tg-bot)
# ✓ Gateway connection: OK
# ✓ Message routing: OK
# Bot Info: @MyAwesomeBot (ID: 7123456789)

# 透過 Channel 發送測試訊息（需指定目標 Chat ID）
openclaw channel test tg-bot --send-test --chat-id "123456"

# 測試所有已啟用的 Channel
openclaw channel test --all

# 查看 Channel 的訊息統計
openclaw channel stats tg-bot
openclaw channel stats --all --since "24h"

5.5 Webhook 設定

# 設定 Telegram Webhook（需要公開 HTTPS URL）
openclaw channel webhook set tg-bot --url "https://your-domain.com/webhook/telegram"

# 移除 Webhook（改用 long polling 模式）
openclaw channel webhook remove tg-bot

# 查看 Webhook 狀態
openclaw channel webhook status tg-bot

# 在本地開發時使用 ngrok tunnel
openclaw channel tunnel start --channel tg-bot --port 18789

六、Skills 管理指令

6.1 Skills 概念說明

Skills 是 OpenClaw 的功能擴充機制，類似於插件系統。每個 Skill 都是一個獨立的模組，定義了 AI 代理可以執行的特定能力，例如網頁搜尋、程式碼執行、檔案管理、API 呼叫等。^[5]

6.2 瀏覽 Skills 市集

# 列出 Skills 市集中的所有可用 Skills
openclaw skill search

# 搜尋特定 Skill（按名稱或關鍵字）
openclaw skill search "web search"
openclaw skill search --tag "productivity"
openclaw skill search --tag "coding"

# 查看 Skill 詳細資訊（含版本歷史、評分、安裝數）
openclaw skill info web-search

# 輸出範例：
# Skill: web-search v2.1.0
# Author: openclaw-team
# Description: Enable web search via Brave Search API
# Rating: 4.8/5.0 (2,341 installs)
# Required Config: BRAVE_API_KEY
# Compatible: OpenClaw >= 1.3.0
# Tags: search, web, research

6.3 安裝與移除 Skills

# 安裝 Skill（從官方市集）
openclaw skill install web-search

# 安裝特定版本
openclaw skill install [email protected]

# 安裝時指定設定值
openclaw skill install web-search --set BRAVE_API_KEY="your-key"

# 從 GitHub 安裝自訂 Skill
openclaw skill install github:username/my-custom-skill

# 從本地目錄載入 Skill（開發模式）
openclaw skill load /path/to/my-skill --dev

# 移除 Skill
openclaw skill uninstall web-search

# 移除並清除相關設定
openclaw skill uninstall web-search --purge

6.4 管理已安裝的 Skills

# 列出所有已安裝的 Skills
openclaw skill list

# 輸出範例：
# NAME              VERSION   STATUS    AUTO-LOAD   LAST-USED
# web-search        2.1.0     enabled   yes         2m ago
# code-runner       1.5.2     enabled   yes         1h ago
# file-manager      1.2.0     enabled   yes         never
# calendar-sync     0.9.1     disabled  no

# 查看特定 Skill 的詳細狀態
openclaw skill info web-search --installed

# 啟用 / 停用 Skill
openclaw skill enable calendar-sync
openclaw skill disable file-manager

# 更新特定 Skill 到最新版
openclaw skill update web-search

# 更新所有已安裝的 Skills
openclaw skill update --all

# 查看有更新可用的 Skills
openclaw skill update --check

# 查看 Skill 的使用統計
openclaw skill stats web-search

6.5 Skill 設定管理

# 查看 Skill 的所有設定項目
openclaw skill config web-search

# 設定 Skill 的特定參數
openclaw skill config web-search set BRAVE_API_KEY "your-api-key"
openclaw skill config web-search set MAX_RESULTS 10
openclaw skill config web-search set SAFE_SEARCH true

# 查看特定設定值
openclaw skill config web-search get MAX_RESULTS

# 重設 Skill 設定為預設值
openclaw skill config web-search reset

# 驗證 Skill 設定是否正確
openclaw skill validate web-search

七、Hooks 相關指令

7.1 Hooks 概念說明

Hooks 是 OpenClaw 的事件驅動自動化機制。當系統中發生特定事件（如收到訊息、任務完成、錯誤發生、Agent 狀態改變）時，對應的 Hook 會自動觸發預設的動作，例如呼叫 Webhook、執行腳本、發送通知等。^[6]

7.2 列出與查看 Hooks

# 列出所有已設定的 Hooks
openclaw hook list

# 輸出範例：
# NAME                  EVENT               ACTION       STATUS
# notify-on-error       gateway.error       webhook      enabled
# log-completions       task.complete       script       enabled
# alert-rate-limit      model.rate_limit    webhook      enabled
# daily-digest          schedule.daily      http         disabled

# 查看特定 Hook 的詳細設定
openclaw hook info notify-on-error

# 查看所有可用的事件類型
openclaw hook events

7.3 建立 Hooks

# 互動式建立 Hook
openclaw hook create

# 建立 Webhook Hook（事件發生時呼叫外部 URL）
openclaw hook create \
--name notify-on-error \
--event gateway.error \
--action webhook \
--url "https://hooks.slack.com/services/..." \
--method POST

# 建立腳本 Hook（事件發生時執行本地腳本）
openclaw hook create \
--name log-completions \
--event task.complete \
--action script \
--script "/path/to/log-task.sh"

# 建立帶有過濾條件的 Hook
openclaw hook create \
--name alert-high-tokens \
--event model.response \
--action webhook \
--url "https://monitoring.example.com/alert" \
--filter "response.tokens > 10000"

# 建立定時 Hook（Cron 排程）
openclaw hook create \
--name daily-report \
--event schedule.cron \
--cron "0 9 * * 1-5" \
--action http \
--url "https://api.example.com/generate-report" \
--method POST \
--body '{"type": "daily_summary"}'

7.4 管理 Hooks

# 啟用 Hook
openclaw hook enable daily-report

# 停用 Hook（保留設定）
openclaw hook disable daily-report

# 修改 Hook 設定
openclaw hook update notify-on-error --url "https://new-webhook-url.com"

# 移除 Hook
openclaw hook remove notify-on-error

# 手動觸發 Hook（用於測試）
openclaw hook trigger notify-on-error

# 查看 Hook 執行歷史
openclaw hook history notify-on-error
openclaw hook history notify-on-error --tail 20

# 查看 Hook 執行統計
openclaw hook stats
openclaw hook stats notify-on-error

7.5 測試 Hooks

# 測試 Hook 設定是否正確（不實際觸發動作）
openclaw hook test notify-on-error --dry-run

# 發送測試事件並觀察 Hook 回應
openclaw hook test notify-on-error --payload '{"error": "test error", "code": 500}'

# 輸出範例：
# Testing hook: notify-on-error
# Event: gateway.error
# Action: webhook → https://hooks.slack.com/services/...
# ✓ Payload validated
# ✓ Webhook URL reachable
# ✓ Test delivery: HTTP 200 OK (latency: 187ms)
# Hook test passed.

八、診斷與除錯指令

8.1 openclaw doctor — 環境健康診斷

openclaw doctor 是 OpenClaw 最重要的診斷工具，它會系統性地檢查安裝環境、相依套件、設定檔、API 連線及 Gateway 狀態，並給出明確的問題報告與修復建議。

# 執行完整環境診斷
openclaw doctor

# 完整診斷輸出範例：
# ══════════════════════════════════════════
#  OpenClaw Doctor — Environment Check
# ══════════════════════════════════════════
#
# [Installation]
# ✓ OpenClaw v1.4.2 installed (/usr/local/bin/openclaw)
# ✓ Config directory exists (~/.openclaw/)
# ✓ Config file valid (config.yaml)
#
# [Dependencies]
# ✓ Node.js v20.11.0 (required >= 18.0.0)
# ✓ npm v10.2.3
# ✗ ffmpeg: not found (required by media-processor skill)
#
# [Gateway]
# ✓ Gateway process: running (PID 12483)
# ✓ Port 18789: listening
# ✓ WebSocket connection: OK
#
# [Models]
# ✓ my-claude (anthropic/claude-opus-4): connected
# ✗ my-gpt4o (openai/gpt-4o): authentication failed
# ✓ local-llama (ollama/llama3.2): connected
#
# [Skills]
# ✓ web-search v2.1.0: healthy
# ✓ code-runner v1.5.2: healthy
# ✗ media-processor v1.0.0: missing dependency (ffmpeg)
#
# Summary: 3 issues found
# Run 'openclaw doctor --fix' to attempt automatic repair.

8.2 openclaw doctor --fix — 自動修復

# 嘗試自動修復所有偵測到的問題
openclaw doctor --fix

# 修復過程輸出範例：
# ══════════════════════════════════════════
#  OpenClaw Doctor — Auto Fix
# ══════════════════════════════════════════
#
# Fixing 3 issues...
#
# [1/3] ffmpeg: not found
#   → Attempting installation via Homebrew...
#   ✓ ffmpeg installed successfully (v6.1.1)
#
# [2/3] my-gpt4o: authentication failed
#   → API key appears invalid or expired
#   ✗ Cannot auto-fix: manual action required
#   Suggestion: Run 'openclaw model update my-gpt4o --api-key NEW_KEY'
#
# [3/3] media-processor: missing dependency
#   → Retrying after ffmpeg installation...
#   ✓ media-processor dependency resolved
#
# Results: 2/3 issues fixed automatically
# 1 issue requires manual intervention (see above)

# 僅修復特定類別的問題
openclaw doctor --fix --only dependencies
openclaw doctor --fix --only models

# 預覽修復動作（不實際執行）
openclaw doctor --fix --dry-run

# 詳細模式（顯示每個修復步驟的詳細日誌）
openclaw doctor --fix --verbose

8.3 進階診斷指令

# 執行完整的系統資訊收集（用於回報 Bug）
openclaw doctor --report

# 這會生成一份脫敏的診斷報告，可安全分享給技術支援

# 僅檢查特定元件
openclaw doctor --check gateway
openclaw doctor --check models
openclaw doctor --check skills
openclaw doctor --check channels
openclaw doctor --check hooks

# 檢查網路連線與防火牆設定
openclaw doctor --check network

# 輸出範例（網路檢查）：
# [Network]
# ✓ Outbound HTTPS (443): OK
# ✓ api.anthropic.com: reachable (latency: 156ms)
# ✓ api.openai.com: reachable (latency: 243ms)
# ✗ localhost:11434 (Ollama): connection refused
#   → Is Ollama running? Try: ollama serve

# 檢查並清理過期的快取與暫存檔
openclaw doctor --clean-cache

# 查看詳細的 Gateway 健康資訊
openclaw gateway health --verbose

8.4 日誌分析與除錯

# 查看完整的系統日誌（所有元件）
openclaw logs

# 依元件篩選
openclaw logs --component gateway
openclaw logs --component skills
openclaw logs --component channels

# 即時追蹤錯誤日誌
openclaw logs --level error --follow

# 匯出日誌以供分析（自動壓縮）
openclaw logs --export --since "24h" --output logs-$(date +%Y%m%d).tar.gz

# 在日誌中搜尋特定 Task ID
openclaw logs --task-id "task_abc123"

# 查看特定 Channel 的訊息日誌
openclaw logs --channel tg-bot --since "1h"

# 效能分析（查看慢查詢與慢任務）
openclaw logs --slow-threshold 5s

8.5 常見錯誤與診斷方式

# 埠號衝突偵測
openclaw gateway check-port --port 18789

# 若確認有衝突，查詢占用程序
openclaw gateway check-port --port 18789 --show-process

# 測試 WebSocket 連線
openclaw gateway ping

# 輸出範例：
# Pinging ws://127.0.0.1:18789...
# PONG received (latency: 2ms)
# Gateway is healthy.

# 重置 Gateway 連線狀態（不重啟程序）
openclaw gateway reconnect --all

# 查看任務佇列狀態
openclaw gateway queue status

# 清除卡住的任務佇列
openclaw gateway queue clear --stuck

九、Agent Teams 指令

9.1 Agent Teams 概念說明

Agent Teams 是 OpenClaw 的多代理協作功能，允許多個 AI 代理以角色分工的方式協同完成複雜任務。每個 Team 由一個 Orchestrator Agent 負責協調，其他 Worker Agents 負責執行具體的子任務。

9.2 建立與管理 Agent Teams

# 互動式建立 Agent Team
openclaw agent team create

# 建立 Agent Team（指定名稱與成員模型）
openclaw agent team create \
--name "research-team" \
--orchestrator my-claude \
--description "負責市場研究與報告生成的代理團隊"

# 列出所有 Agent Teams
openclaw agent team list

# 輸出範例：
# NAME              AGENTS   STATUS    TASKS-COMPLETED
# research-team     4        idle      127
# dev-team          3        active    845
# support-team      2        idle      2,341

# 查看 Team 詳細資訊
openclaw agent team info research-team

# 修改 Team 設定
openclaw agent team update research-team --description "新的描述"

# 刪除 Team
openclaw agent team remove research-team

9.3 管理 Team 成員

# 新增 Agent 到 Team
openclaw agent add \
--team research-team \
--name "web-researcher" \
--model my-claude \
--skills "web-search,summarizer" \
--role "researcher"

openclaw agent add \
--team research-team \
--name "report-writer" \
--model my-gpt4o \
--skills "document-creator,formatter" \
--role "writer"

# 列出 Team 中的所有 Agents
openclaw agent list --team research-team

# 輸出範例：
# NAME             ROLE          MODEL        SKILLS                  STATUS
# web-researcher   researcher    my-claude    web-search,summarizer   idle
# report-writer    writer        my-gpt4o     document-creator        idle
# data-analyst     analyst       deepseek-v3  code-runner,charts      idle

# 更新 Agent 設定
openclaw agent update web-researcher --skills "web-search,summarizer,translator"

# 從 Team 移除 Agent
openclaw agent remove web-researcher --team research-team

9.4 任務分配與監控

# 向 Agent Team 指派任務
openclaw agent task assign \
--team research-team \
--task "分析 2026 年 Q1 台灣 AI 新創市場趨勢，並生成 PDF 報告" \
--priority high \
--deadline "2026-02-23T18:00:00"

# 列出所有任務
openclaw agent task list

# 查看特定任務狀態
openclaw agent task status task_abc123

# 輸出範例：
# Task ID: task_abc123
# Status: IN_PROGRESS (67%)
# Team: research-team
# Started: 2026-02-22 14:30:00
# Assigned to: web-researcher (searching), report-writer (waiting)
# Steps completed: 4/6
# Current step: Analyzing search results

# 取消任務
openclaw agent task cancel task_abc123

# 監控所有活躍任務（即時更新）
openclaw agent task list --active --watch

# 查看 Agent 的任務歷史
openclaw agent history web-researcher --tail 20

十、實用指令組合技巧

10.1 Shell 腳本整合

OpenClaw 的 CLI 設計讓它非常適合嵌入 Shell 腳本中。以下是幾個常見的腳本整合模式：

#!/bin/bash
# 範例：每日 Gateway 健康檢查腳本

set -euo pipefail

LOG_FILE="/var/log/openclaw-health.log"
WEBHOOK_URL="https://hooks.slack.com/services/..."

# 取得 JSON 格式的狀態
STATUS=$(openclaw gateway status --output json)
IS_RUNNING=$(echo "$STATUS" | jq -r '.running')
QUEUE_DEPTH=$(echo "$STATUS" | jq -r '.queue_depth')

if [ "$IS_RUNNING" != "true" ]; then
echo "$(date): Gateway 未運行，嘗試重啟..." >> "$LOG_FILE"
openclaw gateway start --daemon
sleep 5
openclaw doctor --fix --only gateway
fi

if [ "$QUEUE_DEPTH" -gt 100 ]; then
echo "$(date): 任務佇列過深 ($QUEUE_DEPTH)，發送警報..." >> "$LOG_FILE"
curl -s -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d "{\"text\": \"OpenClaw 警報：任務佇列深度 $QUEUE_DEPTH\"}"
fi

echo "$(date): 健康檢查完成" >> "$LOG_FILE"

10.2 管道組合技巧

# 取得所有已啟用且有更新的 Skills，並自動更新
openclaw skill list --output json | \
jq -r '.[] | select(.status == "enabled") | .name' | \
xargs -I{} openclaw skill update {}

# 批次測試所有模型，並篩選出失敗的
openclaw model list --output json | \
jq -r '.[].alias' | \
xargs -P 4 -I{} sh -c 'openclaw model test {} --output json | jq ". + {\"alias\": \"{}\"}"' | \
jq -r 'select(.status != "ok") | .alias'

# 匯出所有 Hook 設定（用於備份）
openclaw hook list --output json > hooks-backup-$(date +%Y%m%d).json

# 從備份還原 Hooks
cat hooks-backup-20260222.json | \
jq -c '.[]' | \
while read hook; do
openclaw hook create --from-json "$hook"
done

10.3 Cron 排程整合

# 編輯 Crontab
crontab -e

# 加入以下排程任務：

# 每天早上 9 點執行環境健康診斷並自動修復
0 9 * * 1-5 /usr/local/bin/openclaw doctor --fix --quiet >> /var/log/openclaw-doctor.log 2>&1

# 每週日凌晨 2 點更新所有 Skills
0 2 * * 0 /usr/local/bin/openclaw skill update --all --quiet

# 每 5 分鐘檢查 Gateway 狀態
*/5 * * * * /usr/local/bin/openclaw gateway status --quiet || /usr/local/bin/openclaw gateway start --daemon

# 每天備份 OpenClaw 設定
0 3 * * * tar -czf "/backup/openclaw-$(date +\%Y\%m\%d).tar.gz" ~/.openclaw/

10.4 Docker 容器環境使用技巧

# Dockerfile 範例片段
# FROM ubuntu:22.04
# RUN curl -sSL https://get.openclaw.ai | bash
# ENV OPENCLAW_GATEWAY_HOST=0.0.0.0
# ENV OPENCLAW_LOG_LEVEL=info
# EXPOSE 18789 18788
# CMD ["openclaw", "gateway", "start"]

# Docker Compose 健康檢查設定範例
# healthcheck:
#   test: ["CMD", "openclaw", "gateway", "ping", "--quiet"]
#   interval: 30s
#   timeout: 10s
#   retries: 3
#   start_period: 10s

# 在 Docker 容器中執行指令
docker exec -it openclaw-container openclaw gateway status
docker exec -it openclaw-container openclaw doctor

# 傳遞 API 金鑰給容器（不硬編碼在映像中）
docker run -d \
-e OPENCLAW_ANTHROPIC_API_KEY="sk-ant-..." \
-e OPENCLAW_GATEWAY_HOST="0.0.0.0" \
-p 18789:18789 \
openclaw/openclaw:latest

10.5 CI/CD Pipeline 整合

# GitHub Actions 範例工作流程片段
# name: Deploy OpenClaw Config
# on:
#   push:
#     branches: [main]
#     paths: ['.openclaw/**']
#
# jobs:
#   deploy:
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#       - name: Install OpenClaw
#         run: curl -sSL https://get.openclaw.ai | bash
#       - name: Validate Config
#         run: openclaw config validate
#       - name: Run Doctor Check
#         run: openclaw doctor --check-only
#       - name: Deploy to Production
#         run: |
#           openclaw skill update --all
#           openclaw gateway restart --graceful

# 在 CI 環境中使用的實用旗標
openclaw --no-color --quiet gateway status   # 抑制彩色輸出與進度提示
openclaw --output json model list            # JSON 輸出便於程式解析
openclaw --timeout 60 model test my-claude   # 增加逾時時間避免 CI 提前失敗

十一、常見問題與疑難排解

11.1 安裝相關問題

問題：執行 curl -sSL https://get.openclaw.ai | bash 後，找不到 openclaw 指令。

# 解決方案：重新載入 Shell 設定
source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh

# 或者手動將安裝路徑加入 PATH
export PATH="$HOME/.openclaw/bin:$PATH"

# 確認安裝位置
which openclaw
ls -la ~/.openclaw/bin/

問題：在公司網路環境下，安裝腳本無法下載（SSL 憑證錯誤或代理封鎖）。

# 方案一：設定 HTTP 代理
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
curl -sSL https://get.openclaw.ai | bash

# 方案二：手動下載二進位檔（從 GitHub Releases）
curl -L "https://github.com/openclaw/openclaw/releases/latest/download/openclaw-darwin-arm64.tar.gz" -o openclaw.tar.gz
tar -xzf openclaw.tar.gz
sudo mv openclaw /usr/local/bin/
chmod +x /usr/local/bin/openclaw

11.2 Gateway 無法啟動

問題：執行 openclaw gateway start 後出現 bind: address already in use。

# 確認哪個程序占用了埠號
openclaw gateway check-port --show-process

# 或使用系統工具
lsof -i :18789   # macOS/Linux
netstat -ano | findstr :18789   # Windows

# 方案一：更換 Gateway 埠號
openclaw gateway start --port 18790
openclaw config set gateway.port 18790

# 方案二：終止占用埠號的程序（確認是多餘的 OpenClaw 程序）
openclaw gateway stop --force
# 若仍無法停止：
kill $(lsof -ti:18789)

問題：Gateway 啟動後立即崩潰，日誌顯示 permission denied。

# 修復設定目錄權限
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/config.yaml

# 重新執行診斷
openclaw doctor --fix --only permissions

11.3 模型連線失敗

問題：openclaw model test my-claude 顯示 authentication failed。

# 確認 API 金鑰是否正確設定
openclaw model info my-claude --show-key   # 顯示部分遮蔽的金鑰

# 更新 API 金鑰
openclaw model update my-claude --api-key "新的 API 金鑰"

# 測試 API 金鑰格式（Anthropic 金鑰以 sk-ant- 開頭）
openclaw model validate-key --provider anthropic --key "sk-ant-..."

問題：Ollama 本地模型連線失敗。

# 確認 Ollama 服務是否運行
ollama list   # 應顯示已下載的模型
ollama serve  # 若未運行，先啟動服務

# 確認 Ollama 端點是否可達
curl http://localhost:11434/api/version

# 在 OpenClaw 中更新 Ollama 端點設定
openclaw model update local-llama --endpoint "http://localhost:11434"
openclaw model test local-llama

11.4 Skills 相關問題

問題：Skill 安裝失敗，顯示 incompatible version。

# 查看當前 OpenClaw 版本與 Skill 相容性要求
openclaw version
openclaw skill info problematic-skill

# 若 OpenClaw 版本過舊，先更新主程式
openclaw update

# 若需要使用舊版 Skill
openclaw skill install [email protected]   # 指定相容的舊版本

問題：已安裝的 Skill 在 Agent 對話中無法被調用。

# 確認 Skill 已啟用
openclaw skill list | grep my-skill

# 若 Skill 被停用，重新啟用
openclaw skill enable my-skill

# 重啟 Gateway 使 Skill 載入生效
openclaw gateway restart --graceful

# 驗證 Skill 在 Gateway 中是否正確載入
openclaw gateway status --skills

11.5 取得技術支援

# 生成技術支援診斷報告（自動脫敏，可安全分享）
openclaw doctor --report --output support-report.txt

# 查看 OpenClaw 版本與環境資訊（回報 Issue 時需附上）
openclaw version --verbose

# 輸出範例：
# OpenClaw v1.4.2
# OS: darwin (arm64)
# Go: go1.22.1
# Config: ~/.openclaw/config.yaml
# Gateway: running (PID 12483)
# Installed Skills: 5
# Active Channels: 3

結語

OpenClaw 的 CLI 設計體現了現代開發者工具的最佳實踐：高度一致的命名規則、豐富的旗標選項、以及對腳本化與自動化的深度支持。^[8] 從日常的 openclaw doctor 健康診斷，到複雜的多代理任務分配，每一個操作都被設計成可以在不依賴 GUI 的情況下完成。

本文整理的指令涵蓋了絕大多數日常使用場景，但 OpenClaw 的生態系仍在快速演進中。建議讀者定期查閱官方 CLI 參考文件，^[1] 並在每次版本更新後執行 openclaw doctor 確保環境持續健康。

對於希望深入了解 OpenClaw 架構原理的讀者，可以參考本系列的前篇文章，了解 Gateway、Nodes、Channels、Skills 四層架構的設計邏輯，以及如何從零開始部署一套完整的 OpenClaw 環境。掌握了 CLI 工具之後，你將能夠更自信地將 AI 代理能力整合進任何現有的技術基礎設施中。