> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cấu hình OpenClaw đọc cấu hình **JSON5** tùy chọn từ `~/.openclaw/openclaw.json`. Đường dẫn cấu hình đang hoạt động phải là một tệp thông thường. Các bố cục `openclaw.json` dùng symlink không được hỗ trợ cho các thao tác ghi do OpenClaw sở hữu; thao tác ghi nguyên tử có thể thay thế đường dẫn thay vì giữ nguyên symlink. Nếu bạn giữ cấu hình bên ngoài thư mục trạng thái mặc định, hãy trỏ `OPENCLAW_CONFIG_PATH` trực tiếp đến tệp thật. Nếu tệp bị thiếu, OpenClaw dùng các mặc định an toàn. Các lý do phổ biến để thêm cấu hình: * Kết nối các kênh và kiểm soát ai có thể nhắn tin cho bot * Đặt mô hình, công cụ, sandboxing hoặc tự động hóa (cron, hook) * Tinh chỉnh phiên, phương tiện, mạng hoặc UI Xem [tham chiếu đầy đủ](/vi/gateway/configuration-reference) để biết mọi trường có sẵn. Agent và tự động hóa nên dùng `config.schema.lookup` để lấy tài liệu chính xác ở cấp trường trước khi chỉnh sửa cấu hình. Dùng trang này cho hướng dẫn theo tác vụ và [Tham chiếu cấu hình](/vi/gateway/configuration-reference) cho bản đồ trường và mặc định rộng hơn. **Mới làm quen với cấu hình?** Bắt đầu với `openclaw onboard` để thiết lập tương tác, hoặc xem hướng dẫn [Ví dụ cấu hình](/vi/gateway/configuration-examples) để có cấu hình hoàn chỉnh có thể sao chép-dán. ## Cấu hình tối thiểu ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} // ~/.openclaw/openclaw.json { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } ``` ## Chỉnh sửa cấu hình ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard # full onboarding flow openclaw configure # config wizard ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` Mở [http://127.0.0.1:18789](http://127.0.0.1:18789) và dùng tab **Cấu hình**. Control UI hiển thị một biểu mẫu từ schema cấu hình trực tiếp, bao gồm metadata tài liệu `title` / `description` của trường cùng với schema Plugin và kênh khi có sẵn, với trình chỉnh sửa **Raw JSON** làm lối thoát. Với các UI đi sâu và công cụ khác, Gateway cũng cung cấp `config.schema.lookup` để lấy một nút schema theo phạm vi đường dẫn cùng bản tóm tắt các phần tử con trực tiếp. Chỉnh sửa trực tiếp `~/.openclaw/openclaw.json`. Gateway theo dõi tệp và tự động áp dụng thay đổi (xem [tải lại nóng](#config-hot-reload)). ## Xác thực nghiêm ngặt OpenClaw chỉ chấp nhận cấu hình khớp hoàn toàn với schema. Khóa không xác định, kiểu sai định dạng hoặc giá trị không hợp lệ khiến Gateway **từ chối khởi động**. Ngoại lệ duy nhất ở cấp gốc là `$schema` (chuỗi), để trình chỉnh sửa có thể gắn metadata JSON Schema. `openclaw config schema` in JSON Schema chuẩn được Control UI và quá trình xác thực dùng. `config.schema.lookup` lấy một nút theo phạm vi đường dẫn cùng bản tóm tắt phần tử con cho công cụ đi sâu. Metadata tài liệu `title`/`description` của trường được truyền qua các object lồng nhau, wildcard (`*`), phần tử mảng (`[]`) và các nhánh `anyOf`/ `oneOf`/`allOf`. Schema Plugin và kênh lúc runtime được hợp nhất khi manifest registry được tải. Khi xác thực thất bại: * Gateway không khởi động * Chỉ các lệnh chẩn đoán hoạt động (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) * Chạy `openclaw doctor` để xem vấn đề chính xác * Chạy `openclaw doctor --fix` (hoặc `--yes`) để áp dụng sửa chữa Gateway giữ một bản sao last-known-good đáng tin cậy sau mỗi lần khởi động thành công, nhưng khởi động và tải lại nóng không tự động khôi phục bản sao đó. Nếu `openclaw.json` không vượt qua xác thực (bao gồm xác thực cục bộ của Plugin), quá trình khởi động Gateway thất bại hoặc lần tải lại bị bỏ qua và runtime hiện tại giữ cấu hình được chấp nhận gần nhất. Chạy `openclaw doctor --fix` (hoặc `--yes`) để sửa cấu hình bị thêm tiền tố/bị ghi đè hoặc khôi phục bản sao last-known-good. Việc quảng bá thành last-known-good bị bỏ qua khi một ứng viên chứa placeholder bí mật đã được che như `***`. ## Tác vụ phổ biến Mỗi kênh có phần cấu hình riêng dưới `channels.`. Xem trang kênh chuyên biệt để biết các bước thiết lập: * [WhatsApp](/vi/channels/whatsapp) - `channels.whatsapp` * [Telegram](/vi/channels/telegram) - `channels.telegram` * [Discord](/vi/channels/discord) - `channels.discord` * [Feishu](/vi/channels/feishu) - `channels.feishu` * [Google Chat](/vi/channels/googlechat) - `channels.googlechat` * [Microsoft Teams](/vi/channels/msteams) - `channels.msteams` * [Slack](/vi/channels/slack) - `channels.slack` * [Signal](/vi/channels/signal) - `channels.signal` * [iMessage](/vi/channels/imessage) - `channels.imessage` * [Mattermost](/vi/channels/mattermost) - `channels.mattermost` Tất cả kênh dùng chung cùng mẫu chính sách DM: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 fallback tùy chọn: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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ò allowlist cho `/model`; các mục `provider/*` lọc `/model`, `/models` và bộ chọn mô hình theo những nhà cung cấp đã chọn trong khi vẫn dùng khám phá mô hình động. * Dùng `openclaw config set agents.defaults.models '' --strict-json --merge` để thêm mục allowlist mà không xóa mô hình hiện có. Các thay thế thuần túy sẽ xóa mục 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 giảm tỷ lệ hình ảnh 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ần chạy nhiều ảnh chụp màn hình. * Xem [CLI mô hình](/vi/concepts/models) để chuyển mô hình trong chat và [Chuyển đổi dự phòng mô hình](/vi/concepts/model-failover) để biết xoay vòng xác thực và hành vi fallback. * Với nhà cung cấp tùy chỉnh/tự host, xem [Nhà cung cấp tùy chỉnh](/vi/gateway/config-tools#custom-providers-and-base-urls) trong tham chiếu. Quyền truy cập DM được kiểm soát theo từng kênh qua `dmPolicy`: * `"pairing"` (mặc định): 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 mọi DM đến (yêu cầu `allowFrom: ["*"]`) * `"disabled"`: bỏ qua mọi DM Với nhóm, dùng `groupPolicy` + `groupAllowFrom` hoặc allowlist theo kênh. Xem [tham chiếu đầy đủ](/vi/gateway/config-channels#dm-and-group-access) để biết chi tiết theo từng kênh. Tin nhắn nhóm mặc định là **yêu cầu nhắc đến**. 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; chọn dùng đường dẫn công cụ tin nhắn cho phòng chung nơi agent nên quyết định khi nào phát biểu: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { messages: { visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere groupChat: { visibleReplies: "message_tool", // opt-in; visible output requires message(action=send) unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context }, }, agents: { list: [ { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, }, ], }, channels: { whatsapp: { groups: { "*": { requireMention: true } }, }, }, } ``` * **Nhắc đến bằng metadata**: @-mention gốc (WhatsApp chạm để nhắc đến, 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ụ tin nhắn trên toàn cục; `messages.groupChat.visibleReplies` ghi đè điều đó cho nhóm/kênh. * Xem [tham chiếu đầy đủ](/vi/gateway/config-channels#group-chat-mention-gating) để biết các chế độ phản hồi hiển thị, ghi đè theo kênh và chế độ tự chat. Dùng `agents.defaults.skills` cho đường cơ sở dùng chung, rồi ghi đè các agent cụ thể bằng `agents.list[].skills`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/vi/tools/skills), [Cấu hình Skills](/vi/tools/skills-config), và [Tham chiếu cấu hình](/vi/gateway/config-agents#agents-defaults-skills). Kiểm soát mức độ quyết liệt Gateway khởi động lại các kênh có vẻ stale: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 health-monitor 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..healthMonitor.enabled` hoặc `channels..accounts..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 sức khỏe](/vi/gateway/health) để gỡ lỗi vận hành và [tham chiếu đầy đủ](/vi/gateway/configuration-reference#gateway) để biết 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 host tải nặng hoặc công suất thấp: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { handshakeTimeoutMs: 30000, }, } ``` * Mặc định là `15000` mili giây. * `OPENCLAW_HANDSHAKE_TIMEOUT_MS` vẫn được ưu tiên cho ghi đè dịch vụ hoặc shell dùng một lần. * Ưu tiên sửa stall khởi động/event-loop trước; núm này dành cho host khỏe mạnh nhưng chậm trong quá trình warmup. Phiên kiểm soát tính liên tục và cô lập của hội thoại: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`: giá trị 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](/vi/concepts/session) để biết phạm vi, liên kết danh tính và chính sách gửi. * Xem [tài liệu tham chiếu đầy đủ](/vi/gateway/config-agents#session) để biết tất cả các trường. Chạy phiên tác tử trong các runtime sandbox tách biệt: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, } ``` Trước tiên hãy xây dựng image - từ checkout mã 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 [Chế độ sandbox § Image và thiết lập](/vi/gateway/sandboxing#images-and-setup). Xem [Chế độ sandbox](/vi/gateway/sandboxing) để biết hướng dẫn đầy đủ và [tài liệu tham chiếu đầy đủ](/vi/gateway/config-agents#agentsdefaultssandbox) để biết tất cả tùy chọn. Push dựa trên 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 đường dẫn dựng/triển khai iOS tách riêng có chủ ý, trong đó URL relay khớp với URL relay của Gateway. Nếu bạn đang dùng bản dựng relay tùy chỉnh, hãy đặt mục này trong cấu hình Gateway: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { push: { apns: { relay: { baseUrl: "https://relay.example.com", // Optional. Default: 10000 timeoutMs: 10000, }, }, }, }, } ``` CLI tương đương: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` Việc này thực hiện: * Cho phép Gateway gửi `push.test`, tín hiệu đánh thức và đá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ý được ứng dụng iOS đã ghép đôi chuyển tiếp. Gateway không cần token relay trên toàn bộ triển khai. * Gắn mỗi đăng ký dựa trên 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 trên APNs trực tiếp. 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 trong bản dựng iOS, để lưu lượng đăng ký và gửi đi tới 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 dùng bản dựng relay tùy chỉnh tách riêng có chủ ý. 3. Ghép đôi ứng dụng iOS với Gateway và để cả phiên node lẫn phiên operator kết nối. 4. Ứng dụng iOS lấy danh tính Gateway, đăng ký với relay bằng App Attest cùng biên nhận ứng dụng, rồi công bố 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`, tín hiệu đánh thức và đánh thức kết nối lại. Ghi chú vận hành: * Nếu bạn chuyển ứng dụng iOS sang Gateway khác, hãy kết nối lại ứng dụng để nó có thể công bố đăng ký relay mới gắn với Gateway đó. * Nếu bạn phát hành bản dựng iOS mới trỏ tới triển khai relay khác, ứng dụng sẽ làm mới đăng ký relay đã lưu trong cache thay vì tái sử dụng nguồn relay cũ. Ghi chú tương thích: * `OPENCLAW_APNS_RELAY_BASE_URL` và `OPENCLAW_APNS_RELAY_TIMEOUT_MS` vẫn hoạt động dưới dạng ghi đè env tạm thời. * URL relay Gateway tùy chỉnh phải khớp với URL cơ sở 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 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; đừng lưu cố định URL relay HTTP trong cấu hình. Xem [Ứng dụng iOS](/vi/platforms/ios#relay-backed-push-for-official-builds) để biết luồng đầu cuối và [Luồng xác thực và tin cậy](/vi/platforms/ios#authentication-and-trust-flow) để biết mô hình bảo mật relay. ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { heartbeat: { every: "30m", target: "last", }, }, }, } ``` * `every`: chuỗi thời lượng (`30m`, `2h`). Đặt `0m` để tắt. * `target`: `last` | `none` | `` (ví dụ `discord`, `matrix`, `telegram`, hoặc `whatsapp`) * `directPolicy`: `allow` (mặc định) hoặc `block` cho mục tiêu Heartbeat kiểu DM * Xem [Heartbeat](/vi/gateway/heartbeat) để biết hướng dẫn đầy đủ. ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { cron: { enabled: true, maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, }, } ``` * `sessionRetention`: dọn các phiên chạy tách biệt đã hoàn tất khỏi `sessions.json` (mặc định `24h`; đặt `false` để tắt). * `runLog`: dọn các hàng lịch sử chạy Cron được giữ lại theo từng công việc. `maxBytes` vẫn được chấp nhận cho nhật ký chạy cũ dựa trên tệp. * Xem [Công việc Cron](/vi/automation/cron-jobs) để biết tổng quan tính năng và ví dụ CLI. Bật các endpoint Webhook HTTP trên Gateway: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 toàn bộ 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 tái sử dụng 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ỉ dùng header (`Authorization: Bearer ...` hoặc `x-openclaw-token`); token trong chuỗi truy vấn bị từ chối. * `hooks.path` không thể là `/`; giữ Webhook ingress 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 rất chặt. * 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 tử được điều khiển bằng hook, ưu tiên các tầng 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 sandbox khi có thể). Xem [tài liệu tham chiếu đầy đủ](/vi/gateway/configuration-reference#hooks) để biết tất 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 workspace và phiên riêng: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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ử](/vi/concepts/multi-agent) và [tài liệu tham chiếu đầy đủ](/vi/gateway/config-agents#multi-agent-routing) để biết quy tắc liên kết và hồ sơ truy cập theo từng tác tử. Dùng `$include` để tổ chức các cấu hình lớn: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} // ~/.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 gộp sâu theo thứ tự (mục sau thắng) * **Khóa cùng cấp**: được gộp sau include (ghi đè giá trị đã include) * **Include lồng nhau**: được 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 đang include * **Định dạng đường dẫn**: đường dẫn include không được chứa byte null và phải ngắn hơn nghiêm ngặt 4096 ký tự trước và sau khi phân giải * **Ghi do OpenClaw sở hữu**: khi một thao tác ghi chỉ thay đổi một mục cấp cao nhất được hỗ trợ bởi include một tệp như `plugins: { $include: "./plugins.json5" }`, OpenClaw cập nhật tệp đã include đó và giữ nguyên `openclaw.json` * **Ghi xuyên qua không được hỗ trợ**: include ở root, mảng include và include có ghi đè cùng cấp sẽ đóng thất bại đối với thao tác 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 bên 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) của 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 nằm trong thư mục cấu hình về mặt từ vựng nhưng đích thực của nó thoát khỏi mọi root được cho phép vẫn sẽ 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, include vòng tròn, định dạng đường dẫn không hợp lệ và độ dài quá mức ## Tải lại nóng cấu hình Gateway theo dõi `~/.openclaw/openclaw.json` và tự động áp dụng thay đổi - hầu hết thiết lập không cần khởi động lại thủ công. Các chỉnh sửa tệp trực tiếp được xem là không đáng tin cậy cho đến khi chúng vượt qua xác thực. Bộ theo dõi chờ biến động ghi tạm/đổi tên của trình soạn thảo ổn định, đọc tệp cuối cùng và từ chối các chỉnh sửa bên ngoài không hợp lệ mà không ghi lại `openclaw.json`. Các thao tác ghi cấu hình do OpenClaw sở hữu dùng cùng cổng schema trước khi ghi; các ghi đè phá hủy như xóa `gateway.mode` hoặc thu nhỏ tệp hơn một nửa bị từ chối và được lưu dưới dạng `.rejected.*` để kiểm tra. Nếu bạn thấy `config reload skipped (invalid config)` hoặc khi khởi động báo `Invalid config`, hãy kiểm tra cấu hình, chạy `openclaw config validate`, rồi chạy `openclaw doctor --fix` để sửa. Xem [Khắc phục sự cố Gateway](/vi/gateway/troubleshooting#gateway-rejected-invalid-config) để biết danh sách kiểm tra. ### Chế độ tải lại | Chế độ | Hành vi | | ----------------------- | -------------------------------------------------------------------------------------------------- | | **`hybrid`** (mặc định) | Áp dụng nóng các thay đổi an toàn ngay lập tức. Tự động khởi động lại với các thay đổi quan trọng. | | **`hot`** | Chỉ áp dụng nóng các thay đổi an toàn. Ghi cảnh báo khi cần khởi động lại - bạn tự xử lý. | | **`restart`** | Khởi động lại Gateway khi có bất kỳ thay đổi cấu hình nào, dù an toàn hay không. | | **`off`** | Tắt theo dõi tệp. Thay đổi có hiệu lực ở lần khởi động lại thủ công tiếp theo. | ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { reload: { mode: "hybrid", debounceMs: 300 }, }, } ``` ### Nội dung nào áp dụng nóng và nội dung nào cần khởi động lại Hầu hết các trường được áp dụng nóng mà không có downtime. Ở chế độ `hybrid`, các thay đổi yêu cầu khởi động lại được xử lý tự động. | Danh mục | Trường | Cần khởi động lại? | | ---------------------- | ------------------------------------------------------------------------ | ------------------ | | Kênh | `channels.*`, `web` (WhatsApp) - tất cả kênh tích hợp sẵn và kênh Plugin | Không | | Tác tử và mô hình | `agent`, `agents`, `models`, `routing` | Không | | Tự động hóa | `hooks`, `cron`, `agent.heartbeat` | Không | | Phiên và tin nhắn | `session`, `messages` | Không | | Công cụ và phương tiện | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | Không | | UI và khác | `ui`, `logging`, `identity`, `bindings` | Không | | Máy chủ Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Có** | | Cơ sở hạ tầng | `discovery`, `plugins` | **Có** | `gateway.reload` và `gateway.remote` là ngoại lệ - việc thay đổi chúng **không** kích hoạt khởi động lại. ### Lập kế hoạch tải lại Khi bạn chỉnh sửa một tệp nguồn được tham chiếu qua `$include`, OpenClaw lập kế hoạch tải lại từ bố cục do nguồn định nghĩa, không phải chế độ xem trong bộ nhớ đã được làm phẳng. Điều đó giữ cho các quyết định tải lại nóng (áp dụng nóng so với khởi động lại) có thể dự đoán được ngay cả khi một phần cấp cao nhất duy nhất nằm trong tệp được bao gồm riêng, chẳng hạn như `plugins: { $include: "./plugins.json5" }`. Việc lập kế hoạch tải lại sẽ đóng an toàn nếu bố cục nguồn không rõ ràng. ## Config RPC (cập nhật bằng chương trình) Đối với công cụ ghi cấu hình qua API Gateway, ưu tiên luồng này: * `config.schema.lookup` để kiểm tra một cây con (nút schema nông + tóm tắt phần con) * `config.get` để lấy snapshot hiện tại cùng với `hash` * `config.patch` cho cập nhật một phần (JSON merge patch: các đối tượng được hợp nhất, `null` xóa, mảng được thay thế khi được xác nhận rõ ràng bằng `replacePaths` nếu các mục sẽ bị xóa) * `config.apply` chỉ khi bạn định thay thế toàn bộ cấu hình * `update.run` để tự cập nhật rõ ràng cùng với khởi động lại; bao gồm `continuationMessage` khi phiên sau khởi động lại cần chạy một lượt tiếp theo * `update.status` để kiểm tra sentinel khởi động lại cập nhật mới nhất và xác minh phiên bản đang chạy sau khi khởi động lại Tác tử nên xem `config.schema.lookup` là điểm đến đầu tiên cho tài liệu và ràng buộc chính xác ở cấp trường. Dùng [Tham chiếu cấu hình](/vi/gateway/configuration-reference) khi cần bản đồ cấu hình rộng hơn, giá trị mặc định hoặc liên kết đến các tham chiếu hệ thống con chuyên dụng. Các thao tác ghi mặt phẳng điều khiển (`config.apply`, `config.patch`, `update.run`) bị giới hạn tốc độ ở 3 yêu cầu mỗi 60 giây cho mỗi `deviceId+clientIp`. Yêu cầu khởi động lại được hợp nhất rồi áp dụng thời gian chờ 30 giây giữa các chu kỳ khởi động lại. `update.status` là chỉ đọc nhưng nằm trong phạm vi quản trị vì sentinel khởi động lại có thể bao gồm tóm tắt bước cập nhật và phần cuối đầu ra lệnh. Ví dụ patch một phần: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.patch --params '{ "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }", "baseHash": "" }' ``` Cả `config.apply` và `config.patch` đều chấp nhận `raw`, `baseHash`, `sessionKey`, `note` và `restartDelayMs`. `baseHash` là bắt buộc cho cả hai phương thức khi cấu hình đã tồn tại. `config.patch` cũng chấp nhận `replacePaths`, một mảng các đường dẫn cấu hình mà việc thay thế mảng là có chủ ý. Nếu một patch sẽ thay thế hoặc xóa một mảng hiện có bằng ít mục hơn, Gateway sẽ từ chối ghi trừ khi đường dẫn chính xác đó xuất hiện trong `replacePaths`; các mảng lồng nhau dưới mục mảng dùng `[]`, chẳng hạn như `agents.list[].skills`. Điều này ngăn snapshot `config.get` bị cắt ngắn âm thầm ghi đè các mảng định tuyến hoặc danh sách cho phép. Dùng `config.apply` khi bạn định thay thế toàn bộ cấu hình. ## Biến môi trường OpenClaw đọc biến môi trường từ tiến trình cha cùng với: * `.env` từ thư mục làm việc hiện tại (nếu có) * `~/.openclaw/.env` (dự phòng toàn cục) Không tệp nào ghi đè biến môi trường hiện có. Bạn cũng có thể đặt biến môi trường inline trong cấu hình: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-..." }, }, } ``` Nếu được bật và các khóa mong đợi chưa được đặt, OpenClaw chạy login shell của bạn và chỉ nhập các khóa còn thiếu: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { env: { shellEnv: { enabled: true, timeoutMs: 15000 }, }, } ``` Biến môi trường tương đương: `OPENCLAW_LOAD_SHELL_ENV=1` Tham chiếu biến môi trường trong bất kỳ giá trị chuỗi cấu hình nào bằng `${VAR_NAME}`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } }, models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } }, } ``` Quy tắc: * Chỉ khớp tên viết hoa: `[A-Z_][A-Z0-9_]*` * Biến thiếu/rỗng gây lỗi khi tải * Escape bằng `$${VAR}` để xuất ra literal * Hoạt động bên trong tệp `$include` * Thay thế inline: `"${BASE}/v1"` → `"https://api.example.com/v1"` Đối với các trường hỗ trợ đối tượng SecretRef, bạn có thể dùng: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { models: { providers: { openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } }, }, }, skills: { entries: { "image-lab": { apiKey: { source: "file", provider: "filemain", id: "/skills/entries/image-lab/apiKey", }, }, }, }, channels: { googlechat: { serviceAccountRef: { source: "exec", provider: "vault", id: "channels/googlechat/serviceAccount", }, }, }, } ``` Chi tiết SecretRef (bao gồm `secrets.providers` cho `env`/`file`/`exec`) nằm trong [Quản lý bí mật](/vi/gateway/secrets). Các đường dẫn thông tin xác thực được hỗ trợ được liệt kê trong [Bề mặt thông tin xác thực SecretRef](/vi/reference/secretref-credential-surface). Xem [Môi trường](/vi/help/environment) để biết đầy đủ thứ tự ưu tiên và nguồn. ## Tham chiếu đầy đủ Để xem tham chiếu đầy đủ theo từng trường, xem **[Tham chiếu cấu hình](/vi/gateway/configuration-reference)**. *** *Liên quan: [Ví dụ cấu hình](/vi/gateway/configuration-examples) · [Tham chiếu cấu hình](/vi/gateway/configuration-reference) · [Doctor](/vi/gateway/doctor)* ## Liên quan * [Tham chiếu cấu hình](/vi/gateway/configuration-reference) * [Ví dụ cấu hình](/vi/gateway/configuration-examples) * [Runbook Gateway](/vi/gateway)