Cấu hình

Trình trợ giúp không tương tác cho openclaw.json: lấy/đặt/vá/hủy đặt một giá trị theo đường dẫn, in schema, xác thực hoặc in đường dẫn tệp đang hoạt động. Chạy openclaw config mà không có lệnh con để mở cùng trình hướng dẫn từng bước như openclaw configure.

Tùy chọn gốc

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> Bộ lọc phần thiết lập có hướng dẫn, có thể lặp lại, khi bạn chạy openclaw config mà không có lệnh con.

Các phần có hướng dẫn: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Ví dụ

openclaw config fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"openclaw config set agents.defaults.heartbeat.every "2h"openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json

Đường dẫn

Ký hiệu dấu chấm hoặc dấu ngoặc. Hãy đặt đường dẫn có dấu ngoặc trong dấu nháy ở các ví dụ shell để zsh không mở rộng glob [0]:

openclaw config get agents.defaults.workspaceopenclaw config get 'agents.list[0].id'openclaw config get agents.listopenclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

config get

Đọc một giá trị từ ảnh chụp nhanh cấu hình đã che thông tin nhạy cảm (các bí mật không bao giờ được in). --json in giá trị thô dưới dạng JSON; nếu không, chuỗi/số/giá trị boolean được in trực tiếp, còn đối tượng/mảng được in dưới dạng JSON đã định dạng.

Khi không có đường dẫn, --json ghi { "error": "Config path not found: <path>" } vào stdout và thoát với trạng thái 1. Nếu không có --json, thông báo chẩn đoán vẫn nằm trên stderr.

openclaw config get browser.executablePathopenclaw config get agents.defaults.model --json

config file

In đường dẫn tệp cấu hình đang hoạt động, được phân giải từ OPENCLAW_CONFIG_PATH hoặc vị trí mặc định. Đường dẫn trỏ đến một tệp thông thường, không phải liên kết tượng trưng; xem An toàn khi ghi.

config schema

In schema JSON đã tạo cho openclaw.json ra stdout.

openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

Xác thực cấu hình hiện tại theo schema đang hoạt động mà không khởi động Gateway.

openclaw config validateopenclaw config validate --json

Giá trị

Các giá trị được phân tích cú pháp dưới dạng JSON5 khi có thể; nếu không, chúng được coi là chuỗi thô. Dùng --strict-json để bắt buộc sử dụng JSON chuẩn mà không dự phòng sang chuỗi (khi đó cú pháp chỉ có trong JSON5 như chú thích, dấu phẩy cuối hoặc khóa không đặt trong dấu nháy sẽ bị từ chối). --json là bí danh cũ của --strict-json trên config set.

openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json in giá trị thô dưới dạng JSON thay vì văn bản được định dạng cho terminal.

Khi một lần ghi thay đổi agents.defaults.model hoặc agents.list[].model của từng tác nhân, OpenClaw phân giải từng mô hình chính hoặc dự phòng đã thay đổi thông qua các danh mục nhà cung cấp đã cấu hình trước khi ghi. Các tham chiếu mô hình không xác định bị từ chối mà không thay đổi cấu hình đang hoạt động; chạy openclaw models list để xem các mô hình có sẵn.

Dùng --merge khi thêm mục vào các ánh xạ đó:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

Chỉ dùng --replace khi giá trị được cung cấp chủ ý trở thành toàn bộ giá trị đích.

Các chế độ config set

openclaw config set <path> <value>

openclaw config set channels.discord.token \  --ref-provider default \  --ref-source env \  --ref-id DISCORD_BOT_TOKEN

openclaw config set secrets.providers.vault \  --provider-source exec \  --provider-command /usr/local/bin/openclaw-vault \  --provider-arg read \  --provider-arg openai/api-key \  --provider-timeout-ms 5000

openclaw config set --batch-json '[  {    "path": "secrets.providers.default",    "provider": { "source": "env" }  },  {    "path": "channels.discord.token",    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }  }]'

openclaw config set --batch-file ./config-set.batch.json --dry-run

Quá trình phân tích cú pháp hàng loạt luôn dùng tải trọng hàng loạt (--batch-json/--batch-file) làm nguồn sự thật; --strict-json / --json không thay đổi hành vi phân tích cú pháp hàng loạt.

Chế độ đường dẫn/giá trị JSON cũng hoạt động trực tiếp với SecretRef và nhà cung cấp:

openclaw config set channels.discord.token \  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \  --strict-json openclaw config set secrets.providers.vaultfile \  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \  --strict-json

Cờ trình dựng nhà cung cấp

Các đích của trình dựng nhà cung cấp phải dùng secrets.providers.<alias> làm đường dẫn.

Ví dụ về nhà cung cấp thực thi được gia cố:

openclaw config set secrets.providers.vault \  --provider-source exec \  --provider-command /usr/local/bin/openclaw-vault \  --provider-arg read \  --provider-arg openai/api-key \  --provider-json-only \  --provider-pass-env VAULT_TOKEN \  --provider-trusted-dir /usr/local/bin \  --provider-timeout-ms 5000

config patch

Dán hoặc chuyển qua pipe một bản vá JSON5 có hình dạng cấu hình thay vì chạy nhiều lệnh config set dựa trên đường dẫn. Các đối tượng được hợp nhất đệ quy; mảng và giá trị vô hướng thay thế đích; null xóa đường dẫn đích.

openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5

Các tệp bản vá bị giới hạn ở 8 MiB. Các bản vá --stdin được chuyển qua pipe bị giới hạn ở 1 MiB.

Chuyển bản vá qua stdin cho các tập lệnh thiết lập từ xa:

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Bản vá mẫu:

{  channels: {    slack: {      enabled: true,      mode: "socket",      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },      groupPolicy: "open",      requireMention: false,    },    discord: {      enabled: true,      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },      dmPolicy: "disabled",      dm: { enabled: false },      groupPolicy: "allowlist",    },  },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },      models: {        "openai/gpt-5.6-sol": { params: { fastMode: true } },      },    },  },}

Dùng --replace-path <path> khi một đối tượng hoặc mảng phải trở thành chính xác giá trị được cung cấp thay vì được vá đệ quy:

openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run chạy các kiểm tra về schema và khả năng phân giải SecretRef mà không ghi dữ liệu. Theo mặc định, các SecretRef dựa trên exec bị bỏ qua trong quá trình chạy thử; thêm --allow-exec khi bạn chủ ý muốn quá trình chạy thử thực thi các lệnh của nhà cung cấp.

Chạy thử

--dry-run xác thực các thay đổi mà không ghi openclaw.json. Có trên config set, config patch và config unset.

openclaw config set channels.discord.token \  --ref-provider default \  --ref-source env \  --ref-id DISCORD_BOT_TOKEN \  --dry-run \  --json openclaw config set channels.discord.token \  --ref-provider vault \  --ref-source exec \  --ref-id discord/token \  --dry-run \  --allow-exec

Cấu trúc đầu ra JSON

{  ok: boolean,  operations: number,  configPath: string,  inputModes: ["value" | "json" | "builder" | "unset", ...],  checks: {    schema: boolean,    resolvability: boolean,    resolvabilityComplete: boolean,  },  refsChecked: number,  skippedExecRefs: number,  errors?: [    {      kind: "missing-path" | "schema" | "resolvability" | "model",      message: string,      ref?: string, // có mặt đối với lỗi khả năng phân giải    },  ],}

{  "ok": true,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0}

{  "ok": false,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0,  "errors": [    {      "kind": "resolvability",      "message": "Lỗi: Biến môi trường \"MISSING_TEST_SECRET\" chưa được đặt.",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}

Áp dụng thay đổi

Sau mỗi lần config set / config patch / config unset thành công, CLI in ra một trong ba gợi ý để bạn biết Gateway có cần khởi động lại hay không:

Việc ghi vào plugins.entries (hoặc bất kỳ đường dẫn con nào) luôn yêu cầu khởi động lại, vì CLI không thể xác minh rằng siêu dữ liệu tải lại của mọi plugin đã được nạp.

An toàn khi ghi

openclaw config set và các trình ghi cấu hình khác do OpenClaw sở hữu xác thực toàn bộ cấu hình sau thay đổi trước khi ghi cấu hình đó vào đĩa. Nếu nội dung mới không vượt qua xác thực schema hoặc có vẻ là thao tác ghi đè phá hủy, cấu hình đang hoạt động sẽ được giữ nguyên và nội dung bị từ chối được lưu bên cạnh dưới dạng openclaw.json.rejected.*.

Các thao tác ghi do OpenClaw sở hữu sẽ tuần tự hóa lại JSON5 thành JSON tiêu chuẩn. Khi nguồn chứa chú thích, trình ghi sẽ cảnh báo ngay trước khi xóa chúng; hãy dùng trình chỉnh sửa trực tiếp khi cần giữ lại chú thích.

Ưu tiên ghi bằng CLI cho các chỉnh sửa nhỏ:

openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

Nếu thao tác ghi bị từ chối, hãy kiểm tra nội dung đã lưu và sửa toàn bộ cấu trúc cấu hình:

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headopenclaw config validate

Vẫn được phép ghi trực tiếp bằng trình chỉnh sửa, nhưng Gateway đang chạy sẽ coi các thay đổi đó là không đáng tin cậy cho đến khi chúng vượt qua xác thực. Các chỉnh sửa trực tiếp không hợp lệ sẽ khiến quá trình khởi động thất bại hoặc bị bỏ qua khi tải lại nóng; Gateway không ghi lại openclaw.json. Chạy openclaw doctor --fix để sửa cấu hình có tiền tố/bị ghi đè hoặc khôi phục bản sao tốt gần nhất đã biết. Xem Khắc phục sự cố Gateway.

Khôi phục toàn bộ tệp chỉ dành cho việc sửa chữa bằng doctor. Các thay đổi schema của plugin hoặc độ lệch minHostVersion vẫn được báo rõ thay vì hoàn tác các cài đặt không liên quan của người dùng như cấu hình mô hình, nhà cung cấp, hồ sơ xác thực, kênh, mức độ mở Gateway, công cụ, bộ nhớ, trình duyệt hoặc cron.

Vòng lặp sửa chữa

Sau khi openclaw config validate thành công, hãy dùng TUI cục bộ để một agent nhúng so sánh cấu hình đang hoạt động với tài liệu trong khi bạn xác thực từng thay đổi từ cùng một terminal:

openclaw chat

Bên trong TUI, ký tự ! ở đầu sẽ chạy một lệnh shell cục bộ theo đúng nghĩa đen (sau lời nhắc xác nhận một lần cho mỗi phiên):

!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor

Liên quan

• Tham chiếu CLI
• Cấu hình