設定

OpenClaw は、~/.openclaw/openclaw.json から任意の設定を読み込みます。ファイルが存在しない場合、OpenClaw は安全なデフォルトを使用します。設定を追加する一般的な理由：

チャンネルを接続し、誰がボットにメッセージできるかを制御する
モデル、ツール、サンドボックス、自動化（cron、hooks）を設定する
セッション、メディア、ネットワーク、UI を調整する

利用可能なすべてのフィールドについては、full reference を参照してください。

設定が初めてですか？ openclaw onboard で対話型セットアップを開始するか、完全なコピーペースト用設定が載っている Configuration Examples ガイドをご覧ください。

Minimal config

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

Editing config

対話型ウィザード
CLI（ワンライナー）
Control UI
直接編集

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

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

~/.openclaw/openclaw.json を直接編集します。Gateway はファイルを監視し、変更を自動適用します（hot reload を参照）。

Strict validation

OpenClaw はスキーマに完全一致する設定のみを受け付けます。未知のキー、不正な型、無効な値がある場合、Gateway は 起動を拒否 します。ルートレベルでの唯一の例外は $schema（string）で、エディタが JSON Schema メタデータを付与するために使用できます。

検証に失敗した場合：

Gateway は起動しません
診断コマンドのみ使用可能です（openclaw doctor、openclaw logs、openclaw health、openclaw status）
openclaw doctor を実行して正確な問題を確認してください
openclaw doctor --fix（または --yes）で修復を適用します

Common tasks

チャンネルを設定する（WhatsApp、Telegram、Discord など）

各チャンネルには channels.<provider> 配下に専用の設定セクションがあります。セットアップ手順は各チャンネルページを参照してください：

WhatsApp — channels.whatsapp
Telegram — channels.telegram
Discord — channels.discord
Slack — channels.slack
Signal — channels.signal
iMessage — channels.imessage
Google Chat — channels.googlechat
Mattermost — channels.mattermost
MS Teams — channels.msteams

すべてのチャンネルは同じ DM ポリシーパターンを共有します：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}

モデルを選択・設定する

プライマリモデルとオプションのフォールバックを設定します：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

agents.defaults.models はモデルカタログを定義し、/model の許可リストとして機能します。
モデル参照は provider/model 形式です（例：anthropic/claude-opus-4-6）。
チャット中のモデル切替は Models CLI、認証ローテーションやフォールバック動作は Model Failover を参照してください。
カスタム／セルフホスト型プロバイダーは、リファレンスの Custom providers を参照してください。

誰がボットにメッセージできるかを制御する

DM アクセスはチャンネルごとに dmPolicy で制御します：

"pairing"（デフォルト）：未知の送信者は承認用のワンタイムペアリングコードを受け取ります
"allowlist"：allowFrom（またはペア済みストア）の送信者のみ許可
"open"：すべての受信 DM を許可（allowFrom: ["*"] が必要）
"disabled"：すべての DM を無視

グループの場合は groupPolicy + groupAllowFrom、またはチャンネル固有の許可リストを使用します。詳細は full reference を参照してください。

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

グループメッセージはデフォルトで メンション必須 です。エージェントごとにパターンを設定できます：

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

メタデータメンション：ネイティブ @メンション（WhatsApp のタップメンション、Telegram の @bot など）
テキストパターン：mentionPatterns の正規表現パターン
チャンネル別の上書きやセルフチャットモードは full reference を参照してください。

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

セッションは会話の継続性と分離を制御します：

{
  session: {
    dmScope: "per-channel-peer",  // マルチユーザーに推奨
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

dmScope: main（共有）| per-peer | per-channel-peer | per-account-channel-peer
スコープ、IDリンク、送信ポリシーは Session Management を参照してください。
全フィールドは full reference を参照してください。

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

エージェントセッションを分離された Docker コンテナで実行します：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

まずイメージをビルドします：scripts/sandbox-setup.sh詳細は Sandboxing、全オプションは full reference を参照してください。

Heartbeat（定期チェックイン）を設定する

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

every: 期間文字列（30m, 2h）。0m で無効化。
target: last | whatsapp | telegram | discord | none
詳細は Heartbeat を参照してください。

cron ジョブを設定する

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

概要と CLI 例は Cron jobs を参照してください。

webhooks（hooks）を設定する

Gateway 上で HTTP webhook エンドポイントを有効にします：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

すべてのマッピングオプションと Gmail 連携は full reference を参照してください。

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

個別のワークスペースとセッションを持つ複数の分離エージェントを実行します：

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

バインディングルールやエージェント別アクセスプロファイルは Multi-Agent および full reference を参照してください。

設定を複数ファイルに分割する（$include）

大規模な設定を整理するために $include を使用します：

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

単一ファイル：包含オブジェクトを置換
配列ファイル：順にディープマージ（後勝ち）
兄弟キー：include 後にマージ（include を上書き）
ネスト include：最大 10 階層まで対応
相対パス：包含元ファイル基準で解決
エラー処理：未存在ファイル、パースエラー、循環 include を明確に報告

Config hot reload

Gateway は ~/.openclaw/openclaw.json を監視し、変更を自動適用します — 多くの設定では手動再起動は不要です。

Reload modes

Mode	Behavior
`hybrid` (default)	安全な変更は即時ホット適用。重要な変更は自動再起動。
`hot`	安全な変更のみホット適用。再起動が必要な場合は警告ログのみ。
`restart`	すべての設定変更で Gateway を再起動。
`off`	ファイル監視を無効化。変更は次回手動再起動時に反映。

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

What hot-applies vs what needs a restart

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

Category	Fields	Restart needed?
Channels	`channels.*`, `web` (WhatsApp) — すべての組み込み／拡張チャンネル	No
Agent & models	`agent`, `agents`, `models`, `routing`	No
Automation	`hooks`, `cron`, `agent.heartbeat`	No
Sessions & messages	`session`, `messages`	No
Tools & media	`tools`, `browser`, `skills`, `audio`, `talk`	No
UI & misc	`ui`, `logging`, `identity`, `bindings`	No
Gateway server	`gateway.*` (port, bind, auth, tailscale, TLS, HTTP)	Yes
Infrastructure	`discovery`, `canvasHost`, `plugins`	Yes

gateway.reload と gateway.remote の変更は 再起動をトリガーしません。

Config RPC (programmatic updates)

config.apply (full replace)

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

config.apply は 設定全体を置き換えます。部分更新には config.patch、単一キー変更には openclaw config set を使用してください。

Params:

raw (string) — 設定全体の JSON5 ペイロード
baseHash (optional) — config.get からの設定ハッシュ（既存設定がある場合は必須）
sessionKey (optional) — 再起動後のウェイクアップ ping 用セッションキー
note (optional) — 再起動センチネル用メモ
restartDelayMs (optional) — 再起動までの遅延（デフォルト 2000）

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

config.patch (partial update)

既存設定に部分更新をマージします（JSON マージパッチセマンティクス）：

オブジェクトは再帰的にマージ
null はキー削除
配列は置換

Params:

raw (string) — 変更対象キーのみ含む JSON5
baseHash (required) — config.get からの設定ハッシュ
sessionKey, note, restartDelayMs — config.apply と同様

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

Environment variables

OpenClaw は親プロセスの環境変数に加えて、以下を読み込みます：

カレントディレクトリの .env（存在する場合）
~/.openclaw/.env（グローバルフォールバック）

どちらも既存の環境変数を上書きしません。設定内でインライン指定も可能です：

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

Shell env import (optional)

有効時、期待キーが未設定ならログインシェルを実行し、不足キーのみをインポートします：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Env var equivalent: OPENCLAW_LOAD_SHELL_ENV=1

Env var substitution in config values

任意の設定文字列内で ${VAR_NAME} を使用できます：

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

Rules:

大文字名のみ一致：[A-Z_][A-Z0-9_]*
未設定／空はロード時エラー
$${VAR} でエスケープ
$include 内でも機能
インライン例："${BASE}/v1" → "https://api.example.com/v1"

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

Full reference

完全なフィールド別リファレンスは Configuration Reference を参照してください。

Related: Configuration Examples · Configuration Reference · Doctor

ゲートウェイ

リモートアクセス

Webインターフェース

設定

設定

Minimal config

Editing config

Strict validation

Common tasks

Config hot reload

Reload modes

What hot-applies vs what needs a restart

Config RPC (programmatic updates)

Environment variables

Full reference

​設定

​Minimal config

​Editing config

​Strict validation

​Common tasks

​Config hot reload

​Reload modes

​What hot-applies vs what needs a restart

​Config RPC (programmatic updates)

​Environment variables

​Full reference

設定

Minimal config

Editing config

Strict validation

Common tasks

Config hot reload

Reload modes

What hot-applies vs what needs a restart

Config RPC (programmatic updates)

Environment variables

Full reference