Configuration 🔧

OpenClaw đọc file cấu hình JSON5 tùy chọn từ ~/.openclaw/openclaw.json (cho phép comment và dấu phẩy cuối).

Nếu file không tồn tại, OpenClaw sẽ dùng các giá trị mặc định an toàn (embedded Pi agent + session theo người gửi + workspace ~/.openclaw/workspace). Các bạn thường chỉ cần file cấu hình để:

  • giới hạn ai có thể kích hoạt bot (channels.whatsapp.allowFrom, channels.telegram.allowFrom, v.v.)
  • kiểm soát allowlist nhóm + hành vi mention (channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
  • tùy chỉnh message prefix (messages)
  • đặt workspace cho agent (agents.defaults.workspace hoặc agents.list[].workspace)
  • tinh chỉnh cài đặt mặc định của embedded agent (agents.defaults) và hành vi session (session)
  • đặt identity cho từng agent (agents.list[].identity)

Mới làm quen với cấu hình? Xem hướng dẫn Configuration Examples để có các ví dụ đầy đủ kèm giải thích chi tiết nhé!

Strict config validation

OpenClaw chỉ chấp nhận các cấu hình khớp hoàn toàn với schema. Các key không xác định, kiểu dữ liệu sai, hoặc giá trị không hợp lệ sẽ khiến Gateway từ chối khởi động để đảm bảo an toàn.

Khi validation thất bại:

  • Gateway không boot được.
  • Chỉ các lệnh chẩn đoán được phép chạy (ví dụ: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
  • Chạy openclaw doctor để xem các vấn đề cụ thể.
  • Chạy openclaw doctor --fix (hoặc --yes) để áp dụng migration/sửa chữa.

Doctor không bao giờ ghi thay đổi trừ khi các bạn chủ động chọn --fix/--yes.

Schema + UI hints

Gateway cung cấp JSON Schema representation của config qua config.schema cho các UI editor. Control UI render form từ schema này, với editor Raw JSON làm phương án dự phòng.

Channel plugin và extension có thể đăng ký schema + UI hint cho config của chúng, để cài đặt channel vẫn dựa trên schema xuyên suốt các app mà không cần hard-code form.

Hint (label, grouping, sensitive field) đi kèm schema để client có thể render form tốt hơn mà không cần hard-code kiến thức về config.

Apply + restart (RPC)

Dùng config.apply để validate + ghi toàn bộ config và restart Gateway trong một bước. Nó ghi restart sentinel và ping session hoạt động cuối cùng sau khi Gateway quay lại.

Cảnh báo: config.apply thay thế toàn bộ config. Nếu các bạn chỉ muốn thay đổi vài key, hãy dùng config.patch hoặc openclaw config set. Nhớ backup ~/.openclaw/openclaw.json nhé.

Params:

  • raw (string) — JSON5 payload cho toàn bộ config
  • baseHash (optional) — config hash từ config.get (bắt buộc khi config đã tồn tại)
  • sessionKey (optional) — session key hoạt động cuối cùng cho wake-up ping
  • note (optional) — ghi chú để đưa vào restart sentinel
  • restartDelayMs (optional) — độ trễ trước khi restart (mặc định 2000)

Ví dụ (qua gateway call):

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Partial updates (RPC)

Dùng config.patch để merge một phần cập nhật vào config hiện tại mà không ghi đè các key không liên quan. Nó áp dụng JSON merge patch semantics:

  • object merge đệ quy
  • null xóa một key
  • array thay thế Giống config.apply, nó validate, ghi config, lưu restart sentinel, và lên lịch Gateway restart (với wake tùy chọn khi cung cấp sessionKey).

Params:

  • raw (string) — JSON5 payload chỉ chứa các key cần thay đổi
  • baseHash (required) — config hash từ config.get
  • sessionKey (optional) — session key hoạt động cuối cùng cho wake-up ping
  • note (optional) — ghi chú để đưa vào restart sentinel
  • restartDelayMs (optional) — độ trễ trước khi restart (mặc định 2000)

Ví dụ:

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Build default image một lần với:

scripts/sandbox-setup.sh

Để ngăn bot phản hồi WhatsApp @-mention trong nhóm (chỉ phản hồi các text trigger cụ thể):

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // Allowlist chỉ cho DM; bao gồm số của bạn để bật self-chat mode.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Config Includes ($include)

Tách config của các bạn thành nhiều file bằng directive $include. Điều này hữu ích cho:

  • Tổ chức config lớn (ví dụ: định nghĩa agent theo từng client)
  • Chia sẻ cài đặt chung giữa các môi trường
  • Giữ config nhạy cảm riêng biệt

Basic usage

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // Include một file (thay thế giá trị của key)
  agents: { $include: "./agents.json5" },

  // Include nhiều file (deep-merge theo thứ tự)
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Merge behavior

  • Single file: Thay thế object chứa $include
  • Array of files: Deep-merge các file theo thứ tự (file sau ghi đè file trước)
  • With sibling keys: Sibling key được merge sau include (ghi đè giá trị included)
  • Sibling keys + arrays/primitives: Không hỗ trợ (nội dung included phải là object)
// Sibling key ghi đè giá trị included
{
  $include: "./base.json5", // { a: 1, b: 2 }
  b: 99, // Kết quả: { a: 1, b: 99 }
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Nested includes

Các file included có thể tự chứa directive $include (tối đa 10 cấp):

// clients/mueller.json5
{
  agents: { $include: "./mueller/agents.json5" },
  broadcast: { $include: "./mueller/broadcast.json5" },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Path resolution

  • Relative paths: Resolve tương đối với file đang include
  • Absolute paths: Dùng nguyên như vậy
  • Parent directories: Tham chiếu ../ hoạt động như mong đợi
{ "$include": "./sub/config.json5" }      // relative
{ "$include": "/etc/openclaw/base.json5" } // absolute
{ "$include": "../shared/common.json5" }   // parent dir

Error handling

  • Missing file: Lỗi rõ ràng với đường dẫn đã resolve
  • Parse error: Hiển thị file included nào bị lỗi
  • Circular includes: Phát hiện và báo cáo với chuỗi include
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },

  // Common agent defaults
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" },
    },
    // Merge agent list từ tất cả client
    list: { $include: ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] },
  },

  // Merge broadcast config
  broadcast: {
    $include: ["./clients/mueller/broadcast.json5", "./clients/schmidt/broadcast.json5"],
  },

  channels: { whatsapp: { groupPolicy: "allowlist" } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" },
]
// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"],
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Common options

Env vars + .env

OpenClaw đọc env var từ parent process (shell, launchd/systemd, CI, v.v.).

Ngoài ra, nó load:

  • .env từ thư mục làm việc hiện tại (nếu có)
  • .env fallback toàn cục từ ~/.openclaw/.env (hay $OPENCLAW_STATE_DIR/.env)

Cả hai file .env đều không ghi đè env var đã tồn tại.

Các bạn cũng có thể cung cấp inline env var trong config. Chúng chỉ được áp dụng nếu process env thiếu key đó (quy tắc không ghi đè tương tự):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Xem /environment để biết đầy đủ về precedence và source.

env.shellEnv (optional)

Tiện ích opt-in: nếu bật và không có key nào được set, OpenClaw chạy login shell của bạn và import chỉ các key còn thiếu (không bao giờ ghi đè). Điều này thực chất source shell profile của bạn.

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Env var tương đương:

  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Env var substitution in config

Các bạn có thể tham chiếu environment variable trực tiếp trong bất kỳ giá trị string nào của config bằng cú pháp ${VAR_NAME}. Variable được thay thế khi load config, trước validation.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Quy tắc:

  • Chỉ tên env var viết hoa được khớp: [A-Z_][A-Z0-9_]*
  • Env var thiếu hoặc rỗng sẽ throw error khi load config
  • Escape bằng $${VAR} để output literal ${VAR}
  • Hoạt động với $include (file included cũng được substitution)

Inline substitution:

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1", // → "https://api.example.com/v1"
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Auth storage (OAuth + API keys)

OpenClaw lưu auth profile theo từng agent (OAuth + API key) trong:

  • <agentDir>/auth-profiles.json (mặc định: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

Xem thêm: /concepts/oauth

Legacy OAuth import:

  • ~/.openclaw/credentials/oauth.json (hoặc $OPENCLAW_STATE_DIR/credentials/oauth.json)

Embedded Pi agent duy trì runtime cache tại:

  • <agentDir>/auth.json (tự động quản lý; đừng sửa thủ công)

Legacy agent dir (trước multi-agent):

  • ~/.openclaw/agent/* (được migrate bởi openclaw doctor vào ~/.openclaw/agents/<defaultAgentId>/agent/*)

Override:

  • OAuth dir (chỉ legacy import): OPENCLAW_OAUTH_DIR
  • Agent dir (ghi đè agent root mặc định): OPENCLAW_AGENT_DIR (khuyên dùng), PI_CODING_AGENT_DIR (legacy)

Lần đầu sử dụng, OpenClaw import các entry oauth.json vào auth-profiles.json.

auth

Metadata tùy chọn cho auth profile. Điều này không lưu secret; nó map profile ID tới provider + mode (và email tùy chọn) và định nghĩa thứ tự rotation provider dùng cho failover.

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"],
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.list[].identity

Identity tùy chọn theo từng agent dùng cho default và UX. Được ghi bởi macOS onboarding assistant.

Nếu được set, OpenClaw suy ra các giá trị mặc định (chỉ khi các bạn chưa set rõ ràng):

  • messages.ackReaction từ identity.emoji của agent đang hoạt động (fallback về 👀)
  • agents.list[].groupChat.mentionPatterns từ identity.name/identity.emoji của agent (để “@Samantha” hoạt động trong nhóm trên Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
  • identity.avatar chấp nhận đường dẫn ảnh tương đối workspace hoặc remote URL/data URL. File local phải nằm trong agent workspace.

identity.avatar chấp nhận:

  • Đường dẫn tương đối workspace (phải nằm trong agent workspace)
  • http(s) URL
  • data: URI
{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

wizard

Metadata được ghi bởi CLI wizard (onboard, configure, doctor).

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

logging

  • Log file mặc định: /tmp/openclaw/openclaw-YYYY-MM-DD.log
  • Nếu muốn đường dẫn cố định, set logging.file thành /tmp/openclaw/openclaw.log.
  • Console output có thể tinh chỉnh riêng qua:
    • logging.consoleLevel (mặc định info, tăng lên debug khi --verbose)
    • logging.consoleStyle (pretty | compact | json)
  • Tool summary có thể được redact để tránh lộ secret:
    • logging.redactSensitive (off | tools, mặc định: tools)
    • logging.redactPatterns (mảng regex string; ghi đè mặc định)
{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // Ví dụ: ghi đè mặc định bằng rule của bạn.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi",
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

channels.whatsapp.dmPolicy

Kiểm soát cách xử lý WhatsApp direct chat (DM):

  • "pairing" (mặc định): người gửi không xác định nhận pairing code; owner phải phê duyệt
  • "allowlist": chỉ cho phép người gửi trong channels.whatsapp.allowFrom (hoặc paired allow store)
  • "open": cho phép tất cả inbound DM (yêu cầu channels.whatsapp.allowFrom bao gồm "*")
  • "disabled": bỏ qua tất cả inbound DM

Pairing code hết hạn sau 1 giờ; bot chỉ gửi pairing code khi request mới được tạo. Pending DM pairing request được giới hạn ở 3 mỗi channel theo mặc định.

Pairing approval:

  • openclaw pairing list whatsapp
  • openclaw pairing approve whatsapp <code>

channels.whatsapp.allowFrom

Allowlist các số điện thoại E.164 có thể kích hoạt WhatsApp auto-reply (chỉ DM). Nếu rỗng và channels.whatsapp.dmPolicy="pairing", người gửi không xác định sẽ nhận pairing code. Với nhóm, dùng channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // tùy chọn outbound chunk size (ký tự)
      chunkMode: "length", // tùy chọn chunking mode (length | newline)
      mediaMaxMb: 50, // tùy chọn inbound media cap (MB)
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

channels.whatsapp.sendReadReceipts

Kiểm soát việc đánh dấu tin nhắn WhatsApp đến là đã đọc (blue tick). Mặc định: true.

Self-chat mode luôn bỏ qua read receipt, ngay cả khi bật.

Override theo account: channels.whatsapp.accounts.<id>.sendReadReceipts.

{
  channels: {
    whatsapp: { sendReadReceipts: false },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

channels.whatsapp.accounts (multi-account)

Chạy nhiều WhatsApp account trong một gateway:

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // tùy chọn; giữ id mặc định ổn định
        personal: {},
        biz: {
          // Override tùy chọn. Mặc định: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • Lệnh outbound mặc định dùng account default nếu có; nếu không thì dùng account id được cấu hình đầu tiên (đã sắp xếp).
  • Legacy single-account Baileys auth dir được migrate bởi openclaw doctor vào whatsapp/default.

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

Chạy nhiều account mỗi channel (mỗi account có accountId riêng và name tùy chọn):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • default được dùng khi accountId bị bỏ qua (CLI + routing).
  • Env token chỉ áp dụng cho account default.
  • Cài đặt channel cơ bản (group policy, mention gating, v.v.) áp dụng cho tất cả account trừ khi được override theo từng account.
  • Dùng bindings[].match.accountId để route mỗi account tới agents.defaults khác nhau.

Group chat mention gating (agents.list[].groupChat + messages.groupChat)

Group message mặc định yêu cầu mention (metadata mention hoặc regex pattern). Áp dụng cho WhatsApp, Telegram, Discord, Google Chat, và iMessage group chat.

Mention type:

  • Metadata mention: Native platform @-mention (ví dụ: WhatsApp tap-to-mention). Bị bỏ qua trong WhatsApp self-chat mode (xem channels.whatsapp.allowFrom).
  • Text pattern: Regex pattern được định nghĩa trong agents.list[].groupChat.mentionPatterns. Luôn được kiểm tra bất kể self-chat mode.
  • Mention gating chỉ được thực thi khi mention detection khả thi (native mention hoặc ít nhất một mentionPattern).
{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

messages.groupChat.historyLimit đặt giá trị mặc định toàn cục cho group history context. Channel có thể override bằng channels.<channel>.historyLimit (hoặc channels.<channel>.accounts.*.historyLimit cho multi-account). Set 0 để tắt history wrapping.

DM history limits

DM conversation dùng session-based history được quản lý bởi agent. Các bạn có thể giới hạn số lượng user turn được giữ lại mỗi DM session:

{
  channels: {
    telegram: {
      dmHistoryLimit: 30, // giới hạn DM session ở 30 user turn
      dms: {
        "123456789": { historyLimit: 50 }, // override theo user (user ID)
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Thứ tự resolution:

  1. Per-DM override: channels.<provider>.dms[userId].historyLimit
  2. Provider default: channels.<provider>.dmHistoryLimit
  3. Không giới hạn (giữ tất cả history)

Provider được hỗ trợ: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Per-agent override (ưu tiên khi được set, ngay cả []):

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Mention gating default nằm ở mỗi channel (channels.whatsapp.groups, channels.telegram.groups, channels.imessage.groups, channels.discord.guilds). Khi *.groups được set, nó cũng hoạt động như group allowlist; bao gồm "*" để cho phép tất cả nhóm.

Để phản hồi chỉ các text trigger cụ thể (bỏ qua native @-mention):

{
  channels: {
    whatsapp: {
      // Bao gồm số của bạn để bật self-chat mode (bỏ qua native @-mention).
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // Chỉ các text pattern này sẽ kích hoạt phản hồi
          mentionPatterns: ["reisponde", "@openclaw"],
        },
      },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Group policy (per channel)

Dùng channels.*.groupPolicy để kiểm soát việc group/room message có được chấp nhận hay không:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"],
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: {
          channels: { help: { allow: true } },
        },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • "open": nhóm bỏ qua allowlist; mention-gating vẫn áp dụng.
  • "disabled": chặn tất cả group/room message.
  • "allowlist": chỉ cho phép group/room khớp với allowlist đã cấu hình.
  • channels.defaults.groupPolicy đặt giá trị mặc định khi groupPolicy của provider không được set.
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams dùng groupAllowFrom (fallback: allowFrom rõ ràng).
  • Discord/Slack dùng channel allowlist (channels.discord.guilds.*.channels, channels.slack.channels).
  • Group DM (Discord/Slack) vẫn được kiểm soát bởi dm.groupEnabled + dm.groupChannels.
  • Mặc định là groupPolicy: "allowlist" (trừ khi được ghi đè bởi channels.defaults.groupPolicy); nếu không có allowlist được cấu hình, group message bị chặn.

Multi-agent routing (agents.list + bindings)

Chạy nhiều agent độc lập (workspace riêng, agentDir, session) trong một Gateway. Inbound message được route tới agent qua binding.

  • agents.list[]: override theo từng agent.
    • id: stable agent id (bắt buộc).
    • default: tùy chọn; khi nhiều agent được set, agent đầu tiên thắng và warning được log. Nếu không có agent nào được set, entry đầu tiên trong list là default agent.
    • name: tên hiển thị cho agent.
    • workspace: mặc định ~/.openclaw/workspace-<agentId> (với main, fallback về agents.defaults.workspace).
    • agentDir: mặc định ~/.openclaw/agents/<agentId>/agent.
    • model: model mặc định theo agent, ghi đè agents.defaults.model cho agent đó.
      • dạng string: "provider/model", chỉ ghi đè agents.defaults.model.primary
      • dạng object: { primary, fallbacks } (fallback ghi đè agents.defaults.model.fallbacks; [] tắt global fallback cho agent đó)
    • identity: name/theme/emoji theo agent (dùng cho mention pattern + ack reaction).
    • groupChat: mention-gating theo agent (mentionPatterns).
    • sandbox: cấu hình sandbox theo agent (ghi đè agents.defaults.sandbox).
      • mode: "off" | "non-main" | "all"
      • workspaceAccess: "none" | "ro" | "rw"
      • scope: "session" | "agent" | "shared"
      • workspaceRoot: custom sandbox workspace root
      • docker: docker override theo agent (ví dụ: image, network, env, setupCommand, limit; bị bỏ qua khi scope: "shared")
      • browser: sandboxed browser override theo agent (bị bỏ qua khi scope: "shared")
      • prune: sandbox pruning override theo agent (bị bỏ qua khi scope: "shared")
    • subagents: sub-agent default theo agent.
      • allowAgents: allowlist agent id cho sessions_spawn từ agent này (["*"] = cho phép bất kỳ; mặc định: chỉ cùng agent)
    • tools: tool restriction theo agent (áp dụng trước sandbox tool policy).
      • profile: base tool profile (áp dụng trước allow/deny)
      • allow: mảng tên tool được phép
      • deny: mảng tên tool bị từ chối (deny thắng)
  • agents.defaults: agent default chung (model, workspace, sandbox, v.v.).
  • bindings[]: route inbound message tới agentId.
    • match.channel (bắt buộc)
    • match.accountId (tùy chọn; * = bất kỳ account; bỏ qua = default account)
    • match.peer (tùy chọn; { kind: dm|group|channel, id })
    • match.guildId / match.teamId (tùy chọn; theo channel)

Thứ tự match xác định:

  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId (chính xác, không có peer/guild/team)
  5. match.accountId: "*" (toàn channel, không có peer/guild/team)
  6. default agent (agents.list[].default, nếu không thì entry đầu tiên trong list, nếu không thì "main")

Trong mỗi match tier, entry khớp đầu tiên trong bindings thắng.

Per-agent access profile (multi-agent)

Mỗi agent có thể mang sandbox + tool policy riêng. Dùng điều này để kết hợp các mức truy cập trong một gateway:

  • Full access (personal agent)
  • Read-only tool + workspace
  • No filesystem access (chỉ messaging/session tool)

Xem Multi-Agent Sandbox & Tools để biết precedence và các ví dụ bổ sung.

Full access (không sandbox):

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Read-only tool + read-only workspace:

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro",
        },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Không cho phép truy cập filesystem (chỉ bật các công cụ messaging/session):

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "none",
        },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Ví dụ: hai tài khoản WhatsApp → hai Agent:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

tools.agentToAgent (tùy chọn)

Tính năng nhắn tin giữa các Agent cần được bật thủ công:

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

messages.queue

Kiểm soát cách xử lý tin nhắn đến khi Agent đang chạy.

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

messages.inbound

Gộp các tin nhắn liên tiếp từ cùng một người gửi thành một lượt xử lý của Agent. Debouncing được áp dụng theo từng channel + cuộc hội thoại và sử dụng tin nhắn mới nhất để trả lời/threading.

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • Debounce chỉ gộp tin nhắn văn bản thuần túy; media/attachments được xử lý ngay lập tức.
  • Các lệnh điều khiển (ví dụ /queue, /new) bỏ qua debouncing để giữ độc lập.

commands (xử lý lệnh chat)

Kiểm soát cách bật các lệnh chat trên các connector.

{
  commands: {
    native: "auto", // register native commands when supported (auto)
    text: true, // parse slash commands in chat messages
    bash: false, // allow ! (alias: /bash) (host-only; requires tools.elevated allowlists)
    bashForegroundMs: 2000, // bash foreground window (0 backgrounds immediately)
    config: false, // allow /config (writes to disk)
    debug: false, // allow /debug (runtime-only overrides)
    restart: false, // allow /restart + gateway restart tool
    useAccessGroups: true, // enforce access-group allowlists/policies for commands
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • Lệnh văn bản phải được gửi dưới dạng tin nhắn độc lập và sử dụng dấu / ở đầu (không có alias văn bản thuần túy).
  • commands.text: false tắt phân tích tin nhắn chat để tìm lệnh.
  • commands.native: "auto" (mặc định) bật lệnh native cho Discord/Telegram và tắt cho Slack; các channel không hỗ trợ chỉ dùng text.
  • Đặt commands.native: true|false để bắt buộc tất cả, hoặc ghi đè theo từng channel với channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native (bool hoặc "auto"). false xóa các lệnh đã đăng ký trước đó trên Discord/Telegram khi khởi động; lệnh Slack được quản lý trong ứng dụng Slack.
  • channels.telegram.customCommands thêm các mục menu bot Telegram bổ sung. Tên được chuẩn hóa; xung đột với lệnh native sẽ bị bỏ qua.
  • commands.bash: true bật ! <cmd> để chạy lệnh shell trên host (/bash <cmd> cũng hoạt động như alias). Yêu cầu tools.elevated.enabled và thêm người gửi vào allowlist trong tools.elevated.allowFrom.<channel>.
  • commands.bashForegroundMs kiểm soát thời gian bash chờ trước khi chạy nền. Khi một bash job đang chạy, các yêu cầu ! <cmd> mới sẽ bị từ chối (một lần một).
  • commands.config: true bật /config (đọc/ghi openclaw.json).
  • channels.<provider>.configWrites kiểm soát các thay đổi config được khởi tạo bởi channel đó (mặc định: true). Áp dụng cho /config set|unset cộng với các auto-migration theo provider (thay đổi ID supergroup Telegram, thay đổi ID channel Slack).
  • commands.debug: true bật /debug (ghi đè chỉ runtime).
  • commands.restart: true bật /restart và hành động restart tool của gateway.
  • commands.useAccessGroups: false cho phép lệnh bỏ qua allowlist/policy của access-group.
  • Lệnh slash và directive chỉ được chấp nhận từ người gửi được ủy quyền. Ủy quyền được lấy từ allowlist/pairing của channel cộng với commands.useAccessGroups.

web (WhatsApp web channel runtime)

WhatsApp chạy qua web channel của gateway (Baileys Web). Nó tự động khởi động khi có session được liên kết. Đặt web.enabled: false để tắt mặc định.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

channels.telegram (bot transport)

OpenClaw chỉ khởi động Telegram khi có phần config channels.telegram. Bot token được lấy từ channels.telegram.botToken (hoặc channels.telegram.tokenFile), với TELEGRAM_BOT_TOKEN làm fallback cho tài khoản mặc định. Đặt channels.telegram.enabled: false để tắt khởi động tự động. Hỗ trợ nhiều tài khoản nằm trong channels.telegram.accounts (xem phần multi-account ở trên). Env token chỉ áp dụng cho tài khoản mặc định. Đặt channels.telegram.configWrites: false để chặn ghi config từ Telegram (bao gồm migration ID supergroup và /config set|unset).

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"], // optional; "open" requires ["*"]
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50, // include last N group messages as context (0 disables)
      replyToMode: "first", // off | first | all
      linkPreview: true, // toggle outbound link previews
      streamMode: "partial", // off | partial | block (draft streaming; separate from block streaming)
      draftChunk: {
        // optional; only for streamMode=block
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph", // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // tool action gates (false disables)
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 5,
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        // transport overrides
        autoSelectFamily: false,
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook", // requires webhookSecret
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý về draft streaming:

  • Sử dụng sendMessageDraft của Telegram (bong bóng draft, không phải tin nhắn thật).
  • Yêu cầu private chat topics (message_thread_id trong DM; bot đã bật topics).
  • /reasoning stream stream reasoning vào draft, sau đó gửi câu trả lời cuối cùng. Mặc định và hành vi của retry policy được ghi trong Retry policy.

channels.discord (bot transport)

Cấu hình Discord bot bằng cách đặt bot token và gating tùy chọn: Hỗ trợ nhiều tài khoản nằm trong channels.discord.accounts (xem phần multi-account ở trên). Env token chỉ áp dụng cho tài khoản mặc định.

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8, // clamp inbound media size
      allowBots: false, // allow bot-authored messages
      actions: {
        // tool action gates (false disables)
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dm: {
        enabled: true, // disable all DMs when false
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // optional DM allowlist ("open" requires ["*"])
        groupEnabled: false, // enable group DMs
        groupChannels: ["openclaw-dm"], // optional group DM allowlist
      },
      guilds: {
        "123456789012345678": {
          // guild id (preferred) or slug
          slug: "friends-of-openclaw",
          requireMention: false, // per-guild default
          reactionNotifications: "own", // off | own | all | allowlist
          users: ["987654321098765432"], // optional per-guild user allowlist
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20, // include last N guild messages as context
      textChunkLimit: 2000, // optional outbound text chunk size (chars)
      chunkMode: "length", // optional chunking mode (length | newline)
      maxLinesPerMessage: 17, // soft max lines per message (Discord UI clipping)
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

OpenClaw chỉ khởi động Discord khi có phần config channels.discord. Token được lấy từ channels.discord.token, với DISCORD_BOT_TOKEN làm fallback cho tài khoản mặc định (trừ khi channels.discord.enabled là false). Sử dụng user:<id> (DM) hoặc channel:<id> (guild channel) khi chỉ định đích gửi cho lệnh cron/CLI; ID số thuần túy không rõ ràng và sẽ bị từ chối. Guild slug là chữ thường với khoảng trắng được thay bằng -; key channel sử dụng tên channel đã slug (không có # ở đầu). Ưu tiên dùng guild id làm key để tránh nhầm lẫn khi đổi tên. Tin nhắn từ bot được bỏ qua mặc định. Bật với channels.discord.allowBots (tin nhắn của chính bot vẫn được lọc để tránh vòng lặp tự trả lời). Các chế độ reaction notification:

  • off: không có sự kiện reaction.
  • own: reaction trên tin nhắn của chính bot (mặc định).
  • all: tất cả reaction trên tất cả tin nhắn.
  • allowlist: reaction từ guilds.<id>.users trên tất cả tin nhắn (danh sách rỗng tắt).

Văn bản đầu ra được chia nhỏ theo channels.discord.textChunkLimit (mặc định 2000). Đặt channels.discord.chunkMode="newline" để tách theo dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài. Client Discord có thể cắt tin nhắn rất cao, nên channels.discord.maxLinesPerMessage (mặc định 17) chia các câu trả lời nhiều dòng dài ngay cả khi dưới 2000 ký tự. Mặc định và hành vi của retry policy được ghi trong Retry policy.

channels.googlechat (Chat API webhook)

Google Chat chạy qua HTTP webhook với xác thực cấp ứng dụng (service account). Hỗ trợ nhiều tài khoản nằm trong channels.googlechat.accounts (xem phần multi-account ở trên). Env var chỉ áp dụng cho tài khoản mặc định.

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; improves mention detection
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"], // optional; "open" requires ["*"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • Service account JSON có thể inline (serviceAccount) hoặc dựa trên file (serviceAccountFile).
  • Env fallback cho tài khoản mặc định: GOOGLE_CHAT_SERVICE_ACCOUNT hoặc GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
  • audienceType + audience phải khớp với config xác thực webhook của Chat app.
  • Sử dụng spaces/<spaceId> hoặc users/<userId|email> khi đặt đích gửi.

channels.slack (socket mode)

Slack chạy trong Socket Mode và yêu cầu cả bot token và app token:

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // optional; "open" requires ["*"]
        groupEnabled: false,
        groupChannels: ["G123"],
      },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50, // include last N channel/group messages as context (0 disables)
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20,
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Hỗ trợ nhiều tài khoản nằm trong channels.slack.accounts (xem phần multi-account ở trên). Env token chỉ áp dụng cho tài khoản mặc định.

OpenClaw khởi động Slack khi provider được bật và cả hai token được đặt (qua config hoặc SLACK_BOT_TOKEN + SLACK_APP_TOKEN). Sử dụng user:<id> (DM) hoặc channel:<id> khi chỉ định đích gửi cho lệnh cron/CLI. Đặt channels.slack.configWrites: false để chặn ghi config từ Slack (bao gồm migration ID channel và /config set|unset).

Tin nhắn từ bot được bỏ qua mặc định. Bật với channels.slack.allowBots hoặc channels.slack.channels.<id>.allowBots.

Các chế độ reaction notification:

  • off: không có sự kiện reaction.
  • own: reaction trên tin nhắn của chính bot (mặc định).
  • all: tất cả reaction trên tất cả tin nhắn.
  • allowlist: reaction từ channels.slack.reactionAllowlist trên tất cả tin nhắn (danh sách rỗng tắt).

Cô lập session theo thread:

  • channels.slack.thread.historyScope kiểm soát lịch sử thread theo từng thread (thread, mặc định) hoặc chia sẻ qua channel (channel).
  • channels.slack.thread.inheritParent kiểm soát session thread mới có kế thừa transcript channel cha hay không (mặc định: false).

Các nhóm action Slack (kiểm soát action của công cụ slack):

Nhóm actionMặc địnhGhi chú
reactionsenabledReact + liệt kê reaction
messagesenabledĐọc/gửi/sửa/xóa
pinsenabledPin/unpin/liệt kê
memberInfoenabledThông tin thành viên
emojiListenabledDanh sách emoji tùy chỉnh

channels.mattermost (bot token)

Mattermost được cung cấp dưới dạng plugin và không được đóng gói với bản cài đặt core. Cài đặt trước: openclaw plugins install @openclaw/mattermost (hoặc ./extensions/mattermost từ git checkout).

Mattermost yêu cầu bot token cộng với base URL cho server của các bạn:

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

OpenClaw khởi động Mattermost khi tài khoản được cấu hình (bot token + base URL) và được bật. Token + base URL được lấy từ channels.mattermost.botToken + channels.mattermost.baseUrl hoặc MATTERMOST_BOT_TOKEN + MATTERMOST_URL cho tài khoản mặc định (trừ khi channels.mattermost.enabled là false).

Các chế độ chat:

  • oncall (mặc định): chỉ trả lời tin nhắn channel khi được @mention.
  • onmessage: trả lời mọi tin nhắn channel.
  • onchar: trả lời khi tin nhắn bắt đầu bằng prefix kích hoạt (channels.mattermost.oncharPrefixes, mặc định [">", "!"]).

Kiểm soát truy cập:

  • DM mặc định: channels.mattermost.dmPolicy="pairing" (người gửi không xác định nhận mã pairing).
  • DM công khai: channels.mattermost.dmPolicy="open" cộng với channels.mattermost.allowFrom=["*"].
  • Nhóm: channels.mattermost.groupPolicy="allowlist" mặc định (kiểm soát mention). Sử dụng channels.mattermost.groupAllowFrom để hạn chế người gửi.

Hỗ trợ nhiều tài khoản nằm trong channels.mattermost.accounts (xem phần multi-account ở trên). Env var chỉ áp dụng cho tài khoản mặc định. Sử dụng channel:<id> hoặc user:<id> (hoặc @username) khi chỉ định đích gửi; ID thuần túy được coi là channel ID.

channels.signal (signal-cli)

Reaction của Signal có thể phát ra sự kiện hệ thống (công cụ reaction được chia sẻ):

{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50, // include last N group messages as context (0 disables)
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Các chế độ reaction notification:

  • off: không có sự kiện reaction.
  • own: reaction trên tin nhắn của chính bot (mặc định).
  • all: tất cả reaction trên tất cả tin nhắn.
  • allowlist: reaction từ channels.signal.reactionAllowlist trên tất cả tin nhắn (danh sách rỗng tắt).

channels.imessage (imsg CLI)

OpenClaw spawn imsg rpc (JSON-RPC qua stdio). Không cần daemon hoặc port.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // SCP for remote attachments when using SSH wrapper
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50, // include last N group messages as context (0 disables)
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Hỗ trợ nhiều tài khoản nằm trong channels.imessage.accounts (xem phần multi-account ở trên).

Lưu ý:

  • Yêu cầu Full Disk Access đến Messages DB.
  • Lần gửi đầu tiên sẽ yêu cầu quyền tự động hóa Messages.
  • Ưu tiên đích chat_id:<id>. Sử dụng imsg chats --limit 20 để liệt kê chat.
  • channels.imessage.cliPath có thể trỏ đến wrapper script (ví dụ ssh đến Mac khác chạy imsg rpc); sử dụng SSH key để tránh nhắc mật khẩu.
  • Với SSH wrapper từ xa, đặt channels.imessage.remoteHost để tải attachment qua SCP khi includeAttachments được bật.

Ví dụ wrapper:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

agents.defaults.workspace

Đặt thư mục workspace toàn cục duy nhất được Agent sử dụng cho các thao tác file.

Mặc định: ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Nếu agents.defaults.sandbox được bật, các session không phải main có thể ghi đè bằng workspace riêng theo scope trong agents.defaults.sandbox.workspaceRoot.

agents.defaults.repoRoot

Repository root tùy chọn để hiển thị trong dòng Runtime của system prompt. Nếu không đặt, OpenClaw cố gắng phát hiện thư mục .git bằng cách đi lên từ workspace (và thư mục làm việc hiện tại). Đường dẫn phải tồn tại để được sử dụng.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults.skipBootstrap

Tắt tự động tạo các file bootstrap workspace (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, và BOOTSTRAP.md).

Sử dụng cho các triển khai đã có sẵn file workspace từ repo.

{
  agents: { defaults: { skipBootstrap: true } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults.bootstrapMaxChars

Số ký tự tối đa của mỗi file bootstrap workspace được đưa vào system prompt trước khi cắt bớt. Mặc định: 20000.

Khi file vượt quá giới hạn này, OpenClaw ghi cảnh báo và đưa vào phần đầu/cuối đã cắt với marker.

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults.userTimezone

Đặt timezone của người dùng cho context system prompt (không phải cho timestamp trong message envelope). Nếu không đặt, OpenClaw sử dụng timezone của host tại runtime.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults.timeFormat

Kiểm soát định dạng thời gian hiển thị trong phần Current Date & Time của system prompt. Mặc định: auto (tùy chọn OS).

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

messages

Kiểm soát prefix inbound/outbound và reaction ack tùy chọn. Xem Messages để biết về queueing, session và streaming context.

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false,
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

responsePrefix được áp dụng cho tất cả câu trả lời đầu ra (tóm tắt tool, block streaming, câu trả lời cuối cùng) trên các channel trừ khi đã có sẵn.

Nếu messages.responsePrefix không được đặt, không có prefix nào được áp dụng mặc định. Câu trả lời self-chat WhatsApp là ngoại lệ: chúng mặc định là [{identity.name}] khi được đặt, nếu không thì là [openclaw], để các cuộc hội thoại cùng điện thoại dễ đọc. Đặt thành "auto" để lấy [{identity.name}] cho Agent được route (khi được đặt).

Biến template

Chuỗi responsePrefix có thể bao gồm các biến template được giải quyết động:

BiếnMô tảVí dụ
{model}Tên model ngắnclaude-opus-4-5, gpt-4o
{modelFull}Định danh model đầy đủanthropic/claude-opus-4-5
{provider}Tên provideranthropic, openai
{thinkingLevel}Mức thinking hiện tạihigh, low, off
{identity.name}Tên identity Agent(giống chế độ "auto")

Biến không phân biệt chữ hoa chữ thường ({MODEL} = {model}). {think} là alias của {thinkingLevel}. Biến không giải quyết được vẫn là văn bản literal.

{
  messages: {
    responsePrefix: "[{model} | think:{thinkingLevel}]",
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Ví dụ output: [claude-opus-4-5 | think:high] Here's my response...

Prefix inbound WhatsApp được cấu hình qua channels.whatsapp.messagePrefix (deprecated: messages.messagePrefix). Mặc định giữ không đổi: "[openclaw]" khi channels.whatsapp.allowFrom rỗng, nếu không thì "" (không có prefix). Khi dùng "[openclaw]", OpenClaw sẽ thay bằng [{identity.name}] khi Agent được route có identity.name được đặt.

ackReaction gửi emoji reaction để xác nhận tin nhắn đến trên các channel hỗ trợ reaction (Slack/Discord/Telegram/Google Chat). Mặc định là identity.emoji của Agent đang hoạt động khi được đặt, nếu không thì là "👀". Đặt thành "" để tắt.

ackReactionScope kiểm soát khi nào reaction kích hoạt:

  • group-mentions (mặc định): chỉ khi nhóm/phòng yêu cầu mention và bot được mention
  • group-all: tất cả tin nhắn nhóm/phòng
  • direct: chỉ tin nhắn trực tiếp
  • all: tất cả tin nhắn

removeAckAfterReply xóa reaction ack của bot sau khi gửi câu trả lời (chỉ Slack/Discord/Telegram/Google Chat). Mặc định: false.

messages.tts

Bật text-to-speech cho câu trả lời đầu ra. Khi bật, OpenClaw tạo audio bằng ElevenLabs hoặc OpenAI và đính kèm vào response. Telegram sử dụng Opus voice note; các channel khác gửi audio MP3.

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all (include tool/block replies)
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • messages.tts.auto kiểm soát auto-TTS (off, always, inbound, tagged).
  • /tts off|always|inbound|tagged đặt chế độ auto theo session (ghi đè config).
  • messages.tts.enabled là legacy; doctor migrate nó thành messages.tts.auto.
  • prefsPath lưu các ghi đè cục bộ (provider/limit/summarize).
  • maxTextLength là giới hạn cứng cho input TTS; tóm tắt được cắt bớt để vừa.
  • summaryModel ghi đè agents.defaults.model.primary cho auto-summary.
    • Chấp nhận provider/model hoặc alias từ agents.defaults.models.
  • modelOverrides bật ghi đè theo model như tag [[tts:...]] (bật mặc định).
  • /tts limit và /tts summary kiểm soát cài đặt summarization theo người dùng.
  • Giá trị apiKey fallback về ELEVENLABS_API_KEY/XI_API_KEY và OPENAI_API_KEY.
  • elevenlabs.baseUrl ghi đè base URL API ElevenLabs.
  • elevenlabs.voiceSettings hỗ trợ stability/similarityBoost/style (0..1), useSpeakerBoost, và speed (0.5..2.0).

talk

Mặc định cho chế độ Talk (macOS/iOS/Android). Voice ID fallback về ELEVENLABS_VOICE_ID hoặc SAG_VOICE_ID khi không được đặt. apiKey fallback về ELEVENLABS_API_KEY (hoặc shell profile của gateway) khi không được đặt. voiceAliases cho phép directive Talk sử dụng tên thân thiện (ví dụ "voice":"Clawd").

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    interruptOnSpeech: true,
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults

Kiểm soát runtime Agent nhúng (model/thinking/verbose/timeout). agents.defaults.models định nghĩa catalog model đã cấu hình (và hoạt động như allowlist cho /model). agents.defaults.model.primary đặt model mặc định; agents.defaults.model.fallbacks là failover toàn cục. agents.defaults.imageModel là tùy chọn và chỉ được sử dụng nếu model chính thiếu image input. Mỗi entry agents.defaults.models có thể bao gồm:

  • alias (shortcut model tùy chọn, ví dụ /opus).
  • params (tham số API theo provider tùy chọn được truyền qua request model).

params cũng được áp dụng cho streaming run (Agent nhúng + compaction). Các key được hỗ trợ hiện tại: temperature, maxTokens. Chúng merge với tùy chọn call-time; giá trị do caller cung cấp thắng. temperature là nút nâng cao—để không đặt trừ khi các bạn biết mặc định của model và cần thay đổi.

Ví dụ:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5-20250929": {
          params: { temperature: 0.6 },
        },
        "openai/gpt-5.2": {
          params: { maxTokens: 8192 },
        },
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Các model Z.AI GLM-4.x tự động bật chế độ thinking trừ khi các bạn:

  • đặt --thinking off, hoặc
  • tự định nghĩa agents.defaults.models["zai/<model>"].params.thinking.

OpenClaw cũng đi kèm một số alias shorthand tích hợp. Mặc định chỉ áp dụng khi model đã có trong agents.defaults.models:

  • opus -> anthropic/claude-opus-4-5
  • sonnet -> anthropic/claude-sonnet-4-5
  • gpt -> openai/gpt-5.2
  • gpt-mini -> openai/gpt-5-mini
  • gemini -> google/gemini-3-pro-preview
  • gemini-flash -> google/gemini-3-flash-preview

Nếu các bạn tự cấu hình cùng tên alias (không phân biệt chữ hoa chữ thường), giá trị của các bạn thắng (mặc định không bao giờ ghi đè).

Ví dụ: Opus 4.5 chính với MiniMax M2.1 fallback (hosted MiniMax):

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["minimax/MiniMax-M2.1"],
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Xác thực MiniMax: đặt MINIMAX_API_KEY (env) hoặc cấu hình models.providers.minimax.

agents.defaults.cliBackends (CLI fallback)

CLI backend tùy chọn cho các lần chạy fallback chỉ văn bản (không có tool call). Chúng hữu ích như đường dẫn backup khi API provider thất bại. Image pass-through được hỗ trợ khi các bạn cấu hình imageArg chấp nhận đường dẫn file.

Lưu ý:

  • CLI backend là text-first; tool luôn bị tắt.
  • Session được hỗ trợ khi sessionArg được đặt; session ID được lưu trữ theo backend.
  • Với claude-cli, mặc định được kết nối sẵn. Ghi đè đường dẫn lệnh nếu PATH tối thiểu (launchd/systemd).

Ví dụ:

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
        },
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false,
            },
          },
        },
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free",
        ],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last",
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60,
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000,
      },
      contextTokens: 200000,
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults.contextPruning (tool-result pruning)

agents.defaults.contextPruning cắt bớt kết quả tool cũ từ context trong bộ nhớ ngay trước khi request được gửi đến LLM. Nó không sửa đổi lịch sử session trên đĩa (*.jsonl vẫn đầy đủ).

Điều này nhằm giảm sử dụng token cho các Agent nói nhiều tích lũy output tool lớn theo thời gian.

Tổng quan:

  • Không bao giờ chạm vào tin nhắn user/assistant.
  • Bảo vệ keepLastAssistants tin nhắn assistant cuối cùng (không có kết quả tool sau điểm đó bị cắt bớt).
  • Bảo vệ prefix bootstrap (không có gì trước tin nhắn user đầu tiên bị cắt bớt).
  • Các chế độ:
    • adaptive: soft-trim kết quả tool quá lớn (giữ đầu/đuôi) khi tỷ lệ context ước tính vượt softTrimRatio. Sau đó hard-clear kết quả tool đủ điều kiện cũ nhất khi tỷ lệ context ước tính vượt hardClearRatio và có đủ khối lượng kết quả tool có thể cắt bớt (minPrunableToolChars).
    • aggressive: luôn thay thế kết quả tool đủ điều kiện trước cutoff bằng hardClear.placeholder (không kiểm tra tỷ lệ).

Soft vs hard pruning (những gì thay đổi trong context gửi đến LLM):

  • Soft-trim: chỉ cho kết quả tool quá lớn. Giữ đầu + cuối và chèn ... ở giữa.
    • Trước: toolResult("…very long output…")
    • Sau: toolResult("HEAD…\n...\n…TAIL\n\n[Tool result trimmed: …]")
  • Hard-clear: thay thế toàn bộ kết quả tool bằng placeholder.
    • Trước: toolResult("…very long output…")
    • Sau: toolResult("[Old tool result content cleared]")

Lưu ý / giới hạn hiện tại:

  • Kết quả tool chứa image block bị bỏ qua (không bao giờ trim/clear) hiện tại.
  • “Tỷ lệ context” ước tính dựa trên ký tự (xấp xỉ), không phải token chính xác.
  • Nếu session chưa chứa ít nhất keepLastAssistants tin nhắn assistant, pruning bị bỏ qua.
  • Trong chế độ aggressive, hardClear.enabled bị bỏ qua (kết quả tool đủ điều kiện luôn được thay bằng hardClear.placeholder).

Mặc định (adaptive):

{
  agents: { defaults: { contextPruning: { mode: "adaptive" } } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Để tắt:

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Mặc định (khi mode là "adaptive" hoặc "aggressive"):

  • keepLastAssistants: 3
  • softTrimRatio: 0.3 (chỉ adaptive)
  • hardClearRatio: 0.5 (chỉ adaptive)
  • minPrunableToolChars: 50000 (chỉ adaptive)
  • softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 } (chỉ adaptive)
  • hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

Ví dụ (aggressive, minimal):

{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Ví dụ (adaptive tuned):

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "adaptive",
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        // Optional: restrict pruning to specific tools (deny wins; supports "*" wildcards)
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Xem /concepts/session-pruning để biết chi tiết hành vi.

agents.defaults.compaction (dự trữ headroom + memory flush)

agents.defaults.compaction.mode chọn chiến lược tóm tắt compaction. Mặc định là default; đặt safeguard để bật tóm tắt theo chunk cho các lịch sử rất dài. Xem /concepts/compaction.

agents.defaults.compaction.reserveTokensFloor áp dụng giá trị reserveTokens tối thiểu cho Pi compaction (mặc định: 20000). Đặt thành 0 để tắt giới hạn này.

agents.defaults.compaction.memoryFlush chạy một lượt agentic im lặng trước khi auto-compaction, hướng dẫn model lưu các bộ nhớ lâu dài vào đĩa (ví dụ: memory/YYYY-MM-DD.md). Nó kích hoạt khi ước tính token của session vượt qua ngưỡng mềm dưới giới hạn compaction.

Giá trị mặc định cũ:

  • memoryFlush.enabled: true
  • memoryFlush.softThresholdTokens: 4000
  • memoryFlush.prompt / memoryFlush.systemPrompt: giá trị mặc định tích hợp với NO_REPLY
  • Lưu ý: memory flush bị bỏ qua khi workspace của session ở chế độ chỉ đọc (agents.defaults.sandbox.workspaceAccess: "ro" hoặc "none").

Ví dụ (đã tinh chỉnh):

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",
        reserveTokensFloor: 24000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Block streaming:

  • agents.defaults.blockStreamingDefault: "on"/"off" (mặc định off).
  • Channel overrides: *.blockStreaming (và các biến thể theo tài khoản) để bắt buộc bật/tắt block streaming. Các channel không phải Telegram yêu cầu *.blockStreaming: true rõ ràng để bật block replies.
  • agents.defaults.blockStreamingBreak: "text_end" hoặc "message_end" (mặc định: text_end).
  • agents.defaults.blockStreamingChunk: chia nhỏ mềm cho các block được stream. Mặc định là 800–1200 ký tự, ưu tiên ngắt đoạn văn (\n\n), sau đó là dòng mới, rồi đến câu. Ví dụ: 
    {
  agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } },
}
  • agents.defaults.blockStreamingCoalesce: gộp các block được stream trước khi gửi. Mặc định là { idleMs: 1000 } và kế thừa minChars từ blockStreamingChunk với maxChars giới hạn ở giới hạn văn bản của channel. Signal/Slack/Discord/Google Chat mặc định là minChars: 1500 trừ khi bị ghi đè. Channel overrides: channels.whatsapp.blockStreamingCoalesce, channels.telegram.blockStreamingCoalesce, channels.discord.blockStreamingCoalesce, channels.slack.blockStreamingCoalesce, channels.mattermost.blockStreamingCoalesce, channels.signal.blockStreamingCoalesce, channels.imessage.blockStreamingCoalesce, channels.msteams.blockStreamingCoalesce, channels.googlechat.blockStreamingCoalesce (và các biến thể theo tài khoản).
  • agents.defaults.humanDelay: tạm dừng ngẫu nhiên giữa các block replies sau block đầu tiên. Các chế độ: off (mặc định), natural (800–2500ms), custom (dùng minMs/maxMs). Ghi đè theo agent: agents.list[].humanDelay. Ví dụ: 
    {
  agents: { defaults: { humanDelay: { mode: "natural" } } },
}
    Xem /concepts/streaming để biết chi tiết hành vi + chunking.

Typing indicators:

  • agents.defaults.typingMode: "never" | "instant" | "thinking" | "message". Mặc định là instant cho chat trực tiếp / mentions và message cho group chat không được mention.
  • session.typingMode: ghi đè theo session cho chế độ.
  • agents.defaults.typingIntervalSeconds: tần suất làm mới tín hiệu typing (mặc định: 6s).
  • session.typingIntervalSeconds: ghi đè theo session cho khoảng thời gian làm mới. Xem /concepts/typing-indicators để biết chi tiết hành vi.

agents.defaults.model.primary nên được đặt dưới dạng provider/model (ví dụ: anthropic/claude-opus-4-5). Các alias đến từ agents.defaults.models.*.alias (ví dụ: Opus). Nếu các bạn bỏ qua provider, OpenClaw hiện tại sẽ giả định anthropic như một fallback tạm thời để deprecation. Các model Z.AI có sẵn dưới dạng zai/<model> (ví dụ: zai/glm-4.7) và yêu cầu ZAI_API_KEY (hoặc Z_AI_API_KEY cũ) trong môi trường.

agents.defaults.heartbeat cấu hình các lần chạy heartbeat định kỳ:

  • every: chuỗi duration (ms, s, m, h); đơn vị mặc định là phút. Mặc định: 30m. Đặt 0m để tắt.
  • model: ghi đè model tùy chọn cho các lần chạy heartbeat (provider/model).
  • includeReasoning: khi true, heartbeat cũng sẽ gửi tin nhắn Reasoning: riêng biệt khi có sẵn (cùng hình dạng với /reasoning on). Mặc định: false.
  • session: khóa session tùy chọn để kiểm soát session nào mà heartbeat chạy trong đó. Mặc định: main.
  • to: ghi đè người nhận tùy chọn (id cụ thể theo channel, ví dụ: E.164 cho WhatsApp, chat id cho Telegram).
  • target: channel gửi tùy chọn (last, whatsapp, telegram, discord, slack, msteams, signal, imessage, none). Mặc định: last.
  • prompt: ghi đè tùy chọn cho nội dung heartbeat (mặc định: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.). Các ghi đè được gửi nguyên văn; bao gồm dòng Read HEARTBEAT.md nếu các bạn vẫn muốn đọc file.
  • ackMaxChars: số ký tự tối đa được phép sau HEARTBEAT_OK trước khi gửi (mặc định: 300).

Heartbeat theo agent:

  • Đặt agents.list[].heartbeat để bật hoặc ghi đè cài đặt heartbeat cho một agent cụ thể.
  • Nếu bất kỳ agent entry nào định nghĩa heartbeat, chỉ những agent đó chạy heartbeat; các giá trị mặc định trở thành baseline chung cho những agent đó.

Heartbeat chạy các lượt agent đầy đủ. Khoảng thời gian ngắn hơn tiêu tốn nhiều token hơn; hãy chú ý đến every, giữ HEARTBEAT.md nhỏ gọn, và/hoặc chọn model rẻ hơn.

tools.exec cấu hình các giá trị mặc định cho background exec:

  • backgroundMs: thời gian trước khi tự động chuyển sang background (ms, mặc định 10000)
  • timeoutSec: tự động kill sau thời gian chạy này (giây, mặc định 1800)
  • cleanupMs: thời gian giữ các session đã hoàn thành trong bộ nhớ (ms, mặc định 1800000)
  • notifyOnExit: đưa vào hàng đợi một system event + yêu cầu heartbeat khi exec được background hóa thoát (mặc định true)
  • applyPatch.enabled: bật apply_patch thử nghiệm (chỉ OpenAI/OpenAI Codex; mặc định false)
  • applyPatch.allowModels: allowlist tùy chọn của các model id (ví dụ: gpt-5.2 hoặc openai/gpt-5.2) Lưu ý: applyPatch chỉ nằm dưới tools.exec.

tools.web cấu hình các công cụ web search + fetch:

  • tools.web.search.enabled (mặc định: true khi có key)
  • tools.web.search.apiKey (khuyên dùng: đặt qua openclaw configure --section web, hoặc dùng biến môi trường BRAVE_API_KEY)
  • tools.web.search.maxResults (1–10, mặc định 5)
  • tools.web.search.timeoutSeconds (mặc định 30)
  • tools.web.search.cacheTtlMinutes (mặc định 15)
  • tools.web.fetch.enabled (mặc định true)
  • tools.web.fetch.maxChars (mặc định 50000)
  • tools.web.fetch.timeoutSeconds (mặc định 30)
  • tools.web.fetch.cacheTtlMinutes (mặc định 15)
  • tools.web.fetch.userAgent (ghi đè tùy chọn)
  • tools.web.fetch.readability (mặc định true; tắt để chỉ dùng HTML cleanup cơ bản)
  • tools.web.fetch.firecrawl.enabled (mặc định true khi có API key được đặt)
  • tools.web.fetch.firecrawl.apiKey (tùy chọn; mặc định là FIRECRAWL_API_KEY)
  • tools.web.fetch.firecrawl.baseUrl (mặc định https://api.firecrawl.dev)
  • tools.web.fetch.firecrawl.onlyMainContent (mặc định true)
  • tools.web.fetch.firecrawl.maxAgeMs (tùy chọn)
  • tools.web.fetch.firecrawl.timeoutSeconds (tùy chọn)

tools.media cấu hình khả năng hiểu media đầu vào (image/audio/video):

  • tools.media.models: danh sách model chung (được gắn thẻ capability; dùng sau các danh sách theo capability).
  • tools.media.concurrency: số lượng chạy capability đồng thời tối đa (mặc định 2).
  • tools.media.image / tools.media.audio / tools.media.video:
    • enabled: công tắc opt-out (mặc định true khi các model được cấu hình).
    • prompt: ghi đè prompt tùy chọn (image/video tự động thêm gợi ý maxChars).
    • maxChars: số ký tự đầu ra tối đa (mặc định 500 cho image/video; không đặt cho audio).
    • maxBytes: kích thước media tối đa để gửi (mặc định: image 10MB, audio 20MB, video 50MB).
    • timeoutSeconds: timeout yêu cầu (mặc định: image 60s, audio 60s, video 120s).
    • language: gợi ý audio tùy chọn.
    • attachments: chính sách attachment (mode, maxAttachments, prefer).
    • scope: gating tùy chọn (khớp đầu tiên thắng) với match.channel, match.chatType, hoặc match.keyPrefix.
    • models: danh sách có thứ tự các model entry; lỗi hoặc media quá khổ sẽ fallback sang entry tiếp theo.
  • Mỗi models[] entry:
    • Provider entry (type: "provider" hoặc bỏ qua):
      • provider: id API provider (openai, anthropic, google/gemini, groq, v.v.).
      • model: ghi đè model id (bắt buộc cho image; mặc định là gpt-4o-mini-transcribe/whisper-large-v3-turbo cho audio provider, và gemini-3-flash-preview cho video).
      • profile / preferredProfile: lựa chọn auth profile.
    • CLI entry (type: "cli"):
      • command: executable để chạy.
      • args: các arg được template hóa (hỗ trợ {{MediaPath}}, {{Prompt}}, {{MaxChars}}, v.v.).
    • capabilities: danh sách tùy chọn (image, audio, video) để gate một entry chung. Mặc định khi bỏ qua: openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
    • prompt, maxChars, maxBytes, timeoutSeconds, language có thể được ghi đè theo từng entry.

Nếu không có model nào được cấu hình (hoặc enabled: false), việc hiểu sẽ bị bỏ qua; model vẫn nhận các attachment gốc.

Provider auth tuân theo thứ tự auth model tiêu chuẩn (auth profile, biến môi trường như OPENAI_API_KEY/GROQ_API_KEY/GEMINI_API_KEY, hoặc models.providers.*.apiKey).

Ví dụ:

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

agents.defaults.subagents cấu hình các giá trị mặc định cho sub-agent:

  • model: model mặc định cho các sub-agent được spawn (chuỗi hoặc { primary, fallbacks }). Nếu bỏ qua, sub-agent kế thừa model của caller trừ khi bị ghi đè theo agent hoặc theo lần gọi.
  • maxConcurrent: số lượng chạy sub-agent đồng thời tối đa (mặc định 1)
  • archiveAfterMinutes: tự động archive các session sub-agent sau N phút (mặc định 60; đặt 0 để tắt)
  • Chính sách tool theo subagent: tools.subagents.tools.allow / tools.subagents.tools.deny (deny thắng)

tools.profile đặt một base tool allowlist trước tools.allow/tools.deny:

  • minimal: chỉ session_status
  • coding: group:fs, group:runtime, group:sessions, group:memory, image
  • messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
  • full: không hạn chế (giống như không đặt)

Ghi đè theo agent: agents.list[].tools.profile.

Ví dụ (chỉ messaging theo mặc định, cho phép cả công cụ Slack + Discord):

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Ví dụ (coding profile, nhưng deny exec/process ở mọi nơi):

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

tools.byProvider cho phép các bạn hạn chế thêm các công cụ cho các provider cụ thể (hoặc một provider/model duy nhất). Ghi đè theo agent: agents.list[].tools.byProvider.

Thứ tự: base profile → provider profile → chính sách allow/deny. Các khóa provider chấp nhận provider (ví dụ: google-antigravity) hoặc provider/model (ví dụ: openai/gpt-5.2).

Ví dụ (giữ coding profile toàn cục, nhưng minimal tools cho Google Antigravity):

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Ví dụ (allowlist cụ thể theo provider/model):

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

tools.allow / tools.deny cấu hình chính sách allow/deny công cụ toàn cục (deny thắng). Khớp không phân biệt chữ hoa chữ thường và hỗ trợ wildcard * ("*" có nghĩa là tất cả công cụ). Điều này được áp dụng ngay cả khi Docker sandbox tắt.

Ví dụ (tắt browser/canvas ở mọi nơi):

{
  tools: { deny: ["browser", "canvas"] },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Các nhóm công cụ (shorthands) hoạt động trong chính sách công cụ toàn cục và theo agent:

  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:web: web_search, web_fetch
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: tất cả công cụ OpenClaw tích hợp (loại trừ provider plugin)

tools.elevated kiểm soát quyền truy cập exec nâng cao (host):

  • enabled: cho phép chế độ elevated (mặc định true)
  • allowFrom: allowlist theo channel (rỗng = tắt)
    • whatsapp: số E.164
    • telegram: chat id hoặc username
    • discord: user id hoặc username (fallback về channels.discord.dm.allowFrom nếu bỏ qua)
    • signal: số E.164
    • imessage: handle/chat id
    • webchat: session id hoặc username

Ví dụ:

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["steipete", "1234567890123"],
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Ghi đè theo agent (hạn chế thêm):

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          elevated: { enabled: false },
        },
      },
    ],
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Lưu ý:

  • tools.elevated là baseline toàn cục. agents.list[].tools.elevated chỉ có thể hạn chế thêm (cả hai phải cho phép).
  • /elevated on|off|ask|full lưu trạng thái theo khóa session; các chỉ thị inline áp dụng cho một tin nhắn duy nhất.
  • Elevated exec chạy trên host và bỏ qua sandboxing.
  • Chính sách tool vẫn áp dụng; nếu exec bị deny, elevated không thể được sử dụng.

agents.defaults.maxConcurrent đặt số lượng tối đa các lần chạy embedded agent có thể thực thi song song trên các session. Mỗi session vẫn được tuần tự hóa (một lần chạy trên mỗi khóa session tại một thời điểm). Mặc định: 1.

agents.defaults.sandbox

Docker sandboxing tùy chọn cho embedded agent. Dành cho các session không phải main để chúng không thể truy cập hệ thống host của các bạn.

Chi tiết: Sandboxing

Giá trị mặc định (nếu được bật):

  • scope: "agent" (một container + workspace cho mỗi agent)
  • Image dựa trên Debian bookworm-slim
  • quyền truy cập workspace của agent: workspaceAccess: "none" (mặc định)
    • "none": dùng workspace sandbox theo scope dưới ~/.openclaw/sandboxes
    • "ro": giữ workspace sandbox tại /workspace, và mount workspace agent ở chế độ chỉ đọc tại /agent (tắt write/edit/apply_patch)
    • "rw": mount workspace agent ở chế độ đọc/ghi tại /workspace
  • auto-prune: idle > 24h HOẶC age > 7d
  • chính sách tool: chỉ cho phép exec, process, read, write, edit, apply_patch, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status (deny thắng)
    • cấu hình qua tools.sandbox.tools, ghi đè theo agent qua agents.list[].tools.sandbox.tools
    • các shorthand nhóm công cụ được hỗ trợ trong chính sách sandbox: group:runtime, group:fs, group:sessions, group:memory (xem Sandbox vs Tool Policy vs Elevated)
  • browser được sandbox hóa tùy chọn (Chromium + CDP, noVNC observer)
  • các nút hardening: network, user, pidsLimit, memory, cpus, ulimits, seccompProfile, apparmorProfile

Cảnh báo: scope: "shared" có nghĩa là container chung và workspace chung. Không có cách ly giữa các session. Dùng scope: "session" để cách ly theo session.

Legacy: perSession vẫn được hỗ trợ (true → scope: "session", false → scope: "shared").

setupCommand chạy một lần sau khi container được tạo (bên trong container qua sh -lc). Đối với cài đặt package, đảm bảo network egress, root FS có thể ghi, và user root.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent là mặc định)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          // Per-agent override (multi-agent): agents.list[].sandbox.docker.*
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"],
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          containerPrefix: "openclaw-sbx-browser-",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          allowedControlUrls: ["http://10.0.0.42:18791"],
          allowedControlHosts: ["browser.lab.local", "10.0.0.42"],
          allowedControlPorts: [18791],
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24, // 0 tắt idle pruning
          maxAgeDays: 7, // 0 tắt max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

Build image sandbox mặc định một lần với:

scripts/sandbox-setup.sh

Lưu ý: các container sandbox mặc định là network: "none"; đặt agents.defaults.sandbox.docker.network thành "bridge" (hoặc network tùy chỉnh của các bạn) nếu agent cần truy cập outbound.

Lưu ý: các attachment đầu vào được staged vào workspace đang hoạt động tại media/inbound/*. Với workspaceAccess: "rw", điều đó có nghĩa là các file được ghi vào workspace agent.

Lưu ý: docker.binds mount các thư mục host bổ sung; các bind toàn cục và theo agent được merge.

Build image browser tùy chọn với:

scripts/sandbox-browser-setup.sh

Khi agents.defaults.sandbox.browser.enabled=true, công cụ browser sử dụng instance Chromium được sandbox hóa (CDP). Nếu noVNC được bật (mặc định khi headless=false), URL noVNC được inject vào system prompt để agent có thể tham chiếu nó. Điều này không yêu cầu browser.enabled trong config chính; URL điều khiển sandbox được inject theo session.

agents.defaults.sandbox.browser.allowHostControl (mặc định: false) cho phép các session được sandbox hóa nhắm mục tiêu rõ ràng vào server điều khiển browser host qua công cụ browser (target: "host"). Tắt cái này nếu các bạn muốn cách ly sandbox nghiêm ngặt.

Allowlist cho điều khiển từ xa:

  • allowedControlUrls: các URL điều khiển chính xác được phép cho target: "custom".
  • allowedControlHosts: hostname được phép (chỉ hostname, không có port).
  • allowedControlPorts: port được phép (mặc định: http=80, https=443). Mặc định: tất cả allowlist không được đặt (không hạn chế). allowHostControl mặc định là false.

models (custom providers + base URLs)

OpenClaw sử dụng catalog model pi-coding-agent. Các bạn có thể thêm custom provider (LiteLLM, local OpenAI-compatible server, Anthropic proxy, v.v.) bằng cách viết ~/.openclaw/agents/<agentId>/agent/models.json hoặc bằng cách định nghĩa cùng schema bên trong OpenClaw config của các bạn dưới models.providers. Tổng quan theo provider + ví dụ: /concepts/model-providers.

Khi models.providers có mặt, OpenClaw ghi/merge một models.json vào ~/.openclaw/agents/<agentId>/agent/ khi khởi động:

  • hành vi mặc định: merge (giữ các provider hiện có, ghi đè theo tên)
  • đặt models.mode: "replace" để ghi đè nội dung file

Chọn model qua agents.defaults.model.primary (provider/model).

{
  agents: {
    defaults: {
      model: { primary: "custom-proxy/llama-3.1-8b" },
      models: {
        "custom-proxy/llama-3.1-8b": {},
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

OpenCode Zen (multi-model proxy)

OpenCode Zen là một gateway multi-model với các endpoint theo model. OpenClaw sử dụng provider opencode tích hợp từ pi-ai; đặt OPENCODE_API_KEY (hoặc OPENCODE_ZEN_API_KEY) từ https://opencode.ai/auth.

Lưu ý:

  • Các model ref sử dụng opencode/<modelId> (ví dụ: opencode/claude-opus-4-5).
  • Nếu các bạn bật allowlist qua agents.defaults.models, thêm mỗi model mà các bạn dự định sử dụng.
  • Shortcut: openclaw onboard --auth-choice opencode-zen.
{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-5" },
      models: { "opencode/claude-opus-4-5": { alias: "Opus" } },
    },
  },
}

Z.AI (GLM-4.7) — hỗ trợ alias provider

Các model Z.AI có sẵn qua provider zai tích hợp. Đặt ZAI_API_KEY trong môi trường của các bạn và tham chiếu model theo provider/model.

Shortcut: openclaw onboard --auth-choice zai-api-key.

plugins (extensions)

Quản lý việc tìm kiếm plugin, cho phép/từ chối, và cấu hình từng plugin. Các plugin được load từ ~/.openclaw/extensions, <workspace>/.openclaw/extensions, cộng thêm các mục trong plugins.load.paths. Thay đổi config cần khởi động lại gateway. Xem /plugin để biết cách dùng đầy đủ.

Các trường:

  • enabled: bật/tắt tổng thể cho việc load plugin (mặc định: true).
  • allow: allowlist tùy chọn của các plugin id; khi đặt, chỉ các plugin được liệt kê mới load.
  • deny: denylist tùy chọn của các plugin id (deny thắng).
  • load.paths: các file hoặc thư mục plugin bổ sung để load (đường dẫn tuyệt đối hoặc ~).
  • entries.<pluginId>: ghi đè cho từng plugin.
    • enabled: đặt false để tắt.
    • config: object cấu hình riêng cho plugin (được validate bởi plugin nếu có).

Ví dụ:

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio",
        },
      },
    },
  },
}

browser (openclaw-managed browser)

OpenClaw có thể khởi động một instance Chrome/Brave/Edge/Chromium riêng biệt, cô lập cho openclaw và expose một control service loopback nhỏ. Các profile có thể trỏ đến một trình duyệt Chromium-based từ xa qua profiles.<name>.cdpUrl. Các profile từ xa chỉ attach (start/stop/reset bị tắt).

browser.cdpUrl vẫn giữ cho các config single-profile cũ và làm base scheme/host cho các profile chỉ đặt cdpPort.

Mặc định:

  • enabled: true
  • evaluateEnabled: true (đặt false để tắt act:evaluate và wait --fn)
  • control service: chỉ loopback (port lấy từ gateway.port, mặc định 18791)
  • CDP URL: http://127.0.0.1:18792 (control service + 1, legacy single-profile)
  • profile color: #FF4500 (lobster-orange)
  • Lưu ý: control server được khởi động bởi gateway đang chạy (OpenClaw.app menubar, hoặc openclaw gateway).
  • Thứ tự tự động phát hiện: trình duyệt mặc định nếu là Chromium-based; nếu không thì Chrome → Brave → Edge → Chromium → Chrome Canary.
{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    defaultProfile: "chrome",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // Advanced:
    // headless: false,
    // noSandbox: false,
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false, // set true when tunneling a remote CDP to localhost
  },
}

ui (Appearance)

Màu accent tùy chọn được các ứng dụng native sử dụng cho UI chrome (ví dụ: màu bubble Talk Mode).

Nếu không đặt, client sẽ dùng màu xanh nhạt mặc định.

{
  ui: {
    seamColor: "#FF4500", // hex (RRGGBB or #RRGGBB)
    // Optional: Control UI assistant identity override.
    // If unset, the Control UI uses the active agent identity (config or IDENTITY.md).
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, or image URL/data URI
    },
  },
}

gateway (Gateway server mode + bind)

Dùng gateway.mode để khai báo rõ ràng liệu máy này có nên chạy Gateway hay không.

Mặc định:

  • mode: không đặt (được coi là “không tự động khởi động”)
  • bind: loopback
  • port: 18789 (single port cho WS + HTTP)
{
  gateway: {
    mode: "local", // or "remote"
    port: 18789, // WS + HTTP multiplex
    bind: "loopback",
    // controlUi: { enabled: true, basePath: "/openclaw" }
    // auth: { mode: "token", token: "your-token" } // token gates WS + Control UI access
    // tailscale: { mode: "off" | "serve" | "funnel" }
  },
}

Control UI base path:

  • gateway.controlUi.basePath đặt URL prefix nơi Control UI được serve.
  • Ví dụ: "/ui", "/openclaw", "/apps/openclaw".
  • Mặc định: root (/) (không thay đổi).
  • gateway.controlUi.allowInsecureAuth cho phép auth chỉ bằng token cho Control UI khi device identity bị bỏ qua (thường qua HTTP). Mặc định: false. Nên dùng HTTPS (Tailscale Serve) hoặc 127.0.0.1.
  • gateway.controlUi.dangerouslyDisableDeviceAuth tắt kiểm tra device identity cho Control UI (chỉ token/password). Mặc định: false. Chỉ dùng khi khẩn cấp.

Related docs:

Trusted proxies:

  • gateway.trustedProxies: danh sách các IP reverse proxy terminate TLS trước Gateway.
  • Khi một kết nối đến từ một trong các IP này, OpenClaw sử dụng x-forwarded-for (hoặc x-real-ip) để xác định IP client cho các kiểm tra local pairing và HTTP auth/local checks.
  • Chỉ liệt kê các proxy mà các bạn hoàn toàn kiểm soát, và đảm bảo chúng ghi đè x-forwarded-for đến.

Notes:

  • openclaw gateway từ chối khởi động trừ khi gateway.mode được đặt thành local (hoặc các bạn truyền override flag).
  • gateway.port kiểm soát single multiplexed port được dùng cho WebSocket + HTTP (control UI, hooks, A2UI).
  • OpenAI Chat Completions endpoint: tắt mặc định; bật với gateway.http.endpoints.chatCompletions.enabled: true.
  • Thứ tự ưu tiên: --port > OPENCLAW_GATEWAY_PORT > gateway.port > mặc định 18789.
  • Gateway auth được yêu cầu mặc định (token/password hoặc Tailscale Serve identity). Các bind không phải loopback yêu cầu shared token/password.
  • Wizard onboarding tạo gateway token mặc định (ngay cả trên loopback).
  • gateway.remote.token chỉ dành cho remote CLI calls; nó không bật local gateway auth. gateway.token bị bỏ qua.

Auth and Tailscale:

  • gateway.auth.mode đặt yêu cầu handshake (token hoặc password). Khi không đặt, token auth được giả định.
  • gateway.auth.token lưu shared token cho token auth (được CLI sử dụng trên cùng máy).
  • Khi gateway.auth.mode được đặt, chỉ phương thức đó được chấp nhận (cộng thêm Tailscale headers tùy chọn).
  • gateway.auth.password có thể đặt ở đây, hoặc qua OPENCLAW_GATEWAY_PASSWORD (khuyên dùng).
  • gateway.auth.allowTailscale cho phép Tailscale Serve identity headers (tailscale-user-login) thỏa mãn auth khi request đến trên loopback với x-forwarded-for, x-forwarded-proto, và x-forwarded-host. OpenClaw xác minh identity bằng cách resolve địa chỉ x-forwarded-for qua tailscale whois trước khi chấp nhận. Khi true, các request Serve không cần token/password; đặt false để yêu cầu credentials rõ ràng. Mặc định true khi tailscale.mode = "serve" và auth mode không phải password.
  • gateway.tailscale.mode: "serve" sử dụng Tailscale Serve (chỉ tailnet, loopback bind).
  • gateway.tailscale.mode: "funnel" expose dashboard công khai; yêu cầu auth.
  • gateway.tailscale.resetOnExit reset Serve/Funnel config khi shutdown.

Remote client defaults (CLI):

  • gateway.remote.url đặt Gateway WebSocket URL mặc định cho CLI calls khi gateway.mode = "remote".
  • gateway.remote.transport chọn macOS remote transport (ssh mặc định, direct cho ws/wss). Khi direct, gateway.remote.url phải là ws:// hoặc wss://. ws://host mặc định port 18789.
  • gateway.remote.token cung cấp token cho remote calls (để trống nếu không có auth).
  • gateway.remote.password cung cấp password cho remote calls (để trống nếu không có auth).

macOS app behavior:

  • OpenClaw.app theo dõi ~/.openclaw/openclaw.json và chuyển mode trực tiếp khi gateway.mode hoặc gateway.remote.url thay đổi.
  • Nếu gateway.mode không đặt nhưng gateway.remote.url được đặt, macOS app coi đó là remote mode.
  • Khi các bạn thay đổi connection mode trong macOS app, nó ghi gateway.mode (và gateway.remote.url + gateway.remote.transport trong remote mode) trở lại file config.
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

Direct transport example (macOS app):

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "wss://gateway.example.ts.net",
      token: "your-token",
    },
  },
}

gateway.reload (Config hot reload)

Gateway theo dõi ~/.openclaw/openclaw.json (hoặc OPENCLAW_CONFIG_PATH) và áp dụng thay đổi tự động.

Modes:

  • hybrid (mặc định): hot-apply các thay đổi an toàn; khởi động lại Gateway cho các thay đổi quan trọng.
  • hot: chỉ áp dụng các thay đổi hot-safe; log khi cần khởi động lại.
  • restart: khởi động lại Gateway khi có bất kỳ thay đổi config nào.
  • off: tắt hot reload.
{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 300,
    },
  },
}

Hot reload matrix (files + impact)

Files watched:

  • ~/.openclaw/openclaw.json (hoặc OPENCLAW_CONFIG_PATH)

Hot-applied (không cần khởi động lại gateway hoàn toàn):

  • hooks (webhook auth/path/mappings) + hooks.gmail (Gmail watcher khởi động lại)
  • browser (browser control server khởi động lại)
  • cron (cron service khởi động lại + cập nhật concurrency)
  • agents.defaults.heartbeat (heartbeat runner khởi động lại)
  • web (WhatsApp web channel khởi động lại)
  • telegram, discord, signal, imessage (channel khởi động lại)
  • agent, models, routing, messages, session, whatsapp, logging, skills, ui, talk, identity, wizard (dynamic reads)

Requires full Gateway restart:

  • gateway (port/bind/auth/control UI/tailscale)
  • bridge (legacy)
  • discovery
  • canvasHost
  • plugins
  • Any unknown/unsupported config path (mặc định khởi động lại để đảm bảo an toàn)

Multi-instance isolation

Để chạy nhiều gateway trên một host (cho redundancy hoặc rescue bot), cô lập state + config cho từng instance và dùng port riêng:

  • OPENCLAW_CONFIG_PATH (config cho từng instance)
  • OPENCLAW_STATE_DIR (sessions/creds)
  • agents.defaults.workspace (memories)
  • gateway.port (riêng cho mỗi instance)

Convenience flags (CLI):

  • openclaw --dev … → sử dụng ~/.openclaw-dev + dịch chuyển port từ base 19001
  • openclaw --profile <name> … → sử dụng ~/.openclaw-<name> (port qua config/env/flags)

Xem Gateway runbook cho port mapping được tạo ra (gateway/browser/canvas). Xem Multiple gateways cho chi tiết cô lập browser/CDP port.

Example:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

hooks (Gateway webhooks)

Bật HTTP webhook endpoint đơn giản trên Gateway HTTP server.

Mặc định:

  • enabled: false
  • path: /hooks
  • maxBodyBytes: 262144 (256 KB)
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  },
}

Requests phải bao gồm hook token:

  • Authorization: Bearer <token> hoặc
  • x-openclaw-token: <token> hoặc
  • ?token=<token>

Endpoints:

  • POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
  • POST /hooks/agent → { message, name?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • POST /hooks/<name> → resolved qua hooks.mappings

/hooks/agent luôn post summary vào main session (và có thể tùy chọn trigger heartbeat ngay lập tức qua wakeMode: "now").

Mapping notes:

  • match.path khớp với sub-path sau /hooks (ví dụ: /hooks/gmail → gmail).
  • match.source khớp với một trường payload (ví dụ: { source: "gmail" }) để các bạn có thể dùng path /hooks/ingest chung.
  • Templates như {{messages[0].subject}} đọc từ payload.
  • transform có thể trỏ đến một module JS/TS trả về hook action.
  • deliver: true gửi reply cuối cùng đến một channel; channel mặc định là last (fallback về WhatsApp).
  • Nếu không có delivery route trước đó, đặt channel + to rõ ràng (bắt buộc cho Telegram/Discord/Google Chat/Slack/Signal/iMessage/MS Teams).
  • model ghi đè LLM cho hook run này (provider/model hoặc alias; phải được cho phép nếu agents.defaults.models được đặt).

Gmail helper config (được dùng bởi openclaw webhooks gmail setup / run):

{
  hooks: {
    gmail: {
      account: "[email protected]",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },

      // Optional: use a cheaper model for Gmail hook processing
      // Falls back to agents.defaults.model.fallbacks, then primary, on auth/rate-limit/timeout
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      // Optional: default thinking level for Gmail hooks
      thinking: "off",
    },
  },
}

Model override for Gmail hooks:

  • hooks.gmail.model chỉ định model để sử dụng cho Gmail hook processing (mặc định là session primary).
  • Chấp nhận provider/model refs hoặc aliases từ agents.defaults.models.
  • Fallback về agents.defaults.model.fallbacks, sau đó agents.defaults.model.primary, khi gặp auth/rate-limit/timeouts.
  • Nếu agents.defaults.models được đặt, bao gồm hooks model trong allowlist.
  • Khi khởi động, cảnh báo nếu model được cấu hình không có trong model catalog hoặc allowlist.
  • hooks.gmail.thinking đặt thinking level mặc định cho Gmail hooks và bị ghi đè bởi thinking cho từng hook.

Gateway auto-start:

  • Nếu hooks.enabled=true và hooks.gmail.account được đặt, Gateway khởi động gog gmail watch serve khi boot và tự động renew watch.
  • Đặt OPENCLAW_SKIP_GMAIL_WATCHER=1 để tắt auto-start (cho manual runs).
  • Tránh chạy gog gmail watch serve riêng cùng với Gateway; nó sẽ fail với listen tcp 127.0.0.1:8788: bind: address already in use.

Note: khi tailscale.mode bật, OpenClaw mặc định serve.path thành / để Tailscale có thể proxy /gmail-pubsub đúng cách (nó strip set-path prefix). Nếu các bạn cần backend nhận prefixed path, đặt hooks.gmail.tailscale.target thành full URL (và align serve.path).

canvasHost (LAN/tailnet Canvas file server + live reload)

Gateway serve một thư mục HTML/CSS/JS qua HTTP để các node iOS/Android có thể đơn giản canvas.navigate đến đó.

Default root: ~/.openclaw/workspace/canvas Default port: 18793 (được chọn để tránh openclaw browser CDP port 18792) Server lắng nghe trên gateway bind host (LAN hoặc Tailnet) để các node có thể reach được.

Server:

  • serve các file dưới canvasHost.root
  • inject một live-reload client nhỏ vào HTML được serve
  • theo dõi thư mục và broadcast reloads qua WebSocket endpoint tại /__openclaw__/ws
  • tự động tạo starter index.html khi thư mục trống (để các bạn thấy ngay)
  • cũng serve A2UI tại /__openclaw__/a2ui/ và được advertise cho nodes là canvasHostUrl (luôn được nodes sử dụng cho Canvas/A2UI)

Tắt live reload (và file watching) nếu thư mục lớn hoặc các bạn gặp EMFILE:

  • config: canvasHost: { liveReload: false }
{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    port: 18793,
    liveReload: true,
  },
}

Thay đổi canvasHost.* yêu cầu khởi động lại gateway (config reload sẽ restart).

Tắt với:

  • config: canvasHost: { enabled: false }
  • env: OPENCLAW_SKIP_CANVAS_HOST=1

bridge (legacy TCP bridge, removed)

Các bản build hiện tại không còn bao gồm TCP bridge listener; các config key bridge.* bị bỏ qua. Các node kết nối qua Gateway WebSocket. Phần này được giữ lại để tham khảo lịch sử.

Legacy behavior:

  • Gateway có thể expose một TCP bridge đơn giản cho các node (iOS/Android), thường trên port 18790.

Mặc định:

  • enabled: true
  • port: 18790
  • bind: lan (bind đến 0.0.0.0)

Bind modes:

  • lan: 0.0.0.0 (có thể reach trên bất kỳ interface nào, bao gồm LAN/Wi‑Fi và Tailscale)
  • tailnet: chỉ bind đến Tailscale IP của máy (khuyên dùng cho Vienna ⇄ London)
  • loopback: 127.0.0.1 (chỉ local)
  • auto: ưu tiên tailnet IP nếu có, nếu không thì lan

TLS:

  • bridge.tls.enabled: bật TLS cho bridge connections (chỉ TLS khi enabled).
  • bridge.tls.autoGenerate: tạo self-signed cert khi không có cert/key (mặc định: true).
  • bridge.tls.certPath / bridge.tls.keyPath: đường dẫn PEM cho bridge certificate + private key.
  • bridge.tls.caPath: PEM CA bundle tùy chọn (custom roots hoặc mTLS trong tương lai).

Khi TLS được bật, Gateway advertise bridgeTls=1 và bridgeTlsSha256 trong discovery TXT records để các node có thể pin certificate. Các kết nối thủ công dùng trust-on-first-use nếu chưa lưu fingerprint. Các cert tự động tạo yêu cầu openssl trên PATH; nếu tạo fail, bridge sẽ không khởi động.

{
  bridge: {
    enabled: true,
    port: 18790,
    bind: "tailnet",
    tls: {
      enabled: true,
      // Uses ~/.openclaw/bridge/tls/bridge-{cert,key}.pem when omitted.
      // certPath: "~/.openclaw/bridge/tls/bridge-cert.pem",
      // keyPath: "~/.openclaw/bridge/tls/bridge-key.pem"
    },
  },
}

discovery.mdns (Bonjour / mDNS broadcast mode)

Kiểm soát LAN mDNS discovery broadcasts (_openclaw-gw._tcp).

  • minimal (mặc định): bỏ qua cliPath + sshPort khỏi TXT records
  • full: bao gồm cliPath + sshPort trong TXT records
  • off: tắt hoàn toàn mDNS broadcasts
  • Hostname: mặc định là openclaw (advertise openclaw.local). Ghi đè với OPENCLAW_MDNS_HOSTNAME.
{
  discovery: { mdns: { mode: "minimal" } },
}

discovery.wideArea (Wide-Area Bonjour / unicast DNS‑SD)

Khi được bật, Gateway ghi một unicast DNS-SD zone cho _openclaw-gw._tcp dưới ~/.openclaw/dns/ sử dụng discovery domain được cấu hình (ví dụ: openclaw.internal.).

Để làm cho iOS/Android discover qua các mạng (Vienna ⇄ London), kết hợp với:

  • một DNS server trên gateway host serve domain các bạn chọn (khuyên dùng CoreDNS)
  • Tailscale split DNS để clients resolve domain đó qua gateway DNS server

One-time setup helper (gateway host):

openclaw dns setup --apply
{
  discovery: { wideArea: { enabled: true } },
}

Template variables

Template placeholders được mở rộng trong tools.media.*.models[].args và tools.media.models[].args (và bất kỳ trường argument được template hóa nào trong tương lai).

VariableDescription
{{Body}}Full inbound message body
{{RawBody}}Raw inbound message body (không có history/sender wrappers; tốt nhất cho command parsing)
{{BodyStripped}}Body với group mentions bị strip (mặc định tốt nhất cho agents)
{{From}}Sender identifier (E.164 cho WhatsApp; có thể khác cho mỗi channel)
{{To}}Destination identifier
{{MessageSid}}Channel message id (khi có)
{{SessionId}}Current session UUID
{{IsNewSession}}"true" khi một session mới được tạo
{{MediaUrl}}Inbound media pseudo-URL (nếu có)
{{MediaPath}}Local media path (nếu đã download)
{{MediaType}}Media type (image/audio/document/…)
{{Transcript}}Audio transcript (khi enabled)
{{Prompt}}Resolved media prompt cho CLI entries
{{MaxChars}}Resolved max output chars cho CLI entries
{{ChatType}}"direct" hoặc "group"
{{GroupSubject}}Group subject (best effort)
{{GroupMembers}}Group members preview (best effort)
{{SenderName}}Sender display name (best effort)
{{SenderE164}}Sender phone number (best effort)
{{Provider}}Provider hint (whatsapp / telegram / discord / googlechat / slack / signal / imessage / msteams / webchat / …)

Cron (Gateway scheduler)

Cron là một scheduler thuộc Gateway cho wakeups và scheduled jobs. Xem Cron jobs để biết tổng quan tính năng và ví dụ CLI.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
  },
}

Next: Agent Runtime 🦞