OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

設定

openclaw.json 用の非対話型ヘルパーです。パスによる値の取得、設定、パッチ、設定解除、スキーマの出力、検証、または有効なファイルパスの出力を行います。サブコマンドなしで openclaw config を実行すると、openclaw configure と同じガイド付きウィザードが開きます。

ルートオプション

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> サブコマンドなしで openclaw config を実行するときに使用する、繰り返し指定可能なガイド付きセットアップのセクションフィルターです。

ガイド付きセクション：workspace、model、web、gateway、daemon、channels、plugins、skills、health。

例

bash
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

パス

ドット記法またはブラケット記法を使用します。zsh が [0] をグロブ展開しないように、シェルの例ではブラケット記法のパスを引用符で囲みます。

bash
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

秘匿化された設定スナップショットから値を読み取ります（シークレットは決して出力されません）。--json は未加工の値を JSON として出力します。それ以外の場合、文字列、数値、真偽値はそのまま出力され、オブジェクトと配列は整形済み JSON として出力されます。

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

config file

OPENCLAW_CONFIG_PATH またはデフォルトの場所から解決した、有効な設定ファイルのパスを出力します。このパスが指すのはシンボリックリンクではなく通常のファイルです。書き込みの安全性を参照してください。

config schema

生成された openclaw.json 用 JSON スキーマを標準出力へ出力します。

含まれる内容
  • 現在のルート設定スキーマと、エディターツール用のルート $schema 文字列フィールド。
  • Control UI が使用するフィールドの title / description ドキュメントメタデータ。
  • 対応するフィールドドキュメントが存在する場合、ネストされたオブジェクト、ワイルドカード（*）、配列項目（[]）のノードにも同じ title / description メタデータが継承されます。
  • anyOf / oneOf / allOf の分岐にも同じドキュメントメタデータが継承されます。
  • ランタイムマニフェストを読み込める場合、可能な範囲で取得した現在の Plugin とチャンネルのスキーマメタデータ。
  • 現在の設定が無効な場合でも使用できる、簡潔なフォールバックスキーマ。
関連するランタイム RPC

config.schema.lookup は、正規化された設定パス 1 件について、浅いスキーマノード（title、description、type、enum、const、一般的な境界値）、一致する UI ヒントメタデータ、直下の子要素の概要を返します。Control UI またはカスタムクライアントで、パスを対象とした詳細表示に使用します。

bash
openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

Gateway を起動せずに、現在の設定を有効なスキーマに対して検証します。

bash
openclaw config validateopenclaw config validate --json

値

値は可能な場合 JSON5 として解析されます。それ以外の場合は未加工の文字列として扱われます。文字列へのフォールバックなしで標準 JSON を必須にするには、--strict-json を使用します。この場合、コメント、末尾のカンマ、引用符なしのキーなど、JSON5 固有の構文は拒否されます。config set では、--json は --strict-json のレガシーエイリアスです。

bash
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 は、端末向けに整形されたテキストではなく、未加工の値を JSON として出力します。

これらのマップにエントリを追加するときは --merge を使用します。

bash
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 のモード

値モード

bash
openclaw config set <path> <value>

SecretRef ビルダーモード

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

プロバイダービルダーモード

対象にできるのは secrets.providers.<alias> パスのみです。

bash
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

バッチモード

bash
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" }  }]'
bash
openclaw config set --batch-file ./config-set.batch.json --dry-run

バッチ解析では、常にバッチペイロード（--batch-json/--batch-file）が信頼できる情報源として使用されます。--strict-json / --json はバッチ解析の動作を変更しません。

JSON のパス／値モードを使って、SecretRef とプロバイダーを直接設定することもできます。

bash
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> を使用する必要があります。

共通フラグ
  • --provider-source <env|file|exec>
  • --provider-timeout-ms <ms>（file、exec）
環境変数プロバイダー（--provider-source env）
  • --provider-allowlist &lt;ENV_VAR&gt;（繰り返し指定可能）
ファイルプロバイダー（--provider-source file）
  • --provider-path <path>（必須）
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
実行プロバイダー（--provider-source exec）
  • --provider-command <path>（必須）
  • --provider-arg <arg>（繰り返し指定可能）
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env &lt;KEY=VALUE&gt;（繰り返し指定可能）
  • --provider-pass-env &lt;ENV_VAR&gt;（繰り返し指定可能）
  • --provider-trusted-dir <path>（繰り返し指定可能）
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command

強化された実行プロバイダーの例：

bash
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

パスベースの config set コマンドを多数実行する代わりに、設定と同じ形状の JSON5 パッチを貼り付けるか、パイプで渡します。オブジェクトは再帰的にマージされ、配列とスカラー値は対象を置き換え、null は対象パスを削除します。

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

リモートセットアップスクリプトでは、標準入力からパッチをパイプで渡します。

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

パッチの例：

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

オブジェクトまたは配列を再帰的にパッチするのではなく、指定した値で完全に置き換える必要がある場合は、--replace-path <path> を使用します。

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

--dry-run は書き込みを行わず、スキーマと SecretRef の解決可能性を確認します。実行コマンドを使用する SecretRef は、デフォルトではドライラン中にスキップされます。ドライランで意図的にプロバイダーコマンドを実行する場合は、--allow-exec を追加します。

ドライラン

--dry-run は openclaw.json に書き込まずに変更を検証します。config set、config patch、config unset で使用できます。

bash
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
ドライランの動作
  • ビルダーモード: 変更された参照/プロバイダーに対して SecretRef の解決可否チェックを実行します。
  • JSON モード（--strict-json、--json、またはバッチモード）: スキーマ検証と SecretRef の解決可否チェックを実行します。
  • ポリシー検証は変更後の設定全体に対して実行されるため、親オブジェクトへの書き込み（たとえば hooks をオブジェクトとして設定する場合）によって、未対応の対象領域に対する検証を回避することはできません。
  • コマンドの副作用を避けるため、Exec SecretRef のチェックはデフォルトでスキップされます。明示的に有効化するには --allow-exec を渡します（プロバイダーのコマンドが実行される場合があります）。--allow-exec はドライラン専用であり、--dry-run なしで使用するとエラーになります。
--dry-run --json のフィールド
  • ok: ドライランに成功したかどうか
  • operations: 評価された代入の数
  • checks: スキーマ/解決可否チェックが実行されたかどうか
  • checks.resolvabilityComplete: 解決可否チェックが完了まで実行されたかどうか（Exec 参照がスキップされた場合は false）
  • refsChecked: ドライラン中に実際に解決された参照の数
  • skippedExecRefs: --allow-exec が設定されていないためスキップされた Exec 参照の数
  • errors: ok=false の場合に発生した、構造化されたパス欠落、スキーマ、または解決可否のエラー

JSON 出力の形式

json5
{  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, // 解決可否エラーの場合に存在    },  ],}

成功例

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

失敗例

json
{  "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": "エラー: 環境変数 \"MISSING_TEST_SECRET\" が設定されていません。",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}
ドライランが失敗した場合
  • config schema validation failed: 変更後の設定形式が無効です。パス/値またはプロバイダー/参照オブジェクトの形式を修正してください。
  • Config policy validation failed: unsupported SecretRef usage: その認証情報をプレーンテキスト/文字列入力に戻してください。SecretRef は対応している対象領域でのみ使用してください。
  • SecretRef assignment(s) could not be resolved: 参照先のプロバイダー/参照を現在解決できません（環境変数の欠落、無効なファイルポインター、Exec プロバイダーの失敗、またはプロバイダーとソースの不一致）。
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): Exec の解決可否を検証する必要がある場合は、--allow-exec を指定して再実行してください。
  • バッチモードでは、失敗したエントリを修正し、書き込む前に --dry-run を再実行してください。

変更の適用

config set / config patch / config unset が正常に完了するたびに、Gateway の再起動が必要かどうかを判断できるよう、CLI は次の 3 つのヒントのいずれかを表示します。

ヒント 意味
Restart the gateway to apply. 変更されたパスには完全な再起動が必要です。
Change will apply without restarting the gateway. ホットリロードによって自動的に反映されます。
No gateway restart needed. ランタイムに関係する変更はありません。

CLI はすべての Plugin のリロードメタデータが読み込まれていることを確認できないため、plugins.entries（またはそのサブパス）への書き込みには常に再起動が必要です。

書き込みの安全性

openclaw config set および OpenClaw が管理するその他の設定書き込み機能は、ディスクに確定する前に変更後の設定全体を検証します。新しいペイロードがスキーマ検証に失敗するか、破壊的な上書きと判断された場合、アクティブな設定は変更されず、拒否されたペイロードがその隣に openclaw.json.rejected.* として保存されます。

小規模な編集には CLI による書き込みを推奨します。

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

書き込みが拒否された場合は、保存されたペイロードを確認し、設定全体の形式を修正してください。

bash
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 設定など、無関係なユーザー設定をロールバックせず、明示的なエラーとして扱われます。

修復ループ

openclaw config validate に成功したら、同じターミナルから各変更を検証しながら、ローカル TUI を使用して組み込みエージェントにアクティブな設定とドキュメントを比較させます。

bash
openclaw chat

TUI 内では、先頭に ! を付けると、ローカルシェルコマンドがそのまま実行されます（セッションごとに初回のみ確認プロンプトが表示されます）。

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

  • ドキュメントとの比較

    現在の設定を関連するドキュメントページと比較し、最小限の修正を提案するようエージェントに依頼します。

  • 対象を絞った編集の適用

    openclaw config set または openclaw configure を使用して、対象を絞った編集を適用します。

  • 再検証

    変更するたびに openclaw config validate を再実行します。

  • ランタイムの問題に対する doctor の使用

    検証に成功してもランタイムが正常でない場合は、移行と修復の支援のために openclaw doctor または openclaw doctor --fix を実行します。

    • 関連項目

    Was this useful?
    On this page

    On this page