openclaw config を使った効率的な設定管理

設定ファイルを手動で編集していると、うっかり構文を間違えてしまい、アプリケーションが起動しなくなって冷や汗をかいた経験はありませんか？設定の整合性を保ちながら、安全かつ効率的に変更を加えることは、開発者にとって常に頭の痛い問題です。

OpenClaw の設定管理機能を使えば、OpenClaw の設定項目をコマンドラインから直接、かつ安全に操作できます。このガイドでは、OpenClaw の設定を効率的に管理するための CLI コマンドの使い方を詳しく解説します。

openclaw config

このコマンドは、openclaw.json を非対話的に編集するためのヘルパーツールです。パスを指定して値の取得・設定・削除を行ったり、スキーマの検証や現在の設定ファイルのパスを確認したりできます。サブコマンドを指定せずに実行すると、設定ウィザードが起動します（openclaw configure と同じ動作です）。

ルートオプション：

• --section <section>: サブコマンドなしで openclaw config を実行する際、ガイド付きセットアップのセクションをフィルタリングします。

サポートされているセクション：

• workspace
• model
• web
• gateway
• daemon
• channels
• plugins
• skills
• health

Examples

設定の確認や変更は、以下のコマンドで行うことができます。

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 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

config schema

現在の openclaw.json に対応する JSON スキーマを標準出力に表示します。

これには以下の情報が含まれます：

1. 現在のルート設定スキーマと、エディタツール用のルート $schema 文字列フィールド。
2. Control UI で使用されるフィールドの title および description メタデータ。
3. ネストされたオブジェクト、ワイルドカード (*)、配列アイテム ([]) ノードは、フィールドドキュメントが存在する場合、同じ title / description メタデータを継承します。
4. anyOf / oneOf / allOf ブランチも、同様にドキュメントメタデータを継承します。
5. ランタイムマニフェストが読み込める場合、プラグインやチャンネルのライブスキーマメタデータが含まれます。
6. 現在の設定が無効な場合でも、クリーンなフォールバックスキーマを提供します。

関連するランタイム RPC：

• config.schema.lookup は、正規化された設定パスと、浅いスキーマノード（title, description, type, enum, const など）、UI ヒントメタデータ、および子要素の要約を返します。Control UI やカスタムクライアントでの詳細なドリルダウンに使用してください。

openclaw config schema

他のツールで検査や検証を行いたい場合は、ファイルにパイプしてください：

openclaw config schema > openclaw.schema.json

パス指定

パスにはドット記法またはブラケット記法を使用します。

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

エージェントリストのインデックスを使用して、特定のエージェントをターゲットにします。

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

Values

値は可能な限り 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 として出力します。

config set modes

openclaw config set は、4 つの代入スタイルをサポートしています。

1. 値モード: openclaw config set <path> <value>
2. SecretRef ビルダーモード:

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

3. プロバイダービルダーモード (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

4. バッチモード (--batch-json または --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

ポリシーに関する注意：

• SecretRef の割り当ては、ランタイムで変更できない表面（hooks.token、commands.ownerDisplaySecret、Discord スレッドバインディング webhook トークン、WhatsApp 認証情報 JSON など）では拒否されます。詳細は SecretRef Credential Surface を参照してください。

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

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

Provider Builder Flags

プロバイダービルダーのターゲットには、パスとして secrets.providers.<alias> を使用する必要があります。

共通フラグ：

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

Env プロバイダー (--provider-source env):

• --provider-allowlist <ENV_VAR> (繰り返し可能)

File プロバイダー (--provider-source file):

• --provider-path <path> (必須)
• --provider-mode <singleValue|json>
• --provider-max-bytes <bytes>

Exec プロバイダー (--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 <KEY=VALUE> (繰り返し可能)
• --provider-pass-env <ENV_VAR> (繰り返し可能)
• --provider-trusted-dir <path> (繰り返し可能)
• --provider-allow-insecure-path
• --provider-allow-symlink-command

ハードニングされた 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

--dry-run を使用すると、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

Dry-run の動作：

• ビルダーモード: 変更された ref/プロバイダーの SecretRef 解決可能性チェックを実行します。
• JSON モード (--strict-json, --json, またはバッチモード): スキーマ検証と SecretRef 解決可能性チェックを実行します。
• ポリシー検証は、サポートされていない SecretRef ターゲットに対しても実行されます。
• ポリシーチェックは変更後の完全な設定を評価するため、親オブジェクトの書き込み（例：hooks をオブジェクトとして設定）によって検証を回避することはできません。
• Exec SecretRef チェックは、コマンドの副作用を避けるため、デフォルトではスキップされます。
• --dry-run とともに --allow-exec を使用すると、Exec SecretRef チェックを有効にできます（プロバイダーコマンドが実行される可能性があります）。
• --allow-exec は Dry-run 専用であり、それ以外で使用するとエラーになります。

--dry-run --json は、機械可読なレポートを出力します。

• ok: Dry-run が成功したかどうか
• operations: 評価された代入の数
• checks: スキーマ/解決可能性チェックが実行されたかどうか
• checks.resolvabilityComplete: 解決可能性チェックが完了したかどうか（Exec ref がスキップされた場合は false）
• refsChecked: Dry-run 中に実際に解決された ref の数
• skippedExecRefs: --allow-exec が設定されていないためにスキップされた Exec ref の数
• errors: ok=false の場合の構造化されたスキーマ/解決可能性エラー

JSON Output Shape

{
  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"
    }
  ]
}

Dry-run が失敗した場合：

• config schema validation failed: 変更後の設定形状が無効です。パス/値またはプロバイダー/ref オブジェクトの形状を修正してください。
• Config policy validation failed: unsupported SecretRef usage: 該当する認証情報をプレーンテキスト/文字列入力に戻し、SecretRef はサポートされている表面でのみ使用してください。
• SecretRef assignment(s) could not be resolved: 参照されているプロバイダー/ref が解決できません（環境変数の欠落、無効なファイルポインタ、Exec プロバイダーの失敗、またはプロバイダー/ソースの不一致）。
• Dry run note: skipped <n> exec SecretRef resolvability check(s): Dry-run が Exec ref をスキップしました。解決可能性の検証が必要な場合は --allow-exec を付けて再実行してください。
• バッチモードの場合は、失敗したエントリを修正し、書き込み前に --dry-run を再実行してください。

Write safety

openclaw config set およびその他の OpenClaw 関連の設定書き込みツールは、ディスクにコミットする前に変更後の完全な設定を検証します。新しいペイロードがスキーマ検証に失敗したり、破壊的な上書きと見なされたりした場合、アクティブな設定は変更されず、拒否されたペイロードが openclaw.json.rejected.* として保存されます。

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

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

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

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

直接エディタで書き込むことも可能ですが、実行中の Gateway は検証されるまでそれらを信頼しません。無効な直接編集は、起動時またはホットリロード時に、最後に正常だったバックアップから復元できます。詳細は Gateway troubleshooting を参照してください。

Subcommands

• config file: アクティブな設定ファイルのパスを表示します（OPENCLAW_CONFIG_PATH またはデフォルトの場所から解決されます）。

編集後は Gateway を再起動してください。

Validate

Gateway を起動せずに、アクティブなスキーマに対して現在の設定を検証します。

openclaw config validate
openclaw config validate --json

---

設定管理についてさらに詳しく知りたい場合は、AI Setup Assistant をご利用ください。

関連ドキュメント

• SecretRef Credential Surface
• Gateway troubleshooting