Hello Claw: OpenClaw 入門ガイド

#付録 B: 設定ファイルの詳細な説明

OpenClaw の構成システムは柔軟かつ強力です。この付録では、公式ドキュメントに基づいて各構成項目を詳細に分析します。

参照元：OpenClaw Configuration

設定ファイルの場所

OpenClaw は、オプションの JSON5 構成ファイルを読み取ります。

~/.openclaw/openclaw.json          # 主配置文件
~/.openclaw/.env                   # 环境变量文件

構成ファイルが存在しない場合、OpenClaw は安全なデフォルトを使用します。

設定ファイル構造の概要

json5

{
  agents: { ... },           // Agent 配置
  channels: { ... },         // 渠道配置
  gateway: { ... },          // 网关配置
  session: { ... },          // 会话配置
  messages: { ... },         // 消息配置
  tools: { ... },            // 工具配置
  skills: { ... },           // 技能配置
  cron: { ... },             // 定时任务配置
  hooks: { ... },            // Webhook 配置
  bindings: [...],           // 绑定规则
  env: { ... },              // 环境变量
}

1. エージェントの設定 (エージェント)

1.1 デフォルト設定 (agents.defaults)

json5

{
  agents: {
    defaults: {
      // 工作空间路径
      workspace: "~/.openclaw/workspace",
      
      // 模型配置
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      },
      
      // 模型目录（用于 /model 命令）
      models: {
        "anthropic/claude-sonnet-4-5": {
          alias: "Sonnet"
        },
        "openai/gpt-5.2": {
          alias: "GPT"
        }
      },
      
      // 图片最大尺寸（像素）
      imageMaxDimensionPx: 1200,
      
      // 心跳配置
      heartbeat: {
        every: "30m",        // 30分钟、2小时等
        target: "last",      // last | whatsapp | telegram | discord | none
        directPolicy: "allow" // allow | block
      },
      
      // 沙盒配置
      sandbox: {
        mode: "non-main",    // off | non-main | all
        scope: "agent"       // session | agent | shared
      },
      
      // 工具配置
      tools: {
        enabled: true,
        profile: "full"
      }
    }
  }
}

設定項目の説明:

設定項目	タイプ	デフォルト値	説明
`workspace`	文字列	~/.openclaw/ワークスペース	エージェントの作業ディレクトリ
`model.primary`	文字列	-	メインモデル、形式: プロバイダー/モデル
`model.fallbacks`	配列	[]	フォールバックモデルリスト
`imageMaxDimensionPx`	番号	1200	画像転写/ツール画像ズームサイズ
`heartbeat.every`	文字列	-	ハートビート間隔 (30 分、2 時間など)
`sandbox.mode`	文字列	オフ	サンドボックスモード

1.2 マルチエージェント構成 (agents.list)

json5

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  }
}

2. チャネル構成(チャネル)

2.1 一般的な DM ポリシーの設定

すべてのチャネルは同じ DM 戦略パターンを共有します。

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",      // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],    // 仅用于 allowlist/open
    },
    
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],
      groups: {
        "*": {
          requireMention: true
        }
      }
    },
    
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["discord:123"]
    },
    
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

DM ポリシーオプション:

戦略	説明
`pairing`	不明な送信者がワンタイムペアリングコードを受信したため、承認が必要です。
`allowlist`	allowFrom 内の送信者のみ
`open`	すべての受信 DM を許可します (allowFrom: ["*"] が必要です)
`disabled`	すべてのDMを無視してください

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

json5

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

3. ゲートウェイ構成（ゲートウェイ）

json5

{
  gateway: {
    port: 18789,
    bind: "loopback",           // loopback | lan | tailnet | auto | custom
    auth: {
      mode: "token",            // token | password
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
      allowTailscale: true
    },
    tailscale: {
      mode: "off",              // off | serve | funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",           // hybrid | hot | restart | off
      debounceMs: 300
    }
  }
}

バインドアドレスオプション:

値	説明
`loopback`	ローカルアクセスのみ (127.0.0.1)
`lan`	LANアクセス可能
`tailnet`	テールスケールネットワーク
`auto`	自動検出
`custom`	カスタムアドレス

ホットリロードモード:

パターン	行動
`hybrid`	安全な変更をホット適用し、重要な変更を自動的に再開します (デフォルト)
`hot`	安全な変更のみをホット適用し、再起動が必要な場合は警告をログに記録します。
`restart`	構成を変更した場合はゲートウェイを再起動します。
`off`	ファイル監視を無効にする

4. セッション設定(セッション)

json5

{
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer
    
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0
    },
    
    reset: {
      mode: "daily",            // daily | idle | manual
      atHour: 4,
      idleMinutes: 120
    }
  }
}

DM スコープオプション:

値	説明
`main`	共有セッション
`per-peer`	ピアごとの独立したセッション
`per-channel-peer`	チャネルごと - ピアへの独立したセッション (マルチユーザー推奨)
`per-account-channel-peer`	アカウントチャネルピアごとの独立したセッション

5. メッセージ構成(メッセージ)

json5

{
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

6. ツール構成（ツール）

json5

{
  tools: {
    profile: "full",              // messaging | default | coding | full | all
    enabled: true,
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"
      }
    }
  }
}

ツール設定ファイル:

プロフィール	説明
`messaging`	チャットのみ、ツールなし
`default`	基本的なツールセット
`coding`	プログラミングツールセット
`full`	完全なツールセット
`all`	すべてのツール

7. スキル構成（スキル）

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  }
}

8. スケジュールされたタスクの設定 (cron)

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    }
  }
}

9. Webhookの設定(フック)

json5

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

10. バインディング設定 (バインディング)

json5

{
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

11. 環境変数の設定(env)

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

環境変数ソース (優先度別):

親プロセスの環境変数
現在の作業ディレクトリ内の .env ファイル
~/.openclaw/.env ファイル (グローバルフォールバック)

どちらも既存の環境変数を上書きしません。

12. 構成の分割 ($include)

大規模な構成を整理するには、$include を使用します。

json5

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

ルール:

単一ファイル: 含まれているオブジェクトを置き換えます
ファイル配列: 順番にディープマージ (最新のものから順)
兄弟キー: インクルード後にマージ (インクルードされた値を上書き)
ネストされたインクルード: 最大 10 レベルの深さをサポート
相対パス: 含まれているファイルを基準にして解決されます。

13. 環境変数の置換

構成文字列値内の参照環境変数:

json5

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

ルール:

大文字の名前のみに一致します: [A-Z_][A-Z0-9_]*
ロード中に変数が欠落しているか空であるとエラーが発生する
$${VAR} を使用してリテラル出力にエスケープします
$include ファイルでも有効
インライン置換: "${BASE}/v1" → "https://api.example.com/v1"

14. SecretRef 証明書

SecretRef オブジェクトのサポートされているフィールド:

json5

{
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "env",
          provider: "default",
          id: "OPENAI_API_KEY"
        }
      }
    }
  },
  
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  },
  
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount"
      }
    }
  }
}

ソースタイプ:

env: 環境変数
file: ファイルの内容
exec：コマンド実行出力

15. 完全な構成例

15.1 最小構成

json5

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

15.2 ローカル開発構成

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "ollama/llama3.2"
      }
    }
  },
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "dev-token"
    }
  }
}

15.3 サーバー展開構成

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  },
  
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  },
  
  gateway: {
    port: 18789,
    bind: "lan",
    auth: {
      mode: "password",
      password: "${GATEWAY_PASSWORD}"
    }
  },
  
  session: {
    dmScope: "per-channel-peer"
  }
}

15.4 マルチエージェント構成

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    },
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  },
  
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

16. 構成編集方法

インタラクティブウィザード

bash

openclaw onboard          # 完整设置向导
openclaw configure        # 配置向导

CLI コマンド

bash

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config file      # 查看配置文件路径
openclaw config validate  # 验证配置

Web コンソール

http://127.0.0.1:18789 を開き、[構成] タブを使用します。

直接編集する

~/.openclaw/openclaw.json を直接編集すると、ゲートウェイが自動的に変更を適用します。

17. 厳密な検証

OpenClaw は、スキーマに正確に一致する構成のみを受け入れます。不明なキー、不正な形式、または無効な値により、ゲートウェイの起動が拒否される可能性があります。

検証が失敗した場合:

ゲートウェイが起動しない
診断コマンドのみが使用可能です (openclaw doctor、openclaw logs、openclaw health、openclaw status)
openclaw doctor を実行して、特定の問題を表示します
openclaw doctor --fix を実行して修正を適用します

18. ホットリロード手順

ホットアプリケーション構成のサポート

カテゴリー	フィールド	再起動する必要がありますか?
チャンネル	`channels.*`	いいえ
エージェント＆モデル	`agent`、`agents`、`models`、`routing`	いいえ
自動化	`hooks`、`cron`、`agent.heartbeat`	いいえ
会話とメッセージ	`session`、`messages`	いいえ
ツールとメディア	`tools`、`browser`、`skills`、`audio`、`talk`	いいえ
UIとその他	`ui`、`logging`、`identity`、`bindings`	いいえ

再起動が必要な構成

カテゴリー	フィールド
ゲートウェイサーバー	`gateway.*` (ポート、バインディング、認証、テールスケール、TLS、HTTP)
インフラ	`discovery`、`canvasHost`、`plugins`

例外: gateway.reload および gateway.remote の変更は再起動をトリガーしません。

ヒント: この詳細な構成説明は、OpenClaw の公式ドキュメントに基づいています。完全な参照については、docs.openclaw.ai/gateway/configuration をご覧ください。

設定ファイルの場所 ​

設定ファイル構造の概要 ​

1. エージェントの設定 (エージェント) ​

1.1 デフォルト設定 (agents.defaults) ​

1.2 マルチエージェント構成 (agents.list) ​

2. チャネル構成(チャネル) ​

2.1 一般的な DM ポリシーの設定 ​

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

3. ゲートウェイ構成（ゲートウェイ） ​

4. セッション設定(セッション) ​

5. メッセージ構成(メッセージ) ​

6. ツール構成（ツール） ​

7. スキル構成（スキル） ​

8. スケジュールされたタスクの設定 (cron) ​

9. Webhookの設定(フック) ​

10. バインディング設定 (バインディング) ​

11. 環境変数の設定(env) ​

12. 構成の分割 ($include) ​

13. 環境変数の置換 ​

14. SecretRef 証明書 ​

15. 完全な構成例 ​

15.1 最小構成 ​

15.2 ローカル開発構成 ​

15.3 サーバー展開構成 ​

15.4 マルチエージェント構成 ​

16. 構成編集方法 ​

インタラクティブウィザード ​

CLI コマンド ​

Web コンソール ​

直接編集する ​

17. 厳密な検証 ​

18. ホットリロード手順 ​

ホットアプリケーション構成のサポート ​

再起動が必要な構成 ​

設定ファイルの場所

設定ファイル構造の概要

1. エージェントの設定 (エージェント)

1.1 デフォルト設定 (agents.defaults)

1.2 マルチエージェント構成 (agents.list)

2. チャネル構成(チャネル)

2.1 一般的な DM ポリシーの設定

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

3. ゲートウェイ構成（ゲートウェイ）

4. セッション設定(セッション)

5. メッセージ構成(メッセージ)

6. ツール構成（ツール）

7. スキル構成（スキル）

8. スケジュールされたタスクの設定 (cron)

9. Webhookの設定(フック)

10. バインディング設定 (バインディング)

11. 環境変数の設定(env)

12. 構成の分割 ($include)

13. 環境変数の置換

14. SecretRef 証明書

15. 完全な構成例

15.1 最小構成

15.2 ローカル開発構成

15.3 サーバー展開構成

15.4 マルチエージェント構成

16. 構成編集方法

インタラクティブウィザード

CLI コマンド

Web コンソール

直接編集する

17. 厳密な検証

18. ホットリロード手順

ホットアプリケーション構成のサポート

再起動が必要な構成