Gateway設定の構成例

はじめに

設定ファイルの作成中に、どの項目が最新の仕様に適合しているのか分からず、作業が止まってしまうことはありませんか。ドキュメントを往復する時間を減らし、すぐに動く構成を手に入れることが開発のスピードアップに繋がります。

現在のスキーマに完全に準拠した具体例を参考にすることが、確実なセットアップへの近道です。

必要なもの

• 現在の config schema の確認
• Configuration リファレンスへのアクセス

クイックスタート

最短で設定を完了させるためのステップです。

1. スキーマの確認 現在の config schema に基づいた構成例を確認します。これにより、古い設定形式によるエラーを回避できます。
2. リファレンスの参照 各フィールドの具体的な役割やフィールドごとの注意点については、Configuration を確認してください。

トラブルシューティング

現在のソースドキュメントに記載されている特定のトラブルシューティング情報はありません。

設定に関する詳細な仕様やエラーの解決方法については、Configuration ページにある各フィールドの注釈を参考にしてください。

不明な点がある場合は、AI Setup Assistant で質問することをおすすめします。

次のステップ

• Configuration

新しいツールを導入する際、設定項目の多さに圧倒されてしまうことはよくあります。やりたいことは「AI を自分のチャットツールで動かす」ことだけなのに、準備に時間がかかりすぎるとモチベーションが下がってしまいます。

OpenClaw は、最小限の設定ですぐに使い始めることができます。まずは動かしてみて、そこから自分好みにカスタマイズしていくのが一番の近道です。

必要なもの

• 設定ファイルを配置するディレクトリ: ~/.openclaw/
• 連携に使用する WhatsApp の電話番号

クイックスタート

OpenClaw をセットアップするための 2 つの方法を紹介します。

1. 最小構成での起動

最もシンプルな設定です。以下の内容を ~/.openclaw/openclaw.json として保存してください。

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

保存が完了したら、指定した電話番号からボットに DM を送ることができます。

2. おすすめの初期設定

実際に OpenClaw を活用するなら、キャラクター設定やモデルの指定を含むこちらの構成がおすすめです。

{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

トラブルシューティング

設定が反映されない場合は、ファイルパスが ~/.openclaw/openclaw.json に正しく配置されているかを確認してください。また、allowFrom に指定した電話番号と送信元の番号が一致しているかチェックしましょう。

---

さらに詳細なセットアップ手順や、特定の環境での構成について知りたい場合は、AI Setup Assistant がお手伝いします。

次のステップ

• Agent Configuration
• Channel Setup

複数のメッセージングプラットフォームを使い分けながら、AI エージェントの挙動を細かく制御するのは大変な作業です。セッションの有効期限、ツールの実行権限、各チャネル固有のルールなど、設定項目が増えるほど管理が難しくなります。

一つのファイルでこれらすべてを整理し、自分好みのエージェントを構築するための具体的なテンプレートを用意しました。

必要なもの

• JSON5 を扱えるテキストエディタ
• OpenRouter や Anthropic などの API Key
• Discord や Slack などの Channel 認証情報
• npm などの Node.js パッケージマネージャー

クイックスタート

1. プロジェクトのディレクトリに設定ファイルを作成します。
2. 以下のコードをコピーして貼り付けてください。JSON5 形式なので、コメントや末尾のカンマもそのまま利用できます。
3. YOUR_TELEGRAM_BOT_TOKEN や sk-or-... などのプレースホルダーを、実際の値に書き換えます。

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

  // Auth profile metadata (secrets live in auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"],
      "openai-codex": ["openai-codex:default"],
    },
  },

  // Identity
  identity: {
    name: "Samantha",
    theme: "helpful sloth",
    emoji: "🦥",
  },

  // Logging
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // Message formatting
  messages: {
    messagePrefix: "[openclaw]",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
  },

  // Routing + queue
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
      historyLimit: 50,
    },
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        slack: "collect",
        signal: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },

  // Tooling
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          // Optional CLI fallback (Whisper binary):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // Session behavior
  session: {
    scope: "per-sender",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/default/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Channels
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },

    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["steipete"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },

    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { allow: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
    },
  },

  // Agent runtime
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      blockStreamingDefault: "off",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",
      },
      blockStreamingCoalesce: {
        idleMs: 1000,
      },
      humanDelay: {
        mode: "natural",
      },
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      typingIntervalSeconds: 5,
      maxConcurrent: 3,
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-5",
        target: "last",
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
      sandbox: {
        mode: "non-main",
        perSession: true,
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
        },
        browser: {
          enabled: false,
        },
      },
    },
  },

  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["steipete"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Custom model providers
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // Cron jobs
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/cron.json",
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "./transforms/gmail.js",
          export: "transformGmail",
        },
      },
    ],
    gmail: {
      account: "openclaw@gmail.com",
      label: "INBOX",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
    },
  },

  // Gateway + networking
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

トラブルシューティング

• ログの確認: 動作に問題がある場合は、logging セクションで level を "info" に設定し、file で指定したパスのログを確認してください。
• セッションの初期化: エージェントの応答が不安定な場合は、session セクションで設定した resetTriggers（例: /new, /reset）をチャネル上で送信してセッションをリセットできます。
• メンテナンスモード: session.maintenance.mode が "warn" に設定されている場合、エントリ数が maxEntries（500）を超えると警告が表示されます。

AI Setup Assistant

次のステップ

• Authentication Profiles
• Channel Configuration
• Custom Model Providers
• Gateway Setup

新しいツールを導入するとき、設定ファイルの書き方で迷うことはありませんか？ドキュメントを読み込んで、一つずつパラメータを確認していくのは意外と時間がかかるものです。

特に複数のチャットツールを連携させたり、モデルのフォールバックを設定したりする場合、ベストプラクティスが最初から分かっているとスムーズに進みます。ここでは、よく使われる設定パターンをまとめました。

必要なもの

• 有効な API キー、またはボットトークン（Anthropic, Telegram, Discord, Slack, MiniMax など）
• ローカルモデルを使用する場合は LM Studio などの実行環境
• 設定ファイルを保存するための workspace ディレクトリ

クイックスタート

まずは、複数のプラットフォームを同時に動かす最小限の設定から始めましょう。5分でセットアップを完了させるための最短ルートです。

{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["yourname"] },
    },
  },
}

セキュアな DM モード（共有インボックス / 複数ユーザー）

2人以上のユーザーがボットに DM を送る可能性がある場合（allowFrom に複数のエントリがある、または dmPolicy: "open" の場合）、secure DM mode を有効にしてください。これを設定しないと、異なる送信者間で会話の文脈（context）が共有されてしまう可能性があります。

{
  // 複数ユーザーや機密性の高いエージェントに推奨される設定
  session: { dmScope: "per-channel-peer" },

  channels: {
    // 例：WhatsApp のマルチユーザー・インボックス
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // 例：Discord のマルチユーザー・インボックス
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["alice", "bob"] },
    },
  },
}

OAuth と API キーのフォールバック

認証の優先順位を柔軟に管理したい場合、以下の設定が便利です。まずは Anthropic の OAuth（サブスクリプション）を試し、それが利用できない場合に API キーへ切り替えることができます。

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: ["anthropic/claude-opus-4-6"],
    },
  },
}

Anthropic サブスクリプション + API キー、MiniMax フォールバック

さらに高度な構成として、Anthropic の認証を二段構えにしつつ、完全にダウンした際のバックアップとして MiniMax を指定するパターンです。

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "user@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-opus-4-6",
      fallbacks: ["minimax/MiniMax-M2.1"],
    },
  },
}

ワークボット（アクセス制限付き）

社内用など、特定の Slack チャンネルでのみ動作させ、管理者権限（elevated permissions）を無効化したい場合の設定です。

{
  identity: {
    name: "WorkBot",
    theme: "professional assistant",
  },
  agent: {
    workspace: "~/work-openclaw",
    elevated: { enabled: false },
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
    },
  },
}

ローカルモデルのみを使用する

外部 API を使わず、LM Studio などで動かしているローカルモデルのみを利用する構成です。プライバシーを重視する場合に最適です。

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.1-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

トラブルシューティング

• 問題： 複数のユーザーがボットに DM を送ると、会話の内容が混ざってしまう。
• 解決策： session: { dmScope: "per-channel-peer" } を設定に追加してください。これにより、送信者ごとに独立したセッションが作成されます。

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

次のステップ

• Authentication
• Channel Configuration
• Agent Workspace
• Model Providers

新しい API や Gateway を導入する際、設定ファイルのわずかな記述ミスで数時間を無駄にしてしまった経験はありませんか。ドキュメントを読み飛ばしたせいで、期待通りに通信が通らず頭を抱えるのは避けたいものです。

スムーズに開発を進めるために、設定を行う中で特に重要となるポイントをまとめました。これらを押さえることで、無用なデバッグ時間を減らすことができます。

必要なもの

• 各 Provider のドキュメント（Provider ID の形式確認用）
• Gateway の基本構成ファイル

クイックスタート

設定を最短で完了させるための重要なルールは以下の 2 つです。

1. DM ポリシーの設定 dmPolicy: "open" を設定する場合、対応する allowFrom リストには必ず "*" を含める必要があります。この組み合わせが一致していないと、期待した動作になりません。

2. Provider ID の形式確認 Provider ID は、電話番号、ユーザー ID、チャンネル ID など、使用するサービスによって形式が異なります。必ず Providers のドキュメントを参照し、正しい形式を使用しているか確認してください。

トラブルシューティング

• 問題: dmPolicy: "open" に設定したが、メッセージが正しくフィルタリングされない。
• 解決策: allowFrom リストに "*" が含まれているか確認してください。

また、必要に応じて以下のオプションセクションを後から追加し、機能を拡張できます。

• web, browser, ui, discovery
• canvasHost, talk, signal, imessage

設定の詳細で分からないことがあれば、AI Setup Assistant がサポートします。

次のステップ

• Providers
• Troubleshooting