OpenClaw設定ファイルopenclaw.json5完全ガイド

はじめに

OpenClaw のコア設定ファイルは openclaw.json5 で、デフォルトでは ~/.config/openclaw/openclaw.json5 に保存されています。このファイルは JSON5 フォーマットを採用しており、コメントやより柔軟な構文をサポートしているため、設定作業がよりスムーズになります。本記事では、すべての設定セクションとオプションを一つ一つ解説します。

JSON5フォーマットの紹介

JSON5 は JSON のスーパーセットで、主に以下の特徴が追加されています。

{
  // 単一行コメントをサポート
  /* 複数行コメントもサポート */

  // キー名に引用符が不要
  gateway: {
    port: 18789,
  },

  // 末尾のカンマをサポート
  tags: [
    "ai",
    "assistant",
  ],

  // シングルクォート文字列をサポート
  name: 'OpenClaw',

  // 複数行文字列をサポート
  prompt: "1行目\
    2行目",
}

JSON5 に馴染みがない方は、「コメントが書ける JSON」と考えていただければ大丈夫です。

設定ファイルのパス

プラットフォーム	デフォルトパス
Linux	`~/.config/openclaw/openclaw.json5`
macOS	`~/.config/openclaw/openclaw.json5`
Windows	`%USERPROFILE%\.config\openclaw\openclaw.json5`
Docker	`/app/config/openclaw.json5`（ボリュームマッピング経由）

環境変数でカスタムパスを指定することもできます。

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5
openclaw up

設定構造の全体像

{
  gateway: { /* ゲートウェイ設定 */ },
  models: { /* モデル設定 */ },
  channels: { /* チャネル連携 */ },
  skills: { /* スキルプラグイン */ },
  persona: { /* AIペルソナ */ },
  logging: { /* ログ設定 */ },
  security: { /* セキュリティ設定 */ },
  advanced: { /* 詳細オプション */ },
}

以下、各設定セクションを詳しく解説します。

gateway：ゲートウェイ設定

ゲートウェイは OpenClaw のコアエントリーポイントで、すべてのHTTPリクエストとチャネルメッセージを処理します。

{
  gateway: {
    // リッスンポート、デフォルト18789
    port: 18789,

    // リッスンアドレス
    // "127.0.0.1" ローカルマシンのみアクセス可能
    // "0.0.0.0" すべてのネットワークからアクセスを許可
    host: "0.0.0.0",

    // Dashboardパスワード（本番環境では設定を推奨）
    dashboardPassword: "your-strong-password",

    // APIキー（外部からOpenClaw APIを呼び出す際に使用）
    apiKey: "your-api-key",

    // リクエストタイムアウト（ミリ秒）
    timeout: 120000,

    // 最大リクエストボディサイズ
    maxBodySize: "10mb",

    // CORS設定
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

主要パラメータの説明

パラメータ	型	デフォルト値	説明
`port`	number	18789	ゲートウェイポート
`host`	string	"127.0.0.1"	リッスンアドレス
`dashboardPassword`	string	なし	Dashboardアクセスパスワード
`apiKey`	string	なし	API認証キー
`timeout`	number	120000	リクエストタイムアウト（ms）
`maxBodySize`	string	"10mb"	最大リクエストボディ

models：モデル設定

モデル設定は、OpenClaw がどのAIモデルを使用し、どのように呼び出すかを定義します。

{
  models: {
    // デフォルトで使用するモデルプロバイダ
    default: "claude",

    // 各モデルプロバイダの設定
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.anthropic.com",  // 任意、カスタムAPIエンドポイント
      },

      openai: {
        apiKey: "sk-xxxxx",
        model: "gpt-4o",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.openai.com/v1",
      },

      ollama: {
        baseUrl: "http://localhost:11434",
        model: "llama3.1",
        maxTokens: 2048,
      },

      gemini: {
        apiKey: "AIzaSyxxxxx",
        model: "gemini-2.0-flash",
        maxTokens: 4096,
      },

      openrouter: {
        apiKey: "sk-or-xxxxx",
        model: "anthropic/claude-sonnet-4-20250514",
        baseUrl: "https://openrouter.ai/api/v1",
      },
    },

    // モデルルーティングルール（マルチモデル切り替えチュートリアルを参照）
    routing: {
      rules: [],
      fallback: "claude",
    },
  },
}

各プロバイダの必須パラメータ

プロバイダ	必須パラメータ	任意パラメータ
Claude	`apiKey`, `model`	`maxTokens`, `temperature`, `baseUrl`
OpenAI	`apiKey`, `model`	`maxTokens`, `temperature`, `baseUrl`
Ollama	`baseUrl`, `model`	`maxTokens`, `temperature`
Gemini	`apiKey`, `model`	`maxTokens`, `temperature`
OpenRouter	`apiKey`, `model`	`maxTokens`, `baseUrl`

channels：チャネル連携

チャネル設定は、OpenClaw がどのメッセージングプラットフォームに接続するかを定義します。

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      // WhatsApp Business API設定
      accessToken: "your-access-token",
      verifyToken: "your-verify-token",
      webhookPath: "/webhook/whatsapp",
    },

    telegram: {
      enabled: true,
      token: "123456:ABC-DEF...",
      // 任意：許可するユーザーを制限
      allowedUsers: [12345678, 87654321],
      // 任意：許可するグループを制限
      allowedGroups: [-100123456789],
    },

    discord: {
      enabled: true,
      token: "your-discord-bot-token",
      allowedChannels: ["general", "ai-chat"],
    },

    slack: {
      enabled: true,
      appToken: "xapp-xxxxx",
      botToken: "xoxb-xxxxx",
    },

    // その他のチャネル...
    // imessage, signal, teams, googlechat, matrix, line, irc
  },
}

skills：スキルプラグイン

スキルは OpenClaw の拡張メカニズムで、SKILL.md ファイル形式で ~/.openclaw/skills/ ディレクトリに格納されます。

{
  skills: {
    // スキルファイルの格納ディレクトリ
    directory: "~/.openclaw/skills",

    // 有効なスキルリスト（空の場合はすべて有効）
    enabled: [
      "weather",
      "calculator",
      "translator",
    ],

    // 無効なスキルリスト
    disabled: [],

    // MCP Server統合
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
      },
      web: {
        command: "npx",
        args: ["-y", "@anthropic/mcp-server-web"],
      },
    },
  },
}

persona：AIペルソナ

ペルソナ設定は、AIアシスタントの性格と返答スタイルを決定します。

{
  persona: {
    // システムプロンプト
    systemPrompt: "あなたはフレンドリーでプロフェッショナルなAIアシスタント「小智」です。簡潔で分かりやすい中国語で質問に答えます。",

    // ペルソナ名
    name: "小智",

    // 返答言語（autoで自動検出）
    language: "zh-CN",

    // トーンスタイル：formal, casual, friendly, professional
    tone: "friendly",

    // チャネルごとの個別ペルソナ（グローバル設定を上書き）
    channelOverrides: {
      telegram: {
        systemPrompt: "あなたはTelegramグループの管理アシスタントです...",
        tone: "casual",
      },
      slack: {
        systemPrompt: "あなたはチームの業務アシスタントです。返答はプロフェッショナルで簡潔に...",
        tone: "professional",
      },
    },
  },
}

logging：ログ設定

{
  logging: {
    // ログレベル：debug, info, warn, error
    level: "info",

    // ログファイルパス（空の場合はコンソールのみに出力）
    file: "~/.openclaw/logs/openclaw.log",

    // ログファイルの最大サイズ
    maxSize: "10m",

    // 保持するログファイル数
    maxFiles: 5,

    // コンソールにカラーログを出力するか
    colorize: true,

    // ログフォーマット：json, text
    format: "text",
  },
}

security：セキュリティ設定

{
  security: {
    // リクエストレート制限を有効化
    rateLimit: {
      enabled: true,
      maxRequests: 60,     // 毎分の最大リクエスト数
      windowMs: 60000,     // ウィンドウ時間（ミリ秒）
    },

    // IPホワイトリスト（空の場合は制限なし）
    ipWhitelist: [],

    // IPブラックリスト
    ipBlacklist: [],

    // HTTPSを有効化（証書の提供が必要）
    tls: {
      enabled: false,
      cert: "/path/to/cert.pem",
      key: "/path/to/key.pem",
    },
  },
}

advanced：詳細オプション

{
  advanced: {
    // ワーカースレッド数（0で自動）
    workers: 0,

    // メッセージキューサイズ
    queueSize: 100,

    // コンテキストメモリの最大メッセージ数
    maxContextMessages: 20,

    // コンテキストメモリの最大トークン数
    maxContextTokens: 8000,

    // データストレージバックエンド：memory, sqlite, redis
    storage: "sqlite",

    // SQLiteデータベースパス
    dbPath: "~/.openclaw/data/openclaw.db",

    // Redis接続（storageがredisの場合）
    redis: {
      url: "redis://localhost:6379",
      db: 0,
    },
  },
}

環境変数によるオーバーライド

設定ファイル内の一部の機密フィールドは、環境変数でオーバーライドすることで、キーを直接ファイルに記載することを避けられます。

# モデルAPIキー
export OPENCLAW_CLAUDE_API_KEY="sk-ant-xxxxx"
export OPENCLAW_OPENAI_API_KEY="sk-xxxxx"

# チャネルトークン
export OPENCLAW_TELEGRAM_TOKEN="123456:ABC-DEF..."
export OPENCLAW_DISCORD_TOKEN="your-discord-token"

# ゲートウェイパスワード
export OPENCLAW_DASHBOARD_PASSWORD="your-password"

設定ファイル内で $env を使って参照します。

{
  models: {
    providers: {
      claude: {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
}

設定の検証

設定ファイルを変更した後、起動前に設定が正しいかどうかを検証できます。

# 設定ファイルの構文と必須項目をチェック
openclaw doctor

# 設定ファイルのみ検証（サービスは起動しない）
openclaw doctor --config-only

最小構成の例

最も基本的な機能のみ必要な場合、設定ファイルは非常にシンプルにできます。

{
  models: {
    default: "claude",
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      token: "your-telegram-bot-token",
    },
  },
}

明示的に設定されていないオプションはデフォルト値が使用されます。

まとめ

openclaw.json5 は OpenClaw のコア設定ファイルで、人に優しい JSON5 フォーマットを採用し、コメントや柔軟な構文をサポートしています。各設定セクションの役割を理解すれば、実際のニーズに合わせて OpenClaw の動作を正確に調整できます。最小構成から始めて、必要に応じて機能モジュールを段階的に追加することをお勧めします。設定変更後は openclaw doctor で検証し、openclaw restart で再読み込みすることをお忘れなく。