Configuration

OpenClaw は ~/.openclaw/openclaw.json から任意の JSON5 設定を読み込みます（コメントと末尾カンマ可）。

ファイルが無い場合は安全なデフォルトで動作します。実運用では多くの場合、次だけ設定すれば十分です：

• 誰が bot を起動できるか（例：channels.whatsapp.allowFrom、channels.telegram.allowFrom）。
• グループの allowlist と mention 挙動（例：channels.whatsapp.groups、channels.telegram.groups、channels.discord.guilds、agents.list[].groupChat）。
• メッセージプレフィックスのカスタマイズ（messages）。
• エージェント workspace の設定（agents.defaults.workspace / agents.list[].workspace）。

設定ファイルは ~/.openclaw/openclaw.json で、JSON5 です（厳密 JSON ではありません）。

小さな変更は、全置換よりも増分更新（例：config.patch）を推奨します。

OpenClaw は schema と一致する設定のみ受け付けます。無効な設定は拒否され、Gateway は起動を拒否します。

検証に失敗した場合：

• Gateway が起動しません。
• 診断コマンドのみ利用できます（例：openclaw doctor、openclaw logs、openclaw health、openclaw status）。
• openclaw doctor で原因を確認します。
• openclaw doctor --fix（または --yes）で移行/修正を適用します。

Doctor は --fix/--yes を明示しない限り書き込みません。

Gateway は UI エディタ向けに config.schema として JSON Schema を提供します。

Control UI は schema からフォームを描画し、Raw JSON エディタも用意します。

プラグインは schema + UI hints（ラベル、グループ化、機密フィールド）を登録でき、クライアントはハードコード無しで描画できます。

config.apply で設定全体を検証・書き込みし、1 ステップで Gateway を再起動します。

Warning: config.apply replaces the entire config. If you want to change only a few keys, use config.patch or openclaw config set. Keep a backup of ~/.openclaw/openclaw.json.

パラメータ：

• raw（string）：設定全体の JSON5
• baseHash（任意）：config.get の hash（既存設定がある場合に必要）
• sessionKey（任意）：再起動後に ping する最後のセッション key
• note（任意）：再起動センチネルに含めるメモ
• restartDelayMs（任意）：再起動前の遅延（デフォルト 2000）

Example (via gateway call):

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\n  agents: { defaults: { workspace: \"~/.openclaw/workspace\" } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

config.patch で既存設定に部分更新をマージします。

マージパッチの挙動：

• オブジェクトは再帰的にマージします。
• null はキー削除です。
• 配列は置換です。

Params:

• raw（string）：変更したいキーのみ含む JSON5
• baseHash（必須）：config.get の hash
• sessionKey（任意）：再起動後に ping する最後のセッション key
• note（任意）：再起動センチネルに含めるメモ
• restartDelayMs（任意）：再起動前の遅延（デフォルト 2000）

Example:

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\n  channels: { telegram: { groups: { \"*\": { requireMention: false } } } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

workspace を設定し、WhatsApp の DM を allowlist に制限する最小設定：

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

$include で設定を複数ファイルに分割できます。

• 大きな設定を整理（例：クライアントごとのエージェント定義）。
• 環境間で共通設定を共有。
• 機密設定を分離。

Example:

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: { $include: ["./clients/mueller.json5", "./clients/schmidt.json5"] },
}

OpenClaw は親プロセス（shell、launchd/systemd、CI など）から環境変数を読み、.env をフォールバックとして読み込みます。

• カレントディレクトリの .env を読み込み（存在する場合）。
• ~/.openclaw/.env（$OPENCLAW_STATE_DIR/.env）をグローバルフォールバックとして読み込み。
• .env は既存の環境変数を上書きしません。

設定ファイル内に inline env を書くこともできます（不足しているキーのみ埋めます）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

優先順位とソースは /environment を参照してください。

ReferenceGatewayConfigurationPage.steps.envSubstitution.p1

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

ルール：

• 大文字の env 名のみ：[A-Z_][A-Z0-9_]*
• 欠落/空の env は読み込みエラーになります。
• ReferenceGatewayConfigurationPage.steps.envSubstitution.rules.escape
• $include と併用可能（include されたファイルも置換されます）。

OpenClaw は認証プロファイルをエージェント単位でディスクに保存します。

• 主ファイル：<agentDir>/auth-profiles.json
• 旧インポート：$OPENCLAW_STATE_DIR/credentials/oauth.json
• エージェント root は OPENCLAW_AGENT_DIR（推奨）/ PI_CODING_AGENT_DIR（旧）で上書きできます。

OAuth の全体フローと保存レイアウトは /concepts/oauth を参照。

• 大きな変更前に ~/.openclaw/openclaw.json をバックアップ。
• ログ脱敏で秘密の露出を防ぐ（logging.redactSensitive）。
• 複数エージェントではエージェント単位の sandbox/tools policy を使う。多エージェント sandbox とツール を参照。