Skip to main content

OpenClaw

Introduction

OpenClaw 是一款開源的個人 AI 數位助理，讓你在各種通訊平台上擁有專屬的智慧管家。無論是自動回覆訊息、整理資訊、串接工作流程，OpenClaw 都能幫你搞定。

Resources

Installation

With Docker
git clone https://github.com/openclaw/openclaw
cd openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
Debian 13

Run as root

# Install Node.js
# Run as root
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt install nodejs

Run as non-root

# Switch to non-root account
# NOTE: Node.js 22.14 or newer is required for openclaw
su - <your-username>
node -v
npm --version

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
npm prefix -g
export PATH="$HOME/.npm-global/bin:$PATH"

Edit: ~/.bashrc

export PATH="$HOME/.npm-global/bin:$PATH"

Install openclaw

npm install -g openclaw@latest
openclaw onboard --install-daemon

Post-Install

訂製 AI 助理

使用 3 個檔案量身訂製助理

    SOUL.md — 身份、記憶、溝通風格、關鍵規則 AGENTS.md — 核心使命、技術交付物、工作流程 IDENTITY.md — 名稱與簡介
    Timezone
    openclaw config set agents.defaults.userTimezone "Asia/Taipei"

    CLI Commands

    Check Service
    docker compose run --rm openclaw-cli status
docker compose run --rm openclaw-cli gateway status
    Pairing required

    Approve the device

    docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <request-id>
    Model Configuration
    # 主要模型設置
openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

# 備用模型設置
openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

    Telegram

    Configuration

    Create a Bot from Telegram

    1. Open Telegram
    2. Chat with @BotFather 
    3. Run /newbot , follow prompts to create your bot, and save the token.
      • Bot Name: <whatever>
      • Bot Username: <unique-name and must end in 'bot'> 

    Go to OpenClaw CLI

    docker compose run --rm openclaw-cli channels add --channel telegram --token "<bot-token>"

    Go to Telegram

    1. Open you-bot
    2. Send "Hi"
    3. Getting a pairing code "XXXXX"

    Go to OpenClaw CLI

    docker compose run --rm openclaw-cli pairing list telegram
docker compose run --rm openclaw-cli pairing approve telegram XXXXX

    Done

    Bot Commands
    • /btw : 題外話，在不打斷目前對話（主任務），可以臨時問一個小問題，其內容不會進入主對話的上下文。
    • /subagent : 子代理，在不打斷目前對話（主任務），呼叫另一個代理執行其他任務，其任務結果會納入主任務的上下文。
    • /new : 新對話，建立新的對話（任務），全新的上下文，可節省 Token 用量。

    Gateway

    Local only (default)
    • 遠端存取可以使用 SSH Port Forwarding

    ~/.openclaw/openclaw.json :

      "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ]
    },
    "auth": {
      "mode": "token",
      "token": "YOUR-OPENCLAW-TOKEN"
    },
    Tailscale

    openclaw.json 的 tailscale 功能不適用在 Docker 環境。

    1. Tailscale Console: Enable HTTPS Certicficates
    2. OpenClaw Host: Run
      1. sudo tailscale serve --bg --https=443 127.0.0.1:18789 
      2. tailscale serve status 
    3. Change ~/.openclaw/openclaw.json as follows
    4. Connect to tailnet, and then visit https://your-openclaw-device.tailnet-domain/?token=YOUR-TOKEN ,  such as https://dockers-vm.tailcb58c9.ts.net/ ?token=YOUR-TOKEN

    ~/.openclaw/openclaw.json :

    • mode: local
    • bind: loopback
    • trustedProxies: ["127.0.0.1", "::1"]
    • allowedOrigins: https://yourdevice.tailnet-domain
      "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "trustedProxies": ["127.0.0.1", "::1"],
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "https://yourdevice.tailnet-domain"
      ]
    },
    "auth": {
      "mode": "token",
      "token": "YOUR-OPENCLAW-TOKEN"
    },

    openclaw.json 的 tailscale 模式比較（不適用在 Docker 環境）

    模式 存取範圍 HTTPS 認證 適用場景
    serve 限 tailnet 自動 Tailscale identity headers/Token/Password 個人使用
    funnel 公眾網路 自動 Password Webhook
    bind: "tailnet" 限 tailnet 無 Token/Password 低延遲
    off 限 localhost 無 Token SSH Port Forward

    Skill

    3rd Party

    FAQ

    Context limit exceeded

    Context limit exceeded. I've reset our conversation to start fresh - please try again.

    To prevent this, increase your compaction buffer by setting agents.defaults.compaction.reserveTokensFloor to 20000 or higher in your config.

    Cause: 目前使用模型的 Context Window 與 壓縮緩衝參數不匹配。

    Solution: 以 Gemma4-31B-it 為例

    Edit: ~/.openclaw/openclaw.json

    • contextWindow : 128000
    • reserveTokensFloor : 40000
      "models": {
    "mode": "merge",
    "providers": {
      "custom-cpamc": {
        "baseUrl": "http://192.168.31.89:8317/v1",
        "api": "openai-completions",
        "apiKey": "sk-cvgaT1Z3EhJRBB5pu",
        "models": [
          {
            "id": "gemma-4-31b-it",
            "name": "gemma-4-31b-it (Custom Provider)",
            "contextWindow": 128000,
            "maxTokens": 4096,
            "input": [
              "text"
            ],
      "agents": {
    "defaults": {
      "workspace": "/home/alang/.openclaw/workspace",
      "model": {
        "primary": "custom-cpamc/gemma-4-31b-it"
      },
      "models": {
        "custom-cpamc/gemma-4-31b-it": {}
      },
      "compaction": {
        "reserveTokensFloor": 40000
      }
    }
  },

    或者使用 CLI

    openclaw config set agents.defaults.compaction.reserveTokensFloor 40000
    LLM idle timeout
    The model did not produce a response before the LLM idle timeout. Please try again, or increase agents.defaults.llm.idleTimeoutSeconds in your config (set to 0 to disable).

    Solution:

    openclaw config set agents.defaults.timeoutSeconds 600
openclaw config set agents.defaults.llm.idleTimeoutSeconds 600
    gateway connect failed
    gateway connect failed: GatewayClientRequestError: pairing required

    檢查有無 pending devices

    openclaw devices list
openclaw devices list --json

    Back to top