OpenClawユーザーホワイトリストとアクセス権限の設定

はじめに

OpenClaw のゲートウェイを外部に公開すると、Bot のアカウントを知っている人なら誰でもやり取りできてしまいます。これは API コストの制御不能や、プライバシーリスクにつながる可能性があります。OpenClaw はグローバルホワイトリストからグループ別・チャンネル別の詳細な権限設定まで、多層的なアクセス制御メカニズムを提供しており、「誰が AI を使えるか」を正確にコントロールできます。

アクセス制御のアーキテクチャ

OpenClaw の権限判定は、以下の優先順位で各レイヤーを順にチェックします。

グローバルブラックリスト（最高優先度、即座に拒否）
  ↓
チャンネルレベルホワイトリスト
  ↓
グループホワイトリスト
  ↓
ユーザーホワイトリスト
  ↓
グローバルデフォルトポリシー（許可または拒否）

いずれかのレイヤーで拒否された場合、メッセージは処理されません。この階層設計により、「自分だけが使う」というシンプルなシナリオから、複数チームの複雑な権限管理まで対応できます。

グローバルデフォルトポリシー

まずグローバルのデフォルト動作を決定します。メッセージの送信元がどのホワイトリストにもブラックリストにも含まれない場合、許可するか拒否するかを指定します。

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "logDenied": true
    }
  }
}

defaultPolicy	動作
`"allow"`	デフォルトで全員を許可し、ブラックリストのユーザーのみ拒否
`"deny"`	デフォルトで全員を拒否し、ホワイトリストのユーザーのみ許可

"deny" の使用を推奨します。ホワイトリストモードで運行する方がより安全で、明示的な認可がないと使用できません。

logDenied を true に設定すると、拒否されたメッセージがログに記録され、ホワイトリストに追加すべき正当なユーザーを発見しやすくなります。

ユーザーホワイトリスト

ユーザー ID による設定

各メッセージングプラットフォームには固有のユーザー識別子があります。openclaw.json でチャンネルごとに許可ユーザーを設定できます。

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-token",
      "allowedUsers": [123456789, 987654321]
    },
    "discord": {
      "enabled": true,
      "token": "your-token",
      "allowedUsers": ["1234567890123456", "9876543210987654"]
    },
    "whatsapp": {
      "enabled": true,
      "allowedUsers": ["+8613800138000", "+8613900139000"]
    }
  }
}

ユーザー ID の形式はプラットフォームによって異なります。Telegram は数値 ID、Discord は文字列形式のスノーフレーク ID、WhatsApp は電話番号を使用します。

ユーザー ID の取得方法

各プラットフォームでのユーザー ID 取得方法は以下のとおりです。

プラットフォーム	取得方法
Telegram	@userinfobot にメッセージを送る、または OpenClaw のログで確認
Discord	開発者モードを有効にし、ユーザーを右クリック → ID をコピー
WhatsApp	電話番号をそのまま使用（国際電話番号形式）
Slack	プロフィールで Member ID を確認

最も簡単な方法は、まず defaultPolicy を "allow" にして全員が使えるようにし、OpenClaw のログに記録されたユーザー ID を確認してから、"deny" モードに切り替えてホワイトリストに追加することです。

グループホワイトリスト

AI が特定のグループでのみ応答し、任意のグループに追加されても返信しないようにしたい場合は、以下のように設定します。

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-token",
      "allowedGroups": [-100123456789, -100987654321]
    },
    "discord": {
      "enabled": true,
      "token": "your-token",
      "allowedChannels": ["general", "ai-chat"],
      "allowedGuilds": ["1234567890"]
    }
  }
}

グループ内のユーザーフィルタリング

グループがホワイトリストに入っていても、グループ内のどのユーザーが AI をトリガーできるかを制限できます。

{
  "channels": {
    "telegram": {
      "allowedGroups": [-100123456789],
      "groupUserPolicy": "allowlist",
      "groupAllowedUsers": {
        "-100123456789": [123456789, 111222333]
      }
    }
  }
}

このように設定すると、許可されたグループ内であっても、指定されたユーザーのみが AI の返信をトリガーでき、それ以外の人の @メンションは無視されます。

グローバルホワイトリスト

特定のユーザーをすべてのチャンネルで許可したい場合は、グローバルホワイトリストを使用して各チャンネルでの重複設定を避けられます。

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "globalAllowlist": {
        "users": ["tg:123456789", "dc:1234567890123456", "wa:+8613800138000"],
        "groups": ["tg:-100123456789", "dc:1234567890"]
      }
    }
  }
}

グローバルホワイトリストの識別子は <チャンネルプレフィックス>:<ID> の形式で、対応するプレフィックスは以下のとおりです。

プレフィックス	プラットフォーム
`tg`	Telegram
`dc`	Discord
`wa`	WhatsApp
`sl`	Slack
`im`	iMessage
`sg`	Signal
`mx`	Matrix

ブラックリスト

ブラックリストはホワイトリストよりも優先度が高くなります。ユーザーがホワイトリストに含まれていても、同時にブラックリストにも含まれている場合は拒否されます。

{
  "security": {
    "accessControl": {
      "blacklist": {
        "users": ["tg:999888777"],
        "groups": ["tg:-100111222333"],
        "reason": {
          "tg:999888777": "API の不正利用により、ブロック済み"
        }
      }
    }
  }
}

ブラックリストは、既知の悪意あるユーザーや不正利用されたグループへの対処に適しています。

ロールと権限

OpenClaw はさらに細かいロール権限システムもサポートしており、ユーザーが実行できる操作を制御できます。

{
  "security": {
    "accessControl": {
      "roles": {
        "admin": {
          "permissions": ["chat", "manage", "config", "dashboard"],
          "users": ["tg:123456789"]
        },
        "user": {
          "permissions": ["chat"],
          "users": ["tg:987654321", "tg:111222333"]
        },
        "viewer": {
          "permissions": ["chat:readonly"],
          "users": ["tg:444555666"]
        }
      }
    }
  }
}

使用可能な権限

権限	説明
`chat`	AI と会話する
`chat:readonly`	会話の閲覧のみ可能、メッセージ送信不可
`manage`	セッション管理（履歴のクリア、モデルの切り替えなど）
`config`	設定の変更（チャットコマンド経由）
`dashboard`	Web Dashboard へのアクセス
`admin`	すべての権限

プライベートチャットペアリング認証

プライベートチャットペアリングをサポートするチャンネル（WhatsApp、iMessage など）では、OpenClaw はペアリング認証メカニズムを提供しています。

{
  "security": {
    "accessControl": {
      "pairingRequired": true,
      "pairingMessage": "ペアリングコードを送信して利用を開始してください。ペアリングコードの取得は管理者にお問い合わせください。"
    }
  }
}

有効にすると、新規ユーザーが初めて Bot にプライベートメッセージを送る際にペアリング案内が表示され、正しいペアリングコードを入力して初めて利用を開始できます。ペアリングコードはコマンドラインで生成します。

# ワンタイムペアリングコードの生成
openclaw access pair-code --generate
# 出力: PAIR-A3F2-C1D8

# 特定ユーザー向けのペアリングコード生成
openclaw access pair-code --generate --user "tg:123456789"

アクセスログとモニタリング

アクセスログを有効にすると、OpenClaw はすべての権限判定結果を記録します。

# 最近のアクセスログを確認
openclaw access log --tail 50

# 出力例：
# 2026-03-14 14:30:22 ALLOW tg:123456789 chat "こんにちは"
# 2026-03-14 14:30:25 DENY  tg:999888777 chat "テスト" (blacklisted)
# 2026-03-14 14:31:10 DENY  tg:555666777 chat "hi" (not in allowlist)

Dashboard のセキュリティモニタリングページでは、以下のようなアクセス統計グラフを確認できます。

時間別/日別の許可・拒否回数
最も多く拒否されたユーザー ID（ホワイトリストに追加すべき正当なユーザーか、悪意ある探索の可能性あり）
各チャンネルの使用量分布

実践的な設定例

個人利用（自分だけ許可）

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "globalAllowlist": {
        "users": ["tg:123456789"]
      }
    }
  }
}

小規模チーム利用

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "roles": {
        "admin": {
          "permissions": ["admin"],
          "users": ["tg:123456789"]
        },
        "member": {
          "permissions": ["chat", "manage"],
          "users": ["tg:111111111", "tg:222222222", "tg:333333333"]
        }
      }
    }
  }
}

公開サービス（不正利用の制限）

{
  "security": {
    "accessControl": {
      "defaultPolicy": "allow",
      "blacklist": {
        "users": ["tg:999888777"]
      }
    },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 10,
      "windowMs": 60000
    }
  }
}

まとめ

OpenClaw のアクセス制御システムは、シンプルなホワイトリストからロール権限まで、個人利用からチームデプロイまでさまざまなシナリオに対応しています。重要なポイント：本番環境では常に defaultPolicy を "deny" に設定し、すべてのユーザーとグループを明示的に認可すること。logDenied を有効にして拒否されたリクエストを監視すること。定期的にホワイトリストを見直し、不要になったエントリを削除すること。セキュリティは一度きりの設定ではなく、継続的なプロセスです。