設定と運用

設定

OpenClaw は、オプションの JSON5 設定を ~/.openclaw/openclaw.json から読み込みます。ファイルが存在しない場合、OpenClaw は安全なデフォルト値を使用します。設定を追加する一般的な理由は以下の通りです:

チャネルを接続し、誰がボットにメッセージを送信できるかを制御する
モデル、ツール、サンドボックス化、または自動化 (cron、フック) を設定する
セッション、メディア、ネットワーキング、または UI を調整する

利用可能なすべてのフィールドについては、完全なリファレンスを参照してください。

💡 設定が初めてですか？ インタラクティブなセットアップには openclaw onboard から始めるか、完全なコピー＆ペースト設定については設定例ガイドを確認してください。

最小限の設定

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

設定の編集

openclaw onboard       # 完全セットアップウィザード
openclaw configure     # 設定ウィザード

厳密な検証

⚠️ OpenClaw は、スキーマに完全に一致する設定のみを受け入れます。未知のキー、不正な形式の型、または無効な値があると、ゲートウェイは 起動を拒否します。唯一のルートレベルの例外は $schema (文字列) であり、エディタが JSON スキーマメタデータを添付できるようにします。

検証が失敗した場合:

ゲートウェイは起動しません
診断コマンドのみが機能します (openclaw doctor, openclaw logs, openclaw health, openclaw status)
正確な問題を確認するには openclaw doctor を実行します
修復を適用するには openclaw doctor --fix (または --yes) を実行します

一般的なタスク

チャネルを設定する (WhatsApp, Telegram, Discord など)

モデルを選択して設定する

ボットにメッセージを送信できるユーザーを制御する

グループチャットメンションゲーティングを設定する

セッションとリセットを設定する

サンドボックス化を有効にする

ハートビートを設定する (定期的なチェックイン)

cron ジョブを設定する

ウェブフックを設定する (フック)

マルチエージェントルーティングを設定する

設定を複数のファイルに分割する ($include)

設定ホットリロード

ゲートウェイは ~/.openclaw/openclaw.json を監視し、変更を自動的に適用します — ほとんどの設定で手動での再起動は不要です。

リロードモード

モード	動作
`hybrid` (デフォルト)	安全な変更を即座にホット適用します。重要な変更には自動的に再起動します。
`hot`	安全な変更のみをホット適用します。再起動が必要な場合は警告をログに記録します — ユーザーが対応します。
`restart`	設定変更のたびに、安全かどうかに関わらずゲートウェイを再起動します。
`off`	ファイル監視を無効にします。変更は次回の手動再起動で有効になります。

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

ホット適用されるもの vs 再起動が必要なもの

ほとんどのフィールドはダウンタイムなしでホット適用されます。hybrid モードでは、再起動が必要な変更は自動的に処理されます。

カテゴリ	フィールド	再起動が必要？
チャネル	`channels.*`, `web` (WhatsApp) — すべての組み込みおよび拡張チャネル	いいえ
エージェント & モデル	`agent`, `agents`, `models`, `routing`	いいえ
自動化	`hooks`, `cron`, `agent.heartbeat`	いいえ
セッション & メッセージ	`session`, `messages`	いいえ
ツール & メディア	`tools`, `browser`, `skills`, `audio`, `talk`	いいえ
UI & その他	`ui`, `logging`, `identity`, `bindings`	いいえ
ゲートウェイサーバー	`gateway.*` (ポート、バインド、認証、tailscale、TLS、HTTP)	はい
インフラストラクチャ	`discovery`, `canvasHost`, `plugins`	はい

ℹ️ gateway.reload と gateway.remote は例外です — これらを変更しても 再起動はトリガーされません。

設定 RPC (プログラムによる更新)

ℹ️ コントロールプレーンの書き込み RPC (config.apply, config.patch, update.run) は、deviceId+clientIp ごとに 60秒あたり3リクエスト にレート制限されます。制限されると、RPC は UNAVAILABLE と retryAfterMs を返します。

config.apply (完全置換)

config.patch (部分更新)

環境変数

OpenClaw は親プロセスから環境変数を読み取ります。さらに以下からも読み取ります:

現在の作業ディレクトリの .env (存在する場合)
~/.openclaw/.env (グローバルフォールバック)

どちらのファイルも既存の環境変数を上書きしません。設定内でインライン環境変数を設定することもできます:

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

シェル環境変数のインポート (オプション)

設定値内の環境変数置換

シークレット参照 (env, file, exec)

完全な優先順位とソースについては環境を参照してください。

完全なリファレンス

フィールドごとの完全なリファレンスについては、設定リファレンス を参照してください。

関連: 設定例 · 設定リファレンス · Doctor

ゲートウェイランブック設定リファレンス