Cấu hình

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

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

Tất cả các kênh đều dùng chung mẫu chính sách tin nhắn trực tiếp:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // chỉ dành cho allowlist/open    },  },}

Thiết lập mô hình chính và các phương án 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 lưu bí danh và thiết lập theo từng mô hình; việc thêm một mục không bao giờ hạn chế các giá trị ghi đè /model hoặc --model.
• agents.defaults.modelPolicy.allow là danh sách cho phép rõ ràng dành cho các giá trị ghi đè và trình chọn mô hình. Trường này chấp nhận tham chiếu chính xác và ký tự đại diện provider/*; bỏ qua trường này hoặc dùng [] để cho phép mọi mô hình.
• 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 hình ảnh trong bản chép lời/công cụ (mặc định 1200); giá trị thấp hơn thường giảm mức sử dụng token thị giác trong các lượt chạy có nhiều ảnh chụp màn hình.
• Xem CLI mô hình để chuyển đổi mô hình trong cuộc trò chuyện và Chuyển đổi dự phòng mô hình để biết hành vi luân phiên xác thực và dự phòng.
• Đối với nhà cung cấp tùy chỉnh/tự lưu trữ, xem Nhà cung cấp tùy chỉnh trong tài liệu tham chiếu.

Quyền truy cập tin nhắn trực tiếp được kiểm soát theo từng kênh qua dmPolicy (mặc định "pairing"):

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

Đối với nhóm, dùng groupPolicy ("allowlist" | "open" | "disabled") cùng với groupAllowFrom hoặc danh sách cho phép dành riêng cho kênh.

Xem tài liệu 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 đề cập. Cấu hình mẫu kích hoạt theo từng agent. Phản hồi nhóm/kênh thông thường được đăng tự động; hãy chủ động chọn đường dẫn công cụ tin nhắn cho các phòng dùng chung nơi agent cần quyết định thời điểm lên tiếng:

{  messages: {    visibleReplies: "automatic", // đặt thành "message_tool" để yêu cầu gửi bằng công cụ tin nhắn ở mọi nơi    groupChat: {      visibleReplies: "message_tool", // chủ động bật; đầu ra hiển thị yêu cầu message(action=send)      unmentionedInbound: "room_event", // trò chuyện nhóm luôn bật nhưng không đề cập chỉ là ngữ cảnh thụ động    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Đề cập qua siêu dữ liệu: @-mention gốc (nhấn để đề cập trên WhatsApp, @bot trên Telegram, v.v.)
• Mẫu văn bản: mẫu biểu thức chính quy 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ụ tin nhắn trên toàn cục; messages.groupChat.visibleReplies ghi đè thiết lập đó cho nhóm/kênh.
• Xem tài liệu tham chiếu đầy đủ để biết các chế độ phản hồi hiển thị, giá trị ghi đè theo kênh và chế độ tự trò chuyện.

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

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // kế thừa github, weather      { id: "docs", skills: ["docs-search"] }, // thay thế giá trị mặc định      { id: "locked-down", skills: [] }, // không có Skills    ],  },}

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

Tắt hoặc bật tự động khởi động lại theo tình trạng cho một kênh hoặc tài khoản:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Dùng channels.<provider>.healthMonitor.enabled hoặc channels.<provider>.accounts.<id>.healthMonitor.enabled để kiểm soát tự động khởi động lại cho một kênh hoặc tài khoản.
• Xem Kiểm tra tình trạng để gỡ lỗi vận hành và tài liệu tham chiếu đầy đủ để biết tất cả các trường.

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

{  session: {    dmScope: "per-channel-peer",  // khuyến nghị cho nhiều người dùng    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: các giá trị mặc định toàn cục để định tuyến phiên gắn với luồng. /focus, /unfocus, /agents, /session idle và /session max-age lần lượt gắn, bỏ gắn, liệt kê và tinh chỉnh thiết lập này theo từng phiên (Discord gắn các luồng, Telegram gắn các chủ đề/cuộc trò chuyện).
• Xem Quản lý phiên để biết về phạm vi, liên kết danh tính và chính sách gửi.
• Xem tài liệu tham khảo đầy đủ để biết tất cả các trường.

Chạy các phiên tác tử trong những môi trường runtime sandbox tách biệt:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // tắt | không phải chính | tất cả        scope: "agent",    // phiên | tác tử | dùng chung      },    },  },}

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

Xem Sandbox để biết hướng dẫn đầy đủ và tài liệu tham khảo đầy đủ để biết tất cả các tùy chọn.

Tính năng đẩy qua relay cho các bản dựng App Store công khai sử dụng relay OpenClaw được lưu trữ: https://ios-push-relay.openclaw.ai.

Các triển khai relay tùy chỉnh yêu cầu một quy trình dựng/triển khai iOS riêng biệt có chủ đích, trong đó URL relay khớp với URL relay của Gateway. Nếu đang sử dụng bản dựng relay tùy chỉnh, hãy đặt cấu hình sau trong Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Tùy chọn. Mặc định: 10000          timeoutMs: 10000,        },      },    },  },}

Lệnh CLI tương đương:

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

Tác dụng của cấu hình này:

• Cho phép Gateway gửi push.test, tín hiệu đánh thức và tín hiệu đánh thức để kết nối lại thông qua relay bên ngoài.
• Sử dụng quyền gửi theo phạm vi đăng ký do ứng dụng iOS đã ghép đôi chuyển tiếp. Gateway không cần token relay dùng cho toàn bộ triển khai.
• Gắn mỗi đăng ký qua relay với danh tính Gateway mà ứng dụng iOS đã ghép đôi, để Gateway khác không thể tái sử dụng đăng ký đã lưu.
• Giữ các bản dựng iOS cục bộ/thủ công sử dụng APNs trực tiếp. Hoạt động gửi qua relay chỉ áp dụng cho các bản dựng được phân phối chính thức đã đăng ký thông qua relay.
• Phải khớp với URL cơ sở của relay được nhúng trong bản dựng iOS, để 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 ứng dụng iOS chính thức.
2. Tùy chọn: chỉ cấu hình gateway.push.apns.relay.baseUrl trên Gateway khi sử dụng một bản dựng relay tùy chỉnh riêng biệt có chủ đích.
3. Ghép đôi ứng dụng iOS với Gateway và cho phép cả phiên Node lẫn phiên người vận hành kết nối.
4. Ứng dụng iOS truy xuất danh tính Gateway, đăng ký với relay bằng App Attest cùng biên lai ứng dụng, sau đó gửi tải trọng push.apns.register qua relay đến Gateway đã ghép đôi.
5. Gateway lưu mã xử lý relay và quyền gửi, sau đó sử dụng chúng cho push.test, tín hiệu đánh thức và tín hiệu đánh thức để kết nối lại.

Lưu ý vận hành:

• Nếu chuyển ứng dụng iOS sang một Gateway khác, hãy kết nối lại ứng dụng để ứng dụng có thể gửi đăng ký relay mới được gắn với Gateway đó.
• Nếu phát hành bản dựng iOS mới trỏ đến một triển khai relay khác, ứng dụng sẽ làm mới đăng ký relay đã lưu trong bộ nhớ đệm thay vì tái sử dụng nguồn relay cũ.

Lưu ý về khả năng tương thích:

• OPENCLAW_APNS_RELAY_BASE_URL và OPENCLAW_APNS_RELAY_TIMEOUT_MS vẫn hoạt động dưới dạng các giá trị ghi đè tạm thời bằng biến môi trường.
• URL relay tùy chỉnh của Gateway phải khớp với URL cơ sở của relay được nhúng trong bản dựng iOS; luồng phát hành App Store công khai từ chối các giá trị ghi đè URL relay iOS tùy chỉnh.
• 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 cố định URL relay HTTP trong cấu hình.

Xem Ứng dụng 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 của relay.

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

• every: chuỗi thời lượng (30m, 2h). Đặt 0m để tắt. Mặc định: 30m.
• 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 tin nhắn trực tiếp
• Xem Heartbeat để biết hướng dẫn đầy đủ.

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention: xóa các phiên chạy tách biệt đã hoàn tất khỏi các hàng phiên SQLite (mặc định 24h; đặt false để tắt).
• Lịch sử chạy tự động giữ lại 2000 hàng trạng thái kết thúc mới nhất cho mỗi tác vụ; các hàng bị mất vẫn giữ thời hạn dọn dẹp 24 giờ.
• Xem Tác vụ Cron để biết tổng quan tính năng và các ví dụ CLI.

Bật các điểm cuối Webhook HTTP 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,      },    ],  },}

Lưu ý bảo mật:

• Xem toàn bộ nội dung tải trọng hook/Webhook là dữ liệu đầu vào không đáng tin cậy.
• Sử dụng một hooks.token chuyên dụng; không tái sử dụng các bí mật xác thực Gateway đang hoạt động (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN hoặc gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Xác thực hook chỉ sử dụng header (Authorization: Bearer ... hoặc x-openclaw-token); token trong chuỗi truy vấn sẽ bị từ chối.
• hooks.path không thể là /; hãy đặt điểm tiếp nhận Webhook trên một đường dẫn con chuyên dụng như /hooks.
• Giữ các cờ bỏ qua kiểm tra 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 được kiểm soát chặt chẽ.
• Nếu bật hooks.allowRequestSessionKey, hãy đồng thời đặt hooks.allowedSessionKeyPrefixes để giới hạn các khóa phiên do bên gọi chọn.
• Đối với các tác tử được kích hoạt bằng hook, nên ưu tiên các cấp mô hình hiện đại, mạnh mẽ cùng chính sách công cụ nghiêm ngặt (ví dụ: chỉ nhắn tin, kết hợp sandbox khi có thể).

Xem tài liệu tham khảo đầy đủ để biết tất cả các tùy chọn ánh xạ và tích hợp Gmail.

Chạy nhiều tác tử tách biệt với các không gian làm việc 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 tử và tài liệu tham khảo đầy đủ để biết các quy tắc gắn kết và hồ sơ truy cập theo từng tác tử.

Sử dụng $include để tổ chức cá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: hợp nhất sâu theo thứ tự (tệp sau được ưu tiên), với tối đa 10 cấp lồng nhau
• Khóa cùng cấp: được hợp nhất sau các tệp được bao gồm (ghi đè các giá trị được bao gồm)
• Đường dẫn tương đối: được phân giải tương đối so với tệp bao gồm chúng
• Định dạng đường dẫn: đường dẫn bao gồm không được chứa byte null và phải ngắn hơn nghiêm ngặt 4096 ký tự cả trước và sau khi phân giải
• Thao tác ghi do OpenClaw thực hiện: khi một thao tác ghi chỉ thay đổi một phần cấp cao nhất được cung cấp bởi một tệp bao gồm duy nhất như plugins: { $include: "./plugins.json5" }, OpenClaw cập nhật tệp được bao gồm đó và giữ nguyên openclaw.json
• Không hỗ trợ ghi xuyên qua: các tệp bao gồm ở gốc, mảng tệp bao gồm và các tệp bao gồm có giá trị ghi đè cùng cấp sẽ bị từ chối an toàn đối với thao tác ghi do OpenClaw thực hiện thay vì làm phẳng cấu hình
• Giới hạn phạm vi: các đường dẫn $include phải được phân giải bên trong thư mục chứa openclaw.json. Để chia sẻ một cây thư mục giữa các máy hoặc người dùng, hãy đặ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à tệp bao gồm có thể tham chiếu. Các liên kết tượng trưng được phân giải và kiểm tra lại, vì vậy một đường dẫn về mặt từ vựng nằm trong thư mục cấu hình nhưng có đích thực nằm ngoài mọi gốc được phép vẫn sẽ bị từ chối.
• Xử lý lỗi: cung cấp lỗi rõ ràng cho tệp bị thiếu, lỗi phân tích cú pháp, vòng lặp tệp bao gồm, định dạng đường dẫn không hợp lệ và độ dài vượt quá giới hạn