Hello Claw: Panduan Dasar OpenClaw

#Lampiran B: Penjelasan detail tentang file konfigurasi

Sistem konfigurasi OpenClaw fleksibel dan kuat. Lampiran ini menganalisis setiap item konfigurasi secara rinci berdasarkan dokumen resmi.

Sumber referensi: OpenClaw Configuration

Lokasi file konfigurasi

OpenClaw membaca file konfigurasi JSON5 opsional:

~/.openclaw/openclaw.json          # 主配置文件
~/.openclaw/.env                   # 环境变量文件

Jika file konfigurasi tidak ada, OpenClaw menggunakan default aman.

Ikhtisar struktur file konfigurasi

json5

{
  agents: { ... },           // Agent 配置
  channels: { ... },         // 渠道配置
  gateway: { ... },          // 网关配置
  session: { ... },          // 会话配置
  messages: { ... },         // 消息配置
  tools: { ... },            // 工具配置
  skills: { ... },           // 技能配置
  cron: { ... },             // 定时任务配置
  hooks: { ... },            // Webhook 配置
  bindings: [...],           // 绑定规则
  env: { ... },              // 环境变量
}

1. Konfigurasi agen (agen)

1.1 Konfigurasi default (agents.defaults)

json5

{
  agents: {
    defaults: {
      // 工作空间路径
      workspace: "~/.openclaw/workspace",
      
      // 模型配置
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      },
      
      // 模型目录（用于 /model 命令）
      models: {
        "anthropic/claude-sonnet-4-5": {
          alias: "Sonnet"
        },
        "openai/gpt-5.2": {
          alias: "GPT"
        }
      },
      
      // 图片最大尺寸（像素）
      imageMaxDimensionPx: 1200,
      
      // 心跳配置
      heartbeat: {
        every: "30m",        // 30分钟、2小时等
        target: "last",      // last | whatsapp | telegram | discord | none
        directPolicy: "allow" // allow | block
      },
      
      // 沙盒配置
      sandbox: {
        mode: "non-main",    // off | non-main | all
        scope: "agent"       // session | agent | shared
      },
      
      // 工具配置
      tools: {
        enabled: true,
        profile: "full"
      }
    }
  }
}

Deskripsi item konfigurasi:

Barang konfigurasi	Ketik	Nilai bawaan	Deskripsi
`workspace`	tali	~/.openclaw/ruang kerja	Direktori kerja agen
`model.primary`	tali	-	Model utama, format: penyedia/model
`model.fallbacks`	susunan	[]	Daftar model pengganti
`imageMaxDimensionPx`	nomor	1200	Transkripsi Gambar/Alat Ukuran Zoom Gambar
`heartbeat.every`	tali	-	Interval detak jantung (misalnya 30m, 2 jam)
`sandbox.mode`	tali	mati	mode kotak pasir

1.2 Konfigurasi multi-Agen (agents.list)

json5

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  }
}

2. Konfigurasi saluran (saluran)

2.1 Konfigurasi kebijakan DM umum

Semua saluran berbagi pola strategi DM yang sama:

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",      // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],    // 仅用于 allowlist/open
    },
    
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],
      groups: {
        "*": {
          requireMention: true
        }
      }
    },
    
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["discord:123"]
    },
    
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

Opsi Kebijakan DM:

Strategi	Deskripsi
`pairing`	Pengirim yang tidak dikenal menerima kode penyandingan satu kali dan memerlukan persetujuan
`allowlist`	Hanya pengirim di AllowFrom
`open`	Izinkan semua DM masuk (memerlukan izinkanDari: ["*"])
`disabled`	Abaikan semua DM

2.2 Obrolan grup menyebutkan kontrol gerbang

json5

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      }
    ]
  },
  
  channels: {
    whatsapp: {
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

3. Konfigurasi gerbang (gateway)

json5

{
  gateway: {
    port: 18789,
    bind: "loopback",           // loopback | lan | tailnet | auto | custom
    auth: {
      mode: "token",            // token | password
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
      allowTailscale: true
    },
    tailscale: {
      mode: "off",              // off | serve | funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",           // hybrid | hot | restart | off
      debounceMs: 300
    }
  }
}

Opsi alamat pengikatan:

nilai	deskripsi
`loopback`	Akses lokal saja (127.0.0.1)
`lan`	LAN dapat diakses
`tailnet`	Jaringan Skala Ekor
`auto`	Deteksi otomatis
`custom`	Alamat khusus

Mode isi ulang panas:

Pola	Perilaku
`hybrid`	Terapkan perubahan aman secara panas, mulai ulang perubahan penting secara otomatis (default)
`hot`	Hanya terapkan perubahan aman saat panas, peringatan log jika diperlukan restart
`restart`	Mulai ulang gateway untuk setiap perubahan konfigurasi
`off`	Nonaktifkan pemantauan file

4. Konfigurasi sesi (sesi)

json5

{
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer
    
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0
    },
    
    reset: {
      mode: "daily",            // daily | idle | manual
      atHour: 4,
      idleMinutes: 120
    }
  }
}

Opsi Cakupan DM:

nilai	deskripsi
`main`	Sesi bersama
`per-peer`	Sesi mandiri per rekan
`per-channel-peer`	Per saluran - sesi independen ke rekan (disarankan multi-pengguna)
`per-account-channel-peer`	Sesi independen per rekan saluran akun

5. Konfigurasi pesan (pesan)

json5

{
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

6. Konfigurasi alat (tools)

json5

{
  tools: {
    profile: "full",              // messaging | default | coding | full | all
    enabled: true,
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"
      }
    }
  }
}

File Konfigurasi Alat:

Profil	Deskripsi
`messaging`	Chat saja, tanpa alat
`default`	Perangkat dasar
`coding`	Perangkat pemrograman
`full`	Perangkat lengkap
`all`	Semua alat

7. Konfigurasi keterampilan (skill)

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  }
}

8. Konfigurasi tugas terjadwal (cron)

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    }
  }
}

9. Konfigurasi webhook (hook)

json5

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: {
          path: "gmail"
        },
        action: "agent",
        agentId: "main",
        deliver: true
      }
    ]
  }
}

10. Konfigurasi pengikatan (binding)

json5

{
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

11. Konfigurasi variabel lingkungan (env)

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

Sumber variabel lingkungan (berdasarkan prioritas):

Variabel lingkungan proses induk
File .env di direktori kerja saat ini
~/.openclaw/.env file (penggantian global)

Tidak ada yang menimpa variabel lingkungan yang ada.

12. Pemisahan konfigurasi ($termasuk)

Gunakan $include untuk mengatur konfigurasi besar:

json5

// ~/.openclaw/openclaw.json
{
  gateway: {
    port: 18789
  },
  agents: {
    $include: "./agents.json5"
  },
  broadcast: {
    $include: [
      "./clients/a.json5",
      "./clients/b.json5"
    ]
  }
}

Peraturan:

File tunggal: ganti objek yang ada
Array file: penggabungan dalam secara berurutan (terbaru dulu)
Kunci saudara: gabungkan setelah penyertaan (timpa nilai yang disertakan)
Bersarang termasuk: mendukung hingga kedalaman 10 level
Jalur relatif: diselesaikan relatif terhadap file yang memuatnya

13. Penggantian variabel lingkungan

Variabel lingkungan referensi dalam nilai string konfigurasi:

json5

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  models: {
    providers: {
      custom: {
        apiKey: "${CUSTOM_API_KEY}"
      }
    }
  }
}

Peraturan:

Hanya cocok dengan nama huruf besar: [A-Z_][A-Z0-9_]*
Variabel yang hilang/kosong menimbulkan kesalahan saat memuat
Gunakan $${VAR} untuk keluar ke keluaran literal
Juga valid dalam file $include
Penggantian sebaris: "${BASE}/v1" → "https://api.example.com/v1"

14. Sertifikat SecretRef

Bidang objek SecretRef yang didukung:

json5

{
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "env",
          provider: "default",
          id: "OPENAI_API_KEY"
        }
      }
    }
  },
  
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  },
  
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount"
      }
    }
  }
}

jenis sumber:

env: variabel lingkungan
file: Isi file
exec: Output eksekusi perintah

15. Contoh konfigurasi lengkap

15.1 Konfigurasi minimum

json5

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

15.2 Konfigurasi pengembangan lokal

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "ollama/llama3.2"
      }
    }
  },
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "dev-token"
    }
  }
}

15.3 Konfigurasi penerapan server

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  },
  
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  },
  
  gateway: {
    port: 18789,
    bind: "lan",
    auth: {
      mode: "password",
      password: "${GATEWAY_PASSWORD}"
    }
  },
  
  session: {
    dmScope: "per-channel-peer"
  }
}

15.4 Konfigurasi Multi-Agen

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    },
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  },
  
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

16. Metode pengeditan konfigurasi

Interactive Wizard

bash

openclaw onboard          # 完整设置向导
openclaw configure        # 配置向导

Perintah CLI

bash

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config file      # 查看配置文件路径
openclaw config validate  # 验证配置

Konsol web

Buka http://127.0.0.1:18789 dan gunakan tab Config.

Sunting secara langsung

Edit ~/.openclaw/openclaw.json secara langsung dan gateway akan secara otomatis menerapkan perubahan.

17. Verifikasi ketat

OpenClaw hanya menerima konfigurasi yang sama persis dengan skema. Kunci yang tidak dikenal, tipe yang salah format, atau nilai yang tidak valid dapat menyebabkan gateway menolak untuk memulai.

Ketika verifikasi gagal:

Gerbang tidak akan dimulai
Hanya perintah diagnostik yang tersedia (openclaw doctor, openclaw logs, openclaw health, openclaw status)
Jalankan openclaw doctor untuk melihat masalah spesifik
Jalankan openclaw doctor --fix untuk menerapkan perbaikan

18. Petunjuk isi ulang panas

Mendukung konfigurasi aplikasi panas

Kategori	Bidang	Perlu memulai ulang?
Saluran	`channels.*`	Tidak
Agen & Model	`agent`, `agents`, `models`, `routing`	Tidak
Otomatisasi	`hooks`, `cron`, `agent.heartbeat`	Tidak
Percakapan & Pesan	`session`, `messages`	Tidak
Alat & Media	`tools`, `browser`, `skills`, `audio`, `talk`	Tidak
UI & Lainnya	`ui`, `logging`, `identity`, `bindings`	Tidak

Konfigurasi yang memerlukan restart

Kategori	Bidang
Server Gerbang	`gateway.*` (Port, Pengikatan, Otentikasi, Skala Ekor, TLS, HTTP)
Infrastruktur	`discovery`, `canvasHost`, `plugins`

Pengecualian: gateway.reload dan gateway.remote perubahan tidak memicu restart.

Tips: Penjelasan konfigurasi mendetail ini didasarkan pada dokumentasi resmi OpenClaw. Untuk referensi lengkap, silakan kunjungi docs.openclaw.ai/gateway/configuration.

Lokasi file konfigurasi ​

Ikhtisar struktur file konfigurasi ​

1. Konfigurasi agen (agen) ​

1.1 Konfigurasi default (agents.defaults) ​

1.2 Konfigurasi multi-Agen (agents.list) ​

2. Konfigurasi saluran (saluran) ​

2.1 Konfigurasi kebijakan DM umum ​

2.2 Obrolan grup menyebutkan kontrol gerbang ​

3. Konfigurasi gerbang (gateway) ​

4. Konfigurasi sesi (sesi) ​

5. Konfigurasi pesan (pesan) ​

6. Konfigurasi alat (tools) ​

7. Konfigurasi keterampilan (skill) ​

8. Konfigurasi tugas terjadwal (cron) ​

9. Konfigurasi webhook (hook) ​

10. Konfigurasi pengikatan (binding) ​

11. Konfigurasi variabel lingkungan (env) ​

12. Pemisahan konfigurasi ($termasuk) ​

13. Penggantian variabel lingkungan ​

14. Sertifikat SecretRef ​

15. Contoh konfigurasi lengkap ​

15.1 Konfigurasi minimum ​

15.2 Konfigurasi pengembangan lokal ​

15.3 Konfigurasi penerapan server ​

15.4 Konfigurasi Multi-Agen ​

16. Metode pengeditan konfigurasi ​

Interactive Wizard ​

Perintah CLI ​

Konsol web ​

Sunting secara langsung ​

17. Verifikasi ketat ​

18. Petunjuk isi ulang panas ​

Mendukung konfigurasi aplikasi panas ​

Konfigurasi yang memerlukan restart ​

Lokasi file konfigurasi

Ikhtisar struktur file konfigurasi

1. Konfigurasi agen (agen)

1.1 Konfigurasi default (agents.defaults)

1.2 Konfigurasi multi-Agen (agents.list)

2. Konfigurasi saluran (saluran)

2.1 Konfigurasi kebijakan DM umum

2.2 Obrolan grup menyebutkan kontrol gerbang

3. Konfigurasi gerbang (gateway)

4. Konfigurasi sesi (sesi)

5. Konfigurasi pesan (pesan)

6. Konfigurasi alat (tools)

7. Konfigurasi keterampilan (skill)

8. Konfigurasi tugas terjadwal (cron)

9. Konfigurasi webhook (hook)

10. Konfigurasi pengikatan (binding)

11. Konfigurasi variabel lingkungan (env)

12. Pemisahan konfigurasi ($termasuk)

13. Penggantian variabel lingkungan

14. Sertifikat SecretRef

15. Contoh konfigurasi lengkap

15.1 Konfigurasi minimum

15.2 Konfigurasi pengembangan lokal

15.3 Konfigurasi penerapan server

15.4 Konfigurasi Multi-Agen

16. Metode pengeditan konfigurasi

Interactive Wizard

Perintah CLI

Konsol web

Sunting secara langsung

17. Verifikasi ketat

18. Petunjuk isi ulang panas

Mendukung konfigurasi aplikasi panas

Konfigurasi yang memerlukan restart