Cấu hình

Mỗi kênh có phần cấu hình riêng dưới channels.<provider>. Xem trang kênh chuyên biệt để biết các bước thiết lập:

• WhatsApp - channels.whatsapp
• Telegram - channels.telegram
• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• Microsoft Teams - channels.msteams
• Slack - channels.slack
• Signal - channels.signal
• iMessage - channels.imessage
• Mattermost - channels.mattermost

Tất cả kênh dùng chung cùng mẫu chính sách DM:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}

Đặt mô hình chính và các mô hình dự phòng tùy chọn:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models định nghĩa danh mục mô hình và đóng vai trò là allowlist cho /model.
• Dùng openclaw config set agents.defaults.models '<json>' --strict-json --merge để thêm mục allowlist mà không xóa các mô hình hiện có. Các thao tác thay thế thuần túy có thể xóa mục sẽ bị từ chối trừ khi bạn truyền --replace.
• Tham chiếu mô hình dùng định dạng provider/model (ví dụ anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx kiểm soát việc giảm kích thước ảnh trong transcript/công cụ (mặc định 1200); giá trị thấp hơn thường giảm mức dùng token thị giác trong các lượt chạy nhiều ảnh chụp màn hình.
• Xem CLI mô hình để chuyển mô hình trong chat và Chuyển đổi dự phòng mô hình để biết hành vi xoay vòng xác thực và dự phòng.
• Đối với provider tùy chỉnh/tự host, xem Provider tùy chỉnh trong tài liệu tham chiếu.

Quyền truy cập DM được kiểm soát theo từng kênh thông qua dmPolicy:

• "pairing" (mặc định): người gửi không xác định nhận được mã ghép đôi dùng một lần để phê duyệt
• "allowlist": chỉ những người gửi trong allowFrom (hoặc kho cho phép đã ghép đôi)
• "open": cho phép tất cả DM đến (yêu cầu allowFrom: ["*"])
• "disabled": bỏ qua tất cả DM

Đối với nhóm, hãy dùng groupPolicy + groupAllowFrom hoặc danh sách cho phép riêng theo kênh.

Xem tham chiếu đầy đủ để biết chi tiết theo từng kênh.

Tin nhắn nhóm mặc định yêu cầu nhắc đến. Cấu hình mẫu kích hoạt theo từng agent, và giữ phản hồi phòng hiển thị trên đường dẫn công cụ nhắn tin mặc định trừ khi bạn chủ ý muốn phản hồi cuối tự động kiểu cũ:

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Lượt nhắc trong siêu dữ liệu: @-mention gốc (WhatsApp chạm để nhắc, Telegram @bot, v.v.)
• Mẫu văn bản: mẫu regex an toàn trong mentionPatterns
• Phản hồi hiển thị: messages.visibleReplies có thể yêu cầu gửi bằng công cụ nhắn tin trên toàn cục; messages.groupChat.visibleReplies ghi đè cài đặt đó cho nhóm/kênh.
• Xem tham chiếu đầy đủ để biết các chế độ phản hồi hiển thị, ghi đè theo kênh và chế độ tự trò chuyện.

Dùng agents.defaults.skills làm đường cơ sở dùng chung, rồi ghi đè các agent cụ thể bằng agents.list[].skills:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Bỏ qua agents.defaults.skills để mặc định không giới hạn Skills.
• Bỏ qua agents.list[].skills để kế thừa mặc định.
• Đặt agents.list[].skills: [] để không có Skills.
• Xem Skills, Cấu hình Skills, và Tham chiếu cấu hình.

Kiểm soát mức độ chủ động Gateway khởi động lại các kênh có vẻ bị treo:

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}

• Đặt gateway.channelHealthCheckMinutes: 0 để tắt khởi động lại bằng trình giám sát tình trạng trên toàn cục.
• channelStaleEventThresholdMinutes nên lớn hơn hoặc bằng khoảng thời gian kiểm tra.
• Dùng channels.<provider>.healthMonitor.enabled hoặc channels.<provider>.accounts.<id>.healthMonitor.enabled để tắt tự động khởi động lại cho một kênh hoặc tài khoản mà không tắt trình giám sát toàn cục.
• Xem Kiểm tra tình trạng để gỡ lỗi vận hành và tham chiếu đầy đủ cho tất cả trường.

Cho client cục bộ thêm thời gian để hoàn tất bắt tay WebSocket trước xác thực trên máy chủ đang tải nặng hoặc có công suất thấp:

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• Mặc định là 15000 mili giây.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS vẫn được ưu tiên cho các ghi đè dịch vụ hoặc shell dùng một lần.
• Ưu tiên sửa tình trạng khởi động/vòng lặp sự kiện bị nghẽn trước; núm điều chỉnh này dành cho máy chủ vẫn khỏe nhưng chậm trong quá trình làm nóng.

Phiên kiểm soát tính liên tục và cô lập của cuộc trò chuyện:

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main (dùng chung) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: mặc định toàn cục cho định tuyến phiên gắn với luồng (Discord hỗ trợ /focus, /unfocus, /agents, /session idle, và /session max-age).
• Xem Quản lý phiên để biết phạm vi, liên kết danh tính và chính sách gửi.
• Xem tham chiếu đầy đủ cho tất cả trường.

Chạy phiên tác nhân trong runtime sandbox cô lập:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

Trước tiên hãy dựng image - từ checkout nguồn, chạy scripts/sandbox-setup.sh, hoặc từ bản cài npm, xem lệnh docker build nội tuyến trong Sandboxing § Image và thiết lập.

Xem Sandboxing để đọc hướng dẫn đầy đủ và tham chiếu đầy đủ để biết tất cả tùy chọn.

Push dựa trên relay được cấu hình trong openclaw.json.

Đặt mục này trong cấu hình gateway:

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

Tương đương CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Cơ chế này thực hiện:

• Cho phép gateway gửi push.test, các nudges đánh thức và các lần đánh thức kết nối lại thông qua relay bên ngoài.
• Sử dụng quyền gửi trong phạm vi đăng ký được app iOS đã ghép đôi chuyển tiếp. Gateway không cần token relay cho toàn bộ triển khai.
• Ràng buộc từng đăng ký dựa trên relay với danh tính gateway mà app iOS đã ghép đôi, để gateway khác không thể dùng lại đăng ký đã lưu.
• Giữ các bản dựng iOS cục bộ/thủ công dùng APNs trực tiếp. Việc gửi dựa trên relay chỉ áp dụng cho các bản dựng phân phối chính thức đã đăng ký thông qua relay.
• Phải khớp với URL cơ sở relay được nhúng vào bản dựng iOS chính thức/TestFlight, để lưu lượng đăng ký và gửi đến cùng một triển khai relay.

Luồng đầu cuối:

1. Cài đặt bản dựng iOS chính thức/TestFlight đã được biên dịch với cùng URL cơ sở relay.
2. Cấu hình gateway.push.apns.relay.baseUrl trên gateway.
3. Ghép đôi app iOS với gateway và để cả phiên node lẫn phiên điều hành kết nối.
4. App iOS lấy danh tính gateway, đăng ký với relay bằng App Attest cộng với biên nhận app, rồi phát hành payload push.apns.register dựa trên relay tới gateway đã ghép đôi.
5. Gateway lưu handle relay và quyền gửi, rồi dùng chúng cho push.test, nudges đánh thức và các lần đánh thức kết nối lại.

Ghi chú vận hành:

• Nếu bạn chuyển app iOS sang gateway khác, hãy kết nối lại app để app có thể phát hành đăng ký relay mới được ràng buộc với gateway đó.
• Nếu bạn phát hành bản dựng iOS mới trỏ tới một triển khai relay khác, app sẽ làm mới đăng ký relay đã lưu trong bộ nhớ đệm thay vì dùng lại origin relay cũ.

Ghi chú tương thích:

• OPENCLAW_APNS_RELAY_BASE_URL và OPENCLAW_APNS_RELAY_TIMEOUT_MS vẫn hoạt động như các override env tạm thời.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true vẫn là lối thoát phát triển chỉ dành cho loopback; không lưu URL relay HTTP trong cấu hình.

Xem App iOS để biết luồng đầu cuối và Luồng xác thực và tin cậy để biết mô hình bảo mật relay.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

• every: chuỗi thời lượng (30m, 2h). Đặt 0m để tắt.
• target: last | none | <channel-id> (ví dụ discord, matrix, telegram, hoặc whatsapp)
• directPolicy: allow (mặc định) hoặc block cho các đích Heartbeat kiểu DM
• Xem Heartbeat để đọc hướng dẫn đầy đủ.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: dọn các phiên chạy cô lập đã hoàn tất khỏi sessions.json (mặc định 24h; đặt false để tắt).
• runLog: dọn cron/runs/<jobId>.jsonl theo kích thước và số dòng được giữ lại.
• Xem Tác vụ Cron để biết tổng quan tính năng và ví dụ CLI.

Bật endpoint HTTP webhook trên Gateway:

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

Ghi chú bảo mật:

• Xem mọi nội dung payload hook/webhook là đầu vào không đáng tin cậy.
• Dùng hooks.token chuyên dụng; không dùng lại token Gateway dùng chung.
• Xác thực hook chỉ qua header (Authorization: Bearer ... hoặc x-openclaw-token); token trong query-string bị từ chối.
• hooks.path không được là /; giữ lối vào webhook trên một đường dẫn con chuyên dụng như /hooks.
• Giữ các cờ bỏ qua nội dung không an toàn ở trạng thái tắt (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) trừ khi đang gỡ lỗi trong phạm vi chặt chẽ.
• Nếu bạn bật hooks.allowRequestSessionKey, cũng đặt hooks.allowedSessionKeyPrefixes để giới hạn các khóa phiên do bên gọi chọn.
• Với các tác nhân được kích hoạt bởi hook, ưu tiên các tier mô hình hiện đại mạnh và chính sách công cụ nghiêm ngặt (ví dụ chỉ nhắn tin cộng với sandboxing khi có thể).

Xem tham chiếu đầy đủ để biết tất cả tùy chọn mapping và tích hợp Gmail.

Chạy nhiều tác nhân cô lập với workspace và phiên riêng:

{
  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" } },
  ],
}

Xem Đa tác nhân và tham chiếu đầy đủ để biết quy tắc binding và hồ sơ truy cập theo từng tác nhân.

Dùng $include để tổ chức cấu hình lớn:

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

• Một tệp: thay thế đối tượng chứa nó
• Mảng tệp: được deep-merge theo thứ tự (mục sau thắng)
• Khóa cùng cấp: được merge sau include (ghi đè giá trị được include)
• Include lồng nhau: hỗ trợ sâu tối đa 10 cấp
• Đường dẫn tương đối: được phân giải tương đối với tệp include
• Ghi do OpenClaw sở hữu: khi một thao tác ghi chỉ thay đổi một section cấp cao nhất được hậu thuẫn bởi include một tệp như plugins: { $include: "./plugins.json5" }, OpenClaw cập nhật tệp được include đó và giữ nguyên openclaw.json
• Không hỗ trợ ghi xuyên qua: root include, mảng include và include có override cùng cấp sẽ fail closed đối với ghi do OpenClaw sở hữu thay vì làm phẳng cấu hình
• Giới hạn phạm vi: đường dẫn $include phải phân giải dưới thư mục chứa openclaw.json. Để chia sẻ một cây giữa các máy hoặc người dùng, đặt OPENCLAW_INCLUDE_ROOTS thành danh sách đường dẫn (: trên POSIX, ; trên Windows) gồm các thư mục bổ sung mà include có thể tham chiếu. Symlink được phân giải và kiểm tra lại, nên một đường dẫn về mặt từ vựng nằm trong thư mục cấu hình nhưng đích thực của nó thoát khỏi mọi root được phép vẫn bị từ chối.
• Xử lý lỗi: lỗi rõ ràng cho tệp bị thiếu, lỗi phân tích cú pháp và include vòng