پیکربندی

راهنماهای پیکربندی برای ویرایش‌های غیرتعاملی در openclaw.json: دریافت/تنظیم/وصله/لغو تنظیم/فایل/طرح‌واره/اعتبارسنجی مقدارها بر اساس مسیر و چاپ فایل پیکربندی فعال. بدون زیرفرمان اجرا کنید تا جادوگر پیکربندی باز شود (همانند openclaw configure).

گزینه‌های ریشه

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> فیلتر بخش راه‌اندازی هدایت‌شده و قابل تکرار، وقتی openclaw config را بدون زیرفرمان اجرا می‌کنید.

بخش‌های هدایت‌شده پشتیبانی‌شده: workspace، model، web، gateway، daemon، channels، plugins، skills، health.

مثال‌ها

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

config schema

طرح‌واره JSON تولیدشده برای openclaw.json را به‌صورت JSON در stdout چاپ کنید.

openclaw config schema

وقتی می‌خواهید آن را با ابزارهای دیگر بررسی یا اعتبارسنجی کنید، خروجی را به یک فایل پایپ کنید:

openclaw config schema > openclaw.schema.json

مسیرها

مسیرها از نگارش نقطه‌ای یا کروشه‌ای استفاده می‌کنند. مسیرهای با نگارش کروشه‌ای را در مثال‌های پوسته داخل نقل‌قول بگذارید تا پوسته‌هایی مانند zsh، پیش از دریافت مسیر توسط OpenClaw، [0] را به‌عنوان glob گسترش ندهند:

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"

مقدارها

مقدارها در صورت امکان به‌عنوان JSON5 تجزیه می‌شوند؛ در غیر این صورت به‌عنوان رشته در نظر گرفته می‌شوند. برای الزام به تجزیه JSON استاندارد بدون جایگزین رشته‌ای، از --strict-json استفاده کنید. --json همچنان به‌عنوان نام مستعار قدیمی برای --strict-json پشتیبانی می‌شود.

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

وقتی --strict-json فعال باشد، نحوهای فقط JSON5 مانند نظرها، ویرگول‌های پایانی، یا کلیدهای شیء بدون نقل‌قول رد می‌شوند. برای تجزیه مقدار JSON5 همراه با جایگزین رشته خام، --strict-json را حذف کنید.

config get <path> --json مقدار خام را به‌جای متن قالب‌بندی‌شده ترمینال، به‌صورت JSON چاپ می‌کند.

هنگام افزودن ورودی‌ها به این نقشه‌ها از --merge استفاده کنید:

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

فقط وقتی از --replace استفاده کنید که عمدا می‌خواهید مقدار ارائه‌شده، مقدار کامل هدف شود.

حالت‌های config set

openclaw 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

تجزیه دسته‌ای همیشه از بار دسته‌ای (--batch-json/--batch-file) به‌عنوان منبع حقیقت استفاده می‌کند. --strict-json / --json رفتار تجزیه دسته‌ای را تغییر نمی‌دهند.

config patch

وقتی می‌خواهید به‌جای اجرای تعداد زیادی فرمان مسیرمحور config set، یک وصله با شکل پیکربندی را جای‌گذاری یا پایپ کنید، از config patch استفاده کنید. ورودی یک شیء JSON5 است. شیءها به‌صورت بازگشتی ادغام می‌شوند، آرایه‌ها و مقدارهای اسکالر مقدار هدف را جایگزین می‌کنند، و null مسیر هدف را حذف می‌کند.

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

همچنین می‌توانید یک وصله را از طریق stdin پایپ کنید، که برای اسکریپت‌های راه‌اندازی راه‌دور مفید است:

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

نمونه وصله:

{  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.5" },      models: {        "openai/gpt-5.5": { params: { fastMode: true } },      },    },  },}

وقتی یک شیء یا آرایه باید دقیقا به مقدار ارائه‌شده تبدیل شود، به‌جای اینکه به‌صورت بازگشتی وصله شود، از --replace-path <path> استفاده کنید:

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

--dry-run بررسی‌های طرح‌واره و قابل‌حل‌بودن SecretRef را بدون نوشتن اجرا می‌کند. SecretRefهای مبتنی بر exec در حالت dry-run به‌صورت پیش‌فرض نادیده گرفته می‌شوند؛ وقتی عمدا می‌خواهید dry-run فرمان‌های ارائه‌دهنده را اجرا کند، --allow-exec را اضافه کنید.

حالت مسیر/مقدار JSON همچنان برای SecretRefها و ارائه‌دهنده‌ها پشتیبانی می‌شود:

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

پرچم‌های سازنده ارائه‌دهنده

هدف‌های سازنده ارائه‌دهنده باید از secrets.providers.<alias> به‌عنوان مسیر استفاده کنند.

نمونه ارائه‌دهنده exec سخت‌سازی‌شده:

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

اجرای آزمایشی

برای اعتبارسنجی تغییرها بدون نوشتن در openclaw.json، از --dry-run استفاده کنید.

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

شکل خروجی 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",      message: string,      ref?: string, // present for resolvability errors    },  ],}

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

ایمنی نوشتن

openclaw config set و سایر نویسنده‌های پیکربندی متعلق به OpenClaw، پیش از ثبت روی دیسک، کل پیکربندی پس از تغییر را اعتبارسنجی می‌کنند. اگر بار جدید در اعتبارسنجی طرح‌واره شکست بخورد یا شبیه بازنویسی مخرب باشد، پیکربندی فعال دست‌نخورده می‌ماند و بار ردشده کنار آن با نام openclaw.json.rejected.* ذخیره می‌شود.

برای ویرایش‌های کوچک، نوشتن با CLI را ترجیح دهید:

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

اگر نوشتن رد شد، بار ذخیره‌شده را بررسی کنید و شکل کامل پیکربندی را اصلاح کنید:

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

نوشتن مستقیم با ویرایشگر همچنان مجاز است، اما Gateway در حال اجرا تا زمانی که اعتبارسنجی نشود با آن به‌عنوان نامطمئن رفتار می‌کند. ویرایش‌های مستقیم نامعتبر باعث شکست راه‌اندازی می‌شوند یا توسط بارگذاری مجدد داغ رد می‌شوند؛ Gateway فایل openclaw.json را بازنویسی نمی‌کند. برای تعمیر پیکربندی پیشونددار/بازنویسی‌شده یا بازیابی آخرین نسخه سالم شناخته‌شده، openclaw doctor --fix را اجرا کنید. عیب‌یابی Gateway را ببینید.

بازیابی کل فایل فقط برای تعمیر doctor نگه داشته شده است. تغییرات طرح‌واره Plugin یا ناهمخوانی minHostVersion به‌جای برگشت‌دادن تنظیمات نامرتبط کاربر مانند پیکربندی مدل‌ها، ارائه‌دهندگان، پروفایل‌های احراز هویت، کانال‌ها، آشکارسازی gateway، ابزارها، حافظه، مرورگر، یا cron، آشکارا خطا می‌دهند.

زیرفرمان‌ها

• config file: مسیر فایل پیکربندی فعال را چاپ می‌کند (حل‌شده از OPENCLAW_CONFIG_PATH یا مکان پیش‌فرض). مسیر باید به یک فایل عادی اشاره کند، نه symlink.

پس از ویرایش‌ها، gateway را دوباره راه‌اندازی کنید.

اعتبارسنجی

پیکربندی فعلی را بدون راه‌اندازی gateway در برابر طرح‌واره فعال اعتبارسنجی کنید.

openclaw config validateopenclaw config validate --json

پس از موفق‌شدن openclaw config validate، می‌توانید از TUI محلی استفاده کنید تا یک عامل تعبیه‌شده پیکربندی فعال را با مستندات مقایسه کند، درحالی‌که هر تغییر را از همان پایانه اعتبارسنجی می‌کنید:

openclaw chat

سپس داخل TUI:

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

چرخه معمول تعمیر:

مرتبط

• مرجع CLI
• پیکربندی