~/.openclaw/openclaw.json からオプションの 設定を読み込みます。ファイルが存在しない場合、OpenClaw は安全なデフォルトを使用します。
有効な設定パスは通常のファイルでなければなりません。OpenClaw による書き込みでは、ファイルをアトミックに置き換える(パス上にリネームする)ため、シンボリックリンクされた openclaw.json ではリンク先への書き込みではなく、リンク先自体が置き換えられます。シンボリックリンクを使用した設定レイアウトは避けてください。設定をデフォルトの状態ディレクトリ外に置く場合は、OPENCLAW_CONFIG_PATH が実ファイルを直接指すようにしてください。
設定を追加する一般的な理由:
- チャンネルを接続し、ボットにメッセージを送信できるユーザーを制御する
- モデル、ツール、サンドボックス化、自動化(cron、フック)を設定する
- セッション、メディア、ネットワーク、UI を調整する
agents.defaults にはエージェントループの動作を配置します。スキーマがエージェントごとのオーバーライドをサポートしている場合、agents.entries 配下のエントリでどちらの領域もオーバーライドできます。
エージェントと自動化では、設定を編集する前に、フィールド単位の正確な
ドキュメントを config.schema.lookup で確認してください。このページはタスク指向のガイダンスに使用し、
より広範なフィールド一覧とデフォルトについては
設定リファレンスを参照してください。
最小構成
設定の編集
- 対話形式のウィザード
- CLI(ワンライナー)
- コントロール UI
- 直接編集
厳格な検証
openclaw config schema は、コントロール UI と検証で使用される正規の JSON Schema を出力します。
config.schema.lookup は、詳細表示ツール向けに、パスで範囲指定された単一ノードと
子要素の概要を取得します。フィールドの title/description ドキュメントメタデータは、
ネストされたオブジェクト、ワイルドカード(*)、配列項目([])、および anyOf/
oneOf/allOf の分岐にも引き継がれます。マニフェストレジストリが読み込まれると、
実行時の Plugin とチャンネルのスキーマが統合されます。
すべての設定リーフには、uiHints で一般または高度の表示階層が設定されています。
advanced: false は一般設定、advanced: true は高度な
設定を示します。リーフに直接のヒントがない場合は、最も近い祖先の階層を継承します。
宣言された祖先がないパスは、デフォルトで高度になります。これは表示にのみ影響し、
検証、デフォルト、リロード動作、キーを設定できるかどうかには影響しません。
検証に失敗した場合:
- Gateway は起動しません
- 診断コマンドのみ動作します(
openclaw doctor、openclaw logs、openclaw health、openclaw status) - 正確な問題を確認するには
openclaw doctorを実行します - 修復を適用するには
openclaw doctor --fixを実行します(--repairは同じフラグで、--yesはプロンプトを省略します)
openclaw doctor --fix
のみです。openclaw.json の検証(Plugin ローカルの検証を含む)が失敗した場合、Gateway の
起動は失敗するか、リロードがスキップされ、現在のランタイムは最後に受け入れられた
設定を使用し続けます。拒否された書き込みも、確認用に <path>.rejected.<timestamp> として保存されます。
Gateway は、誤って上書きしたように見える書き込みをブロックします。具体的には、gateway.mode の削除、
meta ブロックの喪失、またはファイルサイズが半分を超えて縮小する場合です。ただし、書き込みで
破壊的変更を明示的に許可している場合を除きます。候補に *** や [redacted] のような
秘匿化されたシークレットのプレースホルダーが含まれる場合、最後の正常なコピーへの昇格はスキップされます。
一般的なタスク
チャンネルをセットアップする(WhatsApp、Telegram、Discord など)
チャンネルをセットアップする(WhatsApp、Telegram、Discord など)
各チャンネルには、
channels.<provider> 配下に独自の設定セクションがあります。セットアップ手順については、各チャンネル専用ページを参照してください:- Discord -
channels.discord - Feishu -
channels.feishu - Google Chat -
channels.googlechat - iMessage -
channels.imessage - Mattermost -
channels.mattermost - Microsoft Teams -
channels.msteams - Signal -
channels.signal - Slack -
channels.slack - Telegram -
channels.telegram - WhatsApp -
channels.whatsapp
モデルを選択して設定する
モデルを選択して設定する
プライマリモデルとオプションのフォールバックを設定します:
agents.defaults.modelsはエイリアスとモデルごとの設定を保存します。エントリを追加しても、/modelまたは--modelのオーバーライドが制限されることはありません。agents.defaults.modelPolicy.allowは、オーバーライドとモデル選択用の明示的な許可リストです。完全一致する参照とprovider/*ワイルドカードを受け入れます。任意のモデルを許可するには、省略するか[]を使用します。- モデル参照には
provider/model形式を使用します(例:anthropic/claude-opus-4-6)。 agents.defaults.imageMaxDimensionPxは、トランスクリプト/ツール画像のダウンスケーリングを制御します(デフォルトは1200)。値を小さくすると通常、スクリーンショットが多い実行でビジョントークンの使用量が減少します。- チャット内でのモデル切り替えについてはモデル CLI、認証のローテーションとフォールバック動作についてはモデルのフェイルオーバーを参照してください。
- カスタム/セルフホストのプロバイダーについては、リファレンスのカスタムプロバイダーを参照してください。
ボットにメッセージを送信できるユーザーを制御する
ボットにメッセージを送信できるユーザーを制御する
DM アクセスは、チャンネルごとに
dmPolicy(デフォルトは "pairing")で制御します:"pairing":不明な送信者には、承認用の 1 回限りのペアリングコードが発行されます"allowlist":allowFrom(またはペアリング済み許可ストア)に含まれる送信者のみ"open":すべての受信 DM を許可します(allowFrom: ["*"]が必要)"disabled":すべての DM を無視します
groupPolicy("allowlist" | "open" | "disabled")と groupAllowFrom、またはチャンネル固有の許可リストを使用します。チャンネルごとの詳細については、完全なリファレンスを参照してください。グループチャットのメンションゲートを設定する
グループチャットのメンションゲートを設定する
グループメッセージでは、デフォルトでメンションが必須です。エージェントごとにトリガーパターンを設定します。通常のグループ/チャンネル返信は自動的に投稿されます。エージェントが発言するタイミングを判断する必要がある共有ルームでは、メッセージツール経由の処理を明示的に有効にします:
- メタデータのメンション:ネイティブの @メンション(WhatsApp のタップによるメンション、Telegram の @bot など)
- テキストパターン:
mentionPatterns内の安全な正規表現パターン - 表示される返信:
messages.visibleRepliesではメッセージツールによる送信を全体で必須にでき、messages.groupChat.visibleRepliesでグループ/チャンネル向けにオーバーライドできます。 - 表示される返信モード、チャンネルごとのオーバーライド、セルフチャットモードについては、完全なリファレンスを参照してください。
エージェントごとに Skills を制限する
エージェントごとに Skills を制限する
共有ベースラインには
agents.defaults.skills を使用し、特定の
エージェントを agents.entries.*.skills でオーバーライドします:- デフォルトで Skills を無制限にするには、
agents.defaults.skillsを省略します。 - デフォルトを継承するには、
agents.entries.*.skillsを省略します。 - Skills なしにするには、
agents.entries.*.skills: []を設定します。 - Skills、Skills の設定、および 設定リファレンスを参照してください。
チャンネルごとのヘルスモニタリングを設定する
チャンネルごとのヘルスモニタリングを設定する
セッションとリセットを設定する
セッションとリセットを設定する
セッションは会話の継続性と分離を制御します。
dmScope:main(共有)|per-peer|per-channel-peer|per-account-channel-peerthreadBindings: スレッドにバインドされたセッションルーティングのグローバルなデフォルト。/focus、/unfocus、/agents、/session idle、/session max-ageを使用して、セッションごとにバインド、バインド解除、一覧表示、調整を行います(Discord はスレッド、Telegram はトピック/会話をバインドします)。- スコープ、ID リンク、送信ポリシーについては、セッション管理を参照してください。
- すべてのフィールドについては、完全なリファレンスを参照してください。
サンドボックス化を有効にする
サンドボックス化を有効にする
エージェントセッションを分離されたサンドボックスランタイムで実行します。まずイメージをビルドします。ソースチェックアウトでは
scripts/sandbox-setup.sh を実行し、npm インストールではサンドボックス化 § イメージとセットアップに記載されたインラインの docker build コマンドを参照してください。詳細なガイドについてはサンドボックス化、すべてのオプションについては完全なリファレンスを参照してください。公式 iOS ビルドのリレー経由プッシュを有効にする
公式 iOS ビルドのリレー経由プッシュを有効にする
公開 App Store ビルドのリレー経由プッシュでは、ホストされた OpenClaw リレー CLI での同等の設定:この設定の動作:
https://ios-push-relay.openclaw.ai を使用します。カスタムリレーのデプロイには、リレー URL が Gateway のリレー URL と一致する、意図的に分離された iOS ビルド/デプロイパスが必要です。カスタムリレービルドを使用している場合は、Gateway 設定で次のように指定します。- Gateway が外部リレーを介して
push.test、ウェイク通知、再接続ウェイクを送信できるようにします。 - ペアリングされた iOS アプリから転送される、登録単位の送信許可を使用します。Gateway にデプロイ全体で共通のリレートークンは必要ありません。
- リレー経由の各登録を、iOS アプリがペアリングした Gateway の ID にバインドし、別の Gateway が保存済み登録を再利用できないようにします。
- ローカル/手動の iOS ビルドでは直接 APNs を使用し続けます。リレー経由の送信は、リレーを介して登録された公式配布ビルドにのみ適用されます。
- 登録トラフィックと送信トラフィックが同じリレーデプロイに到達するよう、iOS ビルドに組み込まれたリレーベース URL と一致させる必要があります。
- 公式 iOS アプリをインストールします。
- 任意: 意図的に分離されたカスタムリレービルドを使用する場合に限り、Gateway で
gateway.push.apns.relay.baseUrlを設定します。 - iOS アプリを Gateway とペアリングし、Node セッションとオペレーターセッションの両方を接続します。
- iOS アプリは Gateway の ID を取得し、App Attest とアプリのレシートを使用してリレーに登録した後、リレー経由の
push.apns.registerペイロードをペアリング済み Gateway に公開します。 - Gateway はリレーハンドルと送信許可を保存し、それらを
push.test、ウェイク通知、再接続ウェイクに使用します。
- iOS アプリを別の Gateway に切り替えた場合は、その Gateway にバインドされた新しいリレー登録を公開できるよう、アプリを再接続してください。
- 異なるリレーデプロイを参照する新しい iOS ビルドを配布した場合、アプリは古いリレーオリジンを再利用せず、キャッシュ済みのリレー登録を更新します。
OPENCLAW_APNS_RELAY_BASE_URLとOPENCLAW_APNS_RELAY_TIMEOUT_MSは、一時的な環境変数によるオーバーライドとして引き続き機能します。- カスタム Gateway のリレー URL は、iOS ビルドに組み込まれたリレーベース URL と一致する必要があります。公開 App Store リリースレーンでは、カスタム iOS リレー URL のオーバーライドが拒否されます。
OPENCLAW_APNS_RELAY_ALLOW_HTTP=trueは local loopback 専用の開発用エスケープハッチとして引き続き使用できます。HTTP リレー URL を設定に永続化しないでください。
Heartbeat(定期チェックイン)を設定する
Heartbeat(定期チェックイン)を設定する
every: 期間文字列(30m、2h)。無効にするには0mを設定します。デフォルト:30m。target:last|none|<channel-id>(例:discord、matrix、telegram、whatsapp)directPolicy: DM 形式の Heartbeat ターゲットではallow(デフォルト)またはblock- 詳細なガイドについては、Heartbeatを参照してください。
Cron ジョブを設定する
Cron ジョブを設定する
sessionRetention: 完了した分離実行セッションを SQLite のセッション行から削除します(デフォルトは24h。無効にするにはfalseを設定)。- 実行履歴では、ジョブごとに最新のターミナル行 2000 件が自動的に保持されます。失われた行には 24 時間のクリーンアップ期間が引き続き適用されます。
- 機能の概要と CLI の例については、Cron ジョブを参照してください。
Webhook(フック)を設定する
Webhook(フック)を設定する
Gateway で HTTP Webhook エンドポイントを有効にします。セキュリティ上の注意:
- すべてのフック/Webhook ペイロードの内容を信頼できない入力として扱ってください。
- 専用の
hooks.tokenを使用し、使用中の Gateway 認証シークレット(gateway.auth.token/OPENCLAW_GATEWAY_TOKENまたはgateway.auth.password/OPENCLAW_GATEWAY_PASSWORD)を再利用しないでください。 - フック認証はヘッダーのみ(
Authorization: Bearer ...またはx-openclaw-token)を使用します。クエリ文字列のトークンは拒否されます。 hooks.pathを/にすることはできません。Webhook の受信パスには/hooksなどの専用サブパスを使用してください。- 厳密に範囲を限定したデバッグを行う場合を除き、安全でないコンテンツのバイパスフラグ(
hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent)は無効のままにしてください。 hooks.allowRequestSessionKeyを有効にする場合は、呼び出し元が選択するセッションキーを制限するため、hooks.allowedSessionKeyPrefixesも設定してください。- フックによって駆動されるエージェントには、性能の高い最新モデルの階層と厳格なツールポリシー(可能であれば、メッセージングのみに制限し、サンドボックス化を併用するなど)を推奨します。
マルチエージェントルーティングを設定する
マルチエージェントルーティングを設定する
設定を複数ファイルに分割する($include)
設定を複数ファイルに分割する($include)
大規模な設定を整理するには、
$include を使用します。- 単一ファイル: それを含むオブジェクトを置き換えます
- ファイルの配列: 順番にディープマージされ(後の値が優先)、最大 10 階層までネストできます
- 兄弟キー: インクルード後にマージされます(インクルードされた値を上書きします)
- 相対パス: インクルード元ファイルを基準に解決されます
- パス形式: インクルードパスに null バイトを含めることはできず、解決前と解決後の両方で 4096 文字未満である必要があります
- OpenClaw による書き込み: 書き込みによって、
plugins: { $include: "./plugins.json5" }のような単一ファイルのインクルードに基づく最上位セクションが 1 つだけ変更される場合、 OpenClaw はそのインクルードファイルを更新し、openclaw.jsonはそのまま維持します - サポートされていないライトスルー: ルートインクルード、インクルード配列、兄弟キーによるオーバーライドを持つインクルードでは、 設定をフラット化せず、OpenClaw による書き込みをフェイルクローズします
- 制限:
$includeパスは、openclaw.jsonを格納するディレクトリ配下に解決される必要があります。複数のマシンまたはユーザー間でツリーを共有するには、OPENCLAW_INCLUDE_ROOTSに、インクルードから参照可能な追加ディレクトリのパスリスト(POSIX では:、Windows では;)を設定します。 シンボリックリンクは解決後に再チェックされるため、字句上は設定ディレクトリ内に存在していても、 実際のターゲットが許可されたすべてのルート外にあるパスは引き続き拒否されます。 - エラー処理: ファイルの欠落、解析エラー、循環インクルード、無効なパス形式、長さ超過に対して明確なエラーを表示します
設定のホットリロード
Gateway は~/.openclaw/openclaw.json を監視して変更を自動的に適用します。ほとんどの設定では手動で再起動する必要はありません。
ファイルへの直接編集は、検証されるまで信頼できないものとして扱われます。ウォッチャーは、
エディターによる一時書き込み/名前変更の連続処理が落ち着くのを待ってから最終ファイルを読み取り、
無効な外部編集を拒否しますが、openclaw.json は書き換えません。OpenClaw による設定の
書き込みも、書き込み前に同じスキーマゲートを使用します(すべての書き込みに適用される上書き/ロールバックのルールについては、
厳格な検証を参照してください)。
config reload skipped (invalid config) が表示される場合、または起動時に Invalid config が報告される場合は、設定を確認し、openclaw config validate を実行してから、修復のために openclaw doctor --fix を実行してください。チェックリストについては、Gateway のトラブルシューティング
を参照してください。
リロードモード
ホット適用される変更と再起動が必要な変更
ほとんどのフィールドはダウンタイムなしでホット適用されます。一部のホット適用対象セクションでは、Gateway 全体ではなく、そのサブシステム(チャンネル、Cron、Heartbeat、ヘルスモニター)のみが再起動されます。hybrid モードでは、Gateway の再起動が必要な変更は自動的に処理されます。
gateway.reload と gateway.remote は gateway.* における例外であり、これらを変更しても再起動はトリガーされません。個々の Plugin がこの表を上書きすることもできます。読み込まれた Plugin は、再起動をトリガーする独自の設定プレフィックスを宣言できます(たとえば、組み込みの Canvas Plugin は、自身の plugins.entries.canvas だけでなく、plugins.enabled、plugins.allow、plugins.deny の変更でも Gateway を再起動します)。そのため、実際の動作は有効な Plugin によって異なります。再読み込みの計画
$include を介して参照されているソースファイルを編集すると、OpenClaw はフラット化されたメモリ内ビューではなく、ソースに記述されたレイアウトに基づいて再読み込みを計画します。
これにより、単一のトップレベルセクションが plugins: { $include: "./plugins.json5" } のような独立したインクルードファイルにある場合でも、ホット再読み込みの判断(ホット適用か再起動か)が予測可能になります。ソースレイアウトが曖昧な場合、再読み込みの計画は安全側に倒して失敗します。
設定 RPC(プログラムによる更新)
Gateway API 経由で設定を書き込むツールでは、次のフローを推奨します。config.schema.lookupで単一のサブツリーを調査する(浅いスキーマノードと子の概要)config.getで現在のスナップショットとhashを取得するconfig.patchで部分更新を行う(JSON マージパッチ:オブジェクトはマージ、nullは削除。エントリが削除される場合はreplacePathsで明示的に確認したときのみ配列を置換)- 設定全体を置き換える場合にのみ
config.applyを使用する - 明示的な自己更新と再起動には
update.runを使用する。再起動後のセッションで追加のターンを 1 回実行する場合はcontinuationMessageを含める - 最新の更新再起動センチネルを調査し、再起動後に実行中のバージョンを確認するには
update.statusを使用する
config.schema.lookup を参照する必要があります。より広範な設定マップ、デフォルト、または各サブシステムのリファレンスへのリンクが必要な場合は、設定リファレンスを使用してください。
コントロールプレーンへの書き込み(
config.apply、config.patch、update.run)は、deviceId+clientIp ごと、メソッドごとに、60 秒あたり 30 リクエストに制限されます。レート制限を参照してください。再起動リクエストは統合された後、再起動サイクル間に 30 秒のクールダウンが適用されます。
update.status は読み取り専用ですが、再起動センチネルに更新手順の概要やコマンド出力の末尾が含まれる可能性があるため、管理者スコープです。config.apply と config.patch はどちらも、raw、baseHash、sessionKey、note、restartDelayMs を受け付けます。設定ファイルがすでに存在する場合、どちらのメソッドでも baseHash が必須です(既存の設定がない状態での初回書き込みでは、このチェックは省略されます)。
config.patch は、配列の置換が意図的である設定パスの配列である replacePaths も受け付けます。パッチによって既存の配列がより少ないエントリの配列に置換または削除される場合、その正確なパスが replacePaths に含まれていない限り、Gateway は書き込みを拒否します。配列エントリ内のネストされた配列では、agents.entries.*.skills のように [] を使用します。これにより、切り詰められた config.get スナップショットが、ルーティング配列や許可リスト配列を意図せず上書きするのを防ぎます。設定全体を置き換える場合は config.apply を使用してください。
環境変数
OpenClaw は親プロセスに加えて、次の場所から環境変数を読み取ります。- 現在の作業ディレクトリにある
.env(存在する場合) ~/.openclaw/.env(グローバルフォールバック)
シェル環境変数のインポート(任意)
シェル環境変数のインポート(任意)
有効にした場合、必要なキーが設定されていなければ、OpenClaw はログインシェルを実行し、不足しているキーのみをインポートします。対応する環境変数:
OPENCLAW_LOAD_SHELL_ENV=1。デフォルトの timeoutMs:15000。設定値での環境変数の置換
設定値での環境変数の置換
任意の設定文字列値で ルール:
${VAR_NAME} を使用して環境変数を参照します。- 一致するのは大文字の名前のみ:
[A-Z_][A-Z0-9_]* - 変数が未設定または空の場合、読み込み時にエラーが発生する
- リテラルとして出力するには
$${VAR}でエスケープする $includeファイル内でも機能する- インライン置換:
"${BASE}/v1"→"https://api.example.com/v1"
シークレット参照(環境変数、ファイル、実行)
シークレット参照(環境変数、ファイル、実行)
SecretRef オブジェクトをサポートするフィールドでは、次のように使用できます。SecretRef の詳細(
env/file/exec の secrets.providers を含む)は、シークレット管理に記載されています。
サポートされる認証情報パスは、SecretRef 認証情報サーフェスに一覧表示されています。完全なリファレンス
フィールドごとの完全なリファレンスについては、**設定リファレンス**を参照してください。関連項目:設定例 · 設定リファレンス · Doctor