پیکربندی

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

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

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

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

# نمونه‌ها

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw 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 --merge
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 patch --file ./openclaw.patch.json5 --dry-run
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

# config schema

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

openclaw config schema

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

openclaw config schema > openclaw.schema.json

# مسیرها

مسیرها از نشانه‌گذاری نقطه‌ای یا کروشه‌ای استفاده می‌کنند:

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

برای هدف‌گیری یک Agent مشخص، از اندیس فهرست Agent استفاده کنید:

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

# مقادیر

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

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

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

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

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw 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

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

# config patch

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

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

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

ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh 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 بررسی‌های طرحواره و قابلیت resolve شدن SecretRef را بدون نوشتن اجرا می‌کند. SecretRefهای مبتنی بر exec هنگام dry-run به‌صورت پیش‌فرض نادیده گرفته می‌شوند؛ وقتی عمداً می‌خواهید dry-run فرمان‌های provider را اجرا کند، --allow-exec را اضافه کنید.

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

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

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

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

نمونه provider سخت‌سازی‌شده مبتنی بر 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

# Dry run

برای اعتبارسنجی تغییرات بدون نوشتن در 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", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "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، پیش از ثبت کردن پیکربندی روی دیسک، کل پیکربندی پس از تغییر را اعتبارسنجی می‌کنند. اگر payload جدید در اعتبارسنجی schema ناموفق شود یا شبیه clobber مخرب به نظر برسد، پیکربندی فعال دست‌نخورده می‌ماند و payload ردشده در کنار آن با نام openclaw.json.rejected.* ذخیره می‌شود.

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

openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

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

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

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

بازیابی کل فایل فقط برای ترمیم با doctor محفوظ است. تغییرات schema مربوط به Plugin یا skew در minHostVersion پرصدا می‌مانند، به‌جای اینکه تنظیمات نامرتبط کاربر مانند مدل‌ها، providerها، نمایه‌های احراز هویت، کانال‌ها، exposure در Gateway، ابزارها، حافظه، مرورگر یا پیکربندی cron را برگردانند.

# زیر‌فرمان‌ها

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

پس از ویرایش‌ها Gateway را restart کنید.

# اعتبارسنجی

پیکربندی فعلی را بدون شروع Gateway، در برابر schema فعال اعتبارسنجی کنید.

openclaw config validate
openclaw config validate --json

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

openclaw chat

سپس داخل TUI:

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

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

# مرتبط

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