OpenClaw の設定ガイド

新しいツールを導入した際、設定ファイルの書き方で迷うことはよくあります。どの項目が必須で、どのように記述すれば正しく動作するのか、ドキュメントを行き来するのは時間がかかる作業です。

OpenClaw では、~/.openclaw/openclaw.json というファイルを使って設定を管理します。このファイルは JSON5 形式に対応しているため、コメントを残したり、末尾にカンマを入れたりすることが可能です。設定ファイルがない場合はデフォルト値が適用されますが、特定の用途に合わせてカスタマイズしたい場合に作成します。

必要なもの

OpenClaw がインストールされている環境
~/.openclaw/ ディレクトリへのアクセス権限

クイックスタート

まずは 5 分で完了する最小限の構成から始めましょう。最も簡単な方法は、対話型のウィザードを使用することです。

1. インタラクティブな設定

ターミナルで以下のコマンドを実行すると、ウィザード形式で設定を進められます。

openclaw onboard       # 初回セットアップウィザード
openclaw configure     # 設定専用ウィザード

2. 最小限の設定例

手動で設定ファイルを作成する場合は、以下のような内容になります。

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

3. CLI を使った操作

CLI から直接値を設定したり確認したりすることもできます。

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

4. Control UI での編集

ブラウザで http://127.0.0.1:18789 を開き、Config タブを使用してください。フォーム形式で編集できるほか、Raw JSON エディタも利用可能です。

トラブルシューティング

OpenClaw は厳格なバリデーションを採用しています。スキーマに合わないキーや不正な値が含まれていると、Gateway は起動しません。問題が発生した場合は、以下の手順を確認してください。

Gateway が起動しない場合: 設定ファイルに未知のキーや型エラーがないか確認してください。
診断コマンドの実行: 起動に失敗しても openclaw doctor や openclaw logs などの診断コマンドは動作します。
ステータスの確認: openclaw health や openclaw status で現在の状態を確認できます。
自動修復の試行: openclaw doctor --fix（または --yes）を実行すると、修復を試みることができます。

設定の詳細は AI Setup Assistant でも確認できます。

次のステップ

full reference: すべての設定フィールドを確認する
Configuration Examples: コピー＆ペーストで使える設定例を見る

新しいツールを導入したとき、設定ファイルの書き方で迷うことはありませんか？特に複数のメッセージングプラットフォームを統合しようとすると、各サービスごとの仕様の違いに頭を抱えることがよくあります。

このガイドでは、日常的な開発で必要になる主要な設定項目を整理しました。これらを活用することで、開発の効率を上げることができます。

必要なもの

接続したい各チャネル（WhatsApp, Telegram, Discord など）のアカウント
モデルプロバイダー（Anthropic, OpenAI など）の API キー
基本的な JSON5 形式の知識

クイックスタート

まずは最小限の設定から始めましょう。5分で Telegram ボットを有効にする例です。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // allowlist または open の場合のみ
    },
  },
}

チャネルのセットアップ

各チャネルには、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 ポリシーパターンを使用します。

モデルの選択と構成

メインで使用するモデルと、オプションのフォールバックを設定します。

{
  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）。
カスタムまたはセルフホストのプロバイダーを使用する場合は、Custom providers を参照してください。

ボットへのメッセージ送信を制限する

DM のアクセス権限は、各チャネルの dmPolicy で制御します。

"pairing" (デフォルト): 未知の送信者には、承認のためのワンタイムペアリングコードが送信されます。
"allowlist": allowFrom（またはペアリング済みの保存済みリスト）にある送信者のみ許可します。
"open": すべてのインバウンド DM を許可します（allowFrom: ["*"] が必要です）。
"disabled": すべての DM を無視します。

グループチャットの場合は、groupPolicy と groupAllowFrom、またはチャネル固有の許可リストを使用してください。

グループチャットのメンション制御

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

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

Metadata mentions: 各プラットフォーム固有のメンション（WhatsApp のタップメンション、Telegram の @bot など）
Text patterns: mentionPatterns に記述された正規表現パターン

セッションとリセットの設定

セッションは、会話の継続性と分離を管理します。

{
  session: {
    dmScope: "per-channel-peer",  // 複数ユーザーでの利用に推奨
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

dmScope: main (共有) | per-peer | per-channel-peer | per-account-channel-peer から選択します。

Sandboxing の有効化

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

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

利用前に、イメージのビルドが必要です： scripts/sandbox-setup.sh

ハートビート（定期チェックイン）

ボットの生存確認や定期的なアクションを設定します。

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

every: 30m や 2h のような形式で指定します。0m で無効化されます。
target: last | whatsapp | telegram | discord | none

Cron ジョブの設定

定期的なタスクの実行を管理します。

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

Webhooks (hooks) の設定

Gateway で HTTP Webhook エンドポイントを有効にします。

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

マルチエージェントのルーティング

ワークスペースとセッションを分離した複数のエージェントを実行します。

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

設定ファイルの分割 ($include)

設定が大きくなった場合は、$include を使って整理しましょう。

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

単一ファイル: 含まれるオブジェクトをそのまま置き換えます。
ファイル配列: 順番にディープマージされます（後のファイルが優先）。
兄弟キー: include の後にマージされ、値を上書きします。
ネスト: 最大 10 レベルまでサポートされます。
相対パス: include 元のファイルからの相対パスとして解決されます。

トラブルシューティング

設定ファイルが見つからない: $include で指定したパスが、実行環境からの相対パスではなく、そのファイルを記述しているファイルからの相対パスになっているか確認してください。
パースエラー: JSON5 形式が正しいか、カンマの有無や括弧の閉じ忘れがないかチェックしましょう。
循環参照: $include で自分自身や親ファイルを読み込んでいないか確認してください。エラーとして検出されます。

設定についてさらに詳しく知りたい場合は、AI Setup Assistant に質問してください。

次のステップ

Models CLI — チャット内でのモデル切り替え
Model Failover — 認証のローテーションとフォールバックの挙動
Session Management — スコープ、アイデンティティリンク、送信ポリシー
Sandboxing — サンドボックス化の完全ガイド
Heartbeat — ハートビート機能の詳細
Cron jobs — 機能の概要と CLI の例
Multi-Agent — バインディングルールとアクセスプロファイル

設定ファイルを書き換えるたびに、手動でサーバーを停止して再起動するのは面倒な作業ですよね。開発のプロセスが途切れてしまいますし、変更が正しく適用されたか確認するまでの待ち時間は、積み重なると大きなロスになります。

OpenClaw の Gateway は、こうした手間を省くための仕組みを備えています。

必要なもの

~/.openclaw/openclaw.json ファイル
実行中の OpenClaw Gateway 環境

クイックスタート

Gateway は ~/.openclaw/openclaw.json を常に監視しており、ほとんどの設定変更を自動的に適用します。手動で再起動する必要はありません。

まずは、自分のスタイルに合った mode を選んでみてください。おすすめは、賢く再起動を判断してくれる hybrid モードです。

Mode	挙動
`hybrid` (default)	安全な変更は即座に反映します。重要な変更が必要な場合のみ、自動的に再起動を実行します。
`hot`	安全な変更のみを反映します。再起動が必要な変更があった場合はログに警告を表示し、判断をあなたに委ねます。
`restart`	設定が変更されたら、内容の安全性に関わらず Gateway を再起動します。
`off`	ファイルの監視を無効化します。次に手動で再起動するまで、変更は反映されません。

設定は以下のように記述します。

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

Hot-applies vs Restart

ほとんどのフィールドは、ダウンタイムなしで反映されます。hybrid モードを使用していれば、再起動が必要なケースも Gateway が自動で処理してくれます。

カテゴリ	フィールド	再起動が必要？
Channels	`channels.*`, `web` (WhatsApp) — すべての内蔵および拡張 Channel	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

[!NOTE] gateway.reload と gateway.remote は例外です。これらを変更しても、再起動はトリガーされません。

トラブルシューティング

設定を変更したのに反映されない: mode が off に設定されていないか確認してください。
再起動が必要という警告が出る: hot モードを使用している場合、gateway.* などの項目を変更すると警告ログが表示されます。この場合は、手動で Gateway を再起動してください。

セットアップで困ったことがあれば、AI Setup Assistant も活用してみてください。

次のステップ

gateway.remote の設定
カスタム Channel の追加方法

システムを自動化していると、設定ファイルをいちいち手動で編集するのが手間に感じることがあります。特に複数の環境を運用している場合、プログラムから直接設定を流し込める仕組みがあると、オペレーションのミスも減らせますし、何より管理が楽になります。

OpenClaw では RPC を通じて設定を更新できるので、その具体的な方法を見ていきましょう。

必要なもの

openclaw CLI
稼働中の Gateway インスタンス

クイックスタート

設定の更新には、用途に合わせて config.apply と config.patch の 2 つの方法が選べます。

1. 現在のハッシュを取得する

どちらのコマンドを実行する場合も、現在の設定状態を特定するための baseHash が必要です。まずは以下のコマンドでハッシュを確認してください。

openclaw gateway call config.get --params '{}'  # 出力される payload.hash を使用します

2. config.apply で全体を書き換える

設定全体を一度に置き換え、Gateway を再起動したい場合に適しています。

[!WARNING] config.apply は 設定全体を上書き します。特定のキーだけを変更したい場合は、この後紹介する config.patch か、CLI の openclaw config set を使ってください。

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

使用できるパラメータ:

raw (string): JSON5 形式の設定全体
baseHash (optional): config.get で取得したハッシュ（設定が存在する場合は必須）
sessionKey (optional): 再起動後のウェイクアップ通知用セッションキー
note (optional): 再起動時のセンチネル用メモ
restartDelayMs (optional): 再起動までの遅延時間（デフォルト 2000ms）

3. config.patch で部分的に更新する

既存の設定に、変更したい部分だけをマージします。JSON merge patch のルールに従って動作します。

オブジェクト：再帰的にマージされます
null：指定したキーが削除されます
配列：新しい配列に置き換わります

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

トラブルシューティング

設定の一部が消えてしまった: config.apply を使用していませんか？これはフルリプレイス用なので、送らなかった項目は削除されます。部分的な変更には config.patch が安全です。
更新が反映されない: baseHash が最新のものか確認してください。設定が存在する場合、config.get で取得した正しいハッシュを渡さないとエラーになります。

設定の自動化についてさらに詳しく知りたい場合は、AI Setup Assistant も活用してください。

次のステップ

---
title: "OpenClaw で環境変数を賢く管理する方法"
description: "OpenClaw における環境変数の読み込み優先順位、設定ファイル内での変数置換、シェル環境のインポートについて解説します。"
---

API キーを設定ファイルに直接書き込んでしまい、コード共有時に慌てて消したことはありませんか？開発環境と本番環境で設定を切り替える際、環境変数を正しく扱うことは非常に重要です。OpenClaw では、セキュリティを保ちながら柔軟に設定を管理するための仕組みが備わっています。

### What You'll Need
- OpenClaw の基本設定に関する知識
- JSON5 形式の設定ファイル
- 参照元となる環境変数（API キーなど）

### Quick Start
OpenClaw は、親プロセスからの環境変数に加えて、以下の場所から変数を読み込みます。

- カレントディレクトリにある `.env` ファイル
- `~/.openclaw/.env` （グローバルなフォールバック）

これらのファイルが既存の環境変数を上書きすることはありません。また、以下のように設定ファイル内で直接環境変数を定義することも可能です。

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

シェル環境のインポート

期待されるキーが設定されていない場合に、ログインシェルを実行して不足しているキーのみを取り込む機能があります。

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

環境変数 OPENCLAW_LOAD_SHELL_ENV=1 を使用して有効化することもできます。

設定値での環境変数置換

設定ファイル内の任意の文字列で ${VAR_NAME} 形式を使用すると、環境変数の値を参照できます。

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

利用にあたってはいくつかのルールがあります。

大文字の変数名（[A-Z_][A-Z0-9_]*）のみがマッチします。
変数が不足していたり空だったりする場合、ロード時にエラーが発生します。
文字列として ${VAR} と出力したい場合は、$${VAR} のようにエスケープしてください。
$include で読み込まれるファイル内でも動作します。
"https://api.example.com/v1" のように、文字列の一部として埋め込むこともできます。

Troubleshooting

ロード時のエラー: 設定ファイルで ${VAR_NAME} を参照しているにもかかわらず、その環境変数が定義されていないか空の場合、OpenClaw は起動時にエラーを投げます。変数が正しくセットされているか確認してください。
変数が置換されない: 変数名に小文字が含まれていないか確認してください。大文字、数字、アンダースコアのみが認識対象です。

詳細な優先順位やソースについては、Environment を参照してください。また、すべてのフィールドを確認したい場合は、Configuration Reference が役立ちます。

設定に関する具体的なアドバイスが必要な場合は、AI Setup Assistant を活用してください。

What’s Next

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。