`openclaw config`

Công cụ hỗ trợ cấu hình cho các chỉnh sửa không tương tác trong openclaw.json: lấy/đặt/xóa/kiểm tra giá trị theo đường dẫn và in ra file cấu hình đang hoạt động. Chạy mà không có lệnh con để mở trình hướng dẫn cấu hình (giống như openclaw configure).

Ví dụ

openclaw config file
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/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 channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

Đường dẫn

Đường dẫn sử dụng ký hiệu dấu chấm hoặc dấu ngoặc:

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

Sử dụng chỉ số danh sách agent để nhắm đến một agent cụ thể:

openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"

Giá trị

Giá trị được phân tích dưới dạng JSON5 khi có thể; nếu không, chúng được coi là chuỗi. Sử dụng --strict-json để yêu cầu phân tích JSON5. --json vẫn được hỗ trợ như một alias cũ.

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

Các chế độ `config set`

openclaw config set hỗ trợ bốn kiểu gán:

Chế độ giá trị: openclaw config set <path> <value>
Chế độ xây dựng SecretRef:

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

Chế độ xây dựng Provider (chỉ đường dẫn secrets.providers.<alias>):

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

Chế độ hàng loạt (--batch-json hoặc --batch-file):

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

Phân tích hàng loạt luôn sử dụng payload hàng loạt (--batch-json/--batch-file) làm nguồn gốc. --strict-json / --json không thay đổi hành vi phân tích hàng loạt. Chế độ đường dẫn/giá trị JSON vẫn được hỗ trợ cho cả SecretRefs và providers:

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ờ xây dựng Provider

Các mục tiêu xây dựng Provider phải sử dụng secrets.providers.<alias> làm đường dẫn. Các cờ thông dụng:

--provider-source <env|file|exec>
--provider-timeout-ms <ms> (file, exec)

Provider môi trường (--provider-source env):

--provider-allowlist <ENV_VAR> (có thể lặp lại)

Provider file (--provider-source file):

--provider-path <path> (bắt buộc)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>

Provider exec (--provider-source exec):

--provider-command <path> (bắt buộc)
--provider-arg <arg> (có thể lặp lại)
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE> (có thể lặp lại)
--provider-pass-env <ENV_VAR> (có thể lặp lại)
--provider-trusted-dir <path> (có thể lặp lại)
--provider-allow-insecure-path
--provider-allow-symlink-command

Ví dụ về provider exec được bảo vệ:

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

Chạy thử

Sử dụng --dry-run để kiểm tra thay đổi mà không ghi vào openclaw.json.

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

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

Hành vi chạy thử:

Chế độ xây dựng: chạy kiểm tra khả năng giải quyết SecretRef cho các ref/provider đã thay đổi.
Chế độ JSON (--strict-json, --json, hoặc chế độ hàng loạt): chạy kiểm tra schema và khả năng giải quyết SecretRef.
Kiểm tra SecretRef exec bị bỏ qua mặc định trong chạy thử để tránh tác động phụ từ lệnh.
Sử dụng --allow-exec với --dry-run để cho phép kiểm tra SecretRef exec (có thể thực thi lệnh provider).
--allow-exec chỉ dành cho chạy thử và sẽ báo lỗi nếu dùng mà không có --dry-run.

--dry-run --json in ra báo cáo có thể đọc bằng máy:

ok: liệu chạy thử có thành công
operations: số lượng gán được đánh giá
checks: liệu kiểm tra schema/khả năng giải quyết có chạy
checks.resolvabilityComplete: liệu kiểm tra khả năng giải quyết có hoàn thành (false khi các ref exec bị bỏ qua)
refsChecked: số lượng ref thực sự được giải quyết trong chạy thử
skippedExecRefs: số lượng ref exec bị bỏ qua vì --allow-exec không được đặt
errors: lỗi cấu trúc schema/khả năng giải quyết khi ok=false

Định dạng đầu ra JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // có mặt cho lỗi khả năng giải quyết
    },
  ],
}

Ví dụ thành công:

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

Ví dụ thất bại:

{
  "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": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

Nếu chạy thử thất bại:

config schema validation failed: cấu trúc config sau thay đổi không hợp lệ; sửa đường dẫn/giá trị hoặc cấu trúc đối tượng provider/ref.
SecretRef assignment(s) could not be resolved: provider/ref được tham chiếu hiện không thể giải quyết (biến môi trường thiếu, con trỏ file không hợp lệ, lỗi provider exec, hoặc không khớp provider/source).
Dry run note: skipped <n> exec SecretRef resolvability check(s): chạy thử đã bỏ qua các ref exec; chạy lại với --allow-exec nếu cần kiểm tra khả năng giải quyết exec.
Đối với chế độ hàng loạt, sửa các mục bị lỗi và chạy lại --dry-run trước khi ghi.

Lệnh con

config file: In ra đường dẫn file cấu hình đang hoạt động (được giải quyết từ OPENCLAW_CONFIG_PATH hoặc vị trí mặc định).

Khởi động lại gateway sau khi chỉnh sửa.

Kiểm tra

Kiểm tra cấu hình hiện tại so với schema đang hoạt động mà không cần khởi động gateway.

openclaw config validate
openclaw config validate --json

Tổng quan cài đặt

Chạy qua Container

Triển khai (Hosting)

Bảo trì & Nâng cấp

config

`openclaw config`

Ví dụ

Đường dẫn

Giá trị

Các chế độ `config set`

Cờ xây dựng Provider

Chạy thử

Định dạng đầu ra JSON

Lệnh con

Kiểm tra

​openclaw config

​Ví dụ

​Đường dẫn

​Giá trị

​Các chế độ config set

​Cờ xây dựng Provider

​Chạy thử

​Định dạng đầu ra JSON

​Lệnh con

​Kiểm tra

`openclaw config`

Ví dụ

Đường dẫn

Giá trị

Các chế độ `config set`

Cờ xây dựng Provider

Chạy thử

Định dạng đầu ra JSON

Lệnh con

Kiểm tra