途工街

Cloudflare上でMoltbot(OpenClaw)を利用する手順

, , ,
, , , ,

目次

1. 構成概要（何が動くか）

このプロジェクト(https://github.com/cloudflare/moltworker)は「Worker が入口になり、Sandbox コンテナ内で起動する Moltbot Gateway（ポート 18789）へ HTTP/WebSocket をプロキシする」構成です。

1.1 コンポーネント

  • Cloudflare Worker（Hono）: src/index.ts
    • / などのリクエストを Sandbox コンテナへ転送
    • Cloudflare Access の JWT を検証して認可（CF_ACCESS_*）
    • デバッグ/管理 API を提供（/_admin/, /api/admin/*, /debug/*）
    • cron（5分毎）で R2 へバックアップ同期
  • Cloudflare Sandbox コンテナ
    • Dockerfile でビルドされ、start-moltbot.sh により clawdbot gateway を起動
    • コンテナ内の設定ファイル: /root/.clawdbot/clawdbot.json
    • スキル置き場: /root/clawd/skills/
  • Durable Object（Sandbox）
    • Worker から Sandbox インスタンスを管理するための DO バインディング
  • R2（任意だが強く推奨）
    • コンテナの状態（設定・ペアリング情報・会話履歴等）を 5 分毎にバックアップ
    • マウントパス: /data/moltbot（S3FS 経由）
  • Cloudflare Access（必須 / 本実装のデフォルト運用前提）
    • Worker 側で JWT を検証して UI/API へのアクセスを制御
  • Browser Rendering（任意機能: CDP Shim）
    • /cdp 以下で CDP 互換 WebSocket を提供（秘密キーで保護）

1.2 ルーティング（入口 URL と役割）

  • GET /sandbox-health
    Worker 自体のヘルスチェック（JSON）
  • GET /api/status
    Gateway プロセスの稼働状況（JSON）
  • GET /_admin/
    管理 UI（デバイス承認 / バックアップ / Gateway 再起動）
  • GET|POST /api/admin/*
    管理 API（管理 UI が内部で使用）
  • GET /debug/*（DEBUG_ROUTES=true の時のみ）
    コンテナプロセス一覧/ログ/環境情報など
  • GET|WS /*
    Moltbot Gateway（コンテナ: 18789）へのプロキシ（Control UI / WebSocket RPC を含む）

（イメージ）

Browser/CLI
  │  HTTPS/WSS
  ▼
Cloudflare Worker (this repo)
  │  containerFetch / wsConnect
  ▼
Cloudflare Sandbox Container
  └─ clawdbot gateway :18789

2. 前提条件（Cloudflare 側・ローカル側）

2.1 Cloudflare 側の前提

  • Workers Paid plan（Sandbox/Containers の利用に必要）
  • Cloudflare Dashboard 上で Containers / Sandbox 機能が有効になっていること
  • Cloudflare Access（Zero Trust）が使えること（無料枠あり）
  • （任意）R2 を使う場合: R2 が使えること（無料枠あり）
  • （任意）Browser Rendering を使う場合: Browser Rendering が使えること（無料枠あり）

2.2 ローカル開発環境の前提

  • Node.js（推奨: 20+, 可能なら 22）
  • npm
  • Git

このリポジトリは wrangler を devDependencies に含むため、グローバルインストールは必須ではありません（npx wrangler ... を利用します）。

3. 重要な概念（認証・永続化・起動方式）

3.1 認証は「二重」になっています

本構成は、最低限次の 2 レイヤで守る設計です。

  1. Cloudflare Access（UI/API の入口）
    Worker 側が CF-Access-JWT-Assertion ヘッダーまたは CF_Authorization Cookie から JWT を取り出し、CF_ACCESS_TEAM_DOMAIN と CF_ACCESS_AUD で検証します。

  2. Gateway Token（Moltbot Gateway への接続）
    MOLTBOT_GATEWAY_TOKEN（Worker の secret）をコンテナ側の CLAWDBOT_GATEWAY_TOKEN にマップし、clawdbot gateway --token で起動します。
    Control UI / WebSocket 接続時に ?token=... を付けてアクセスします。

本リポジトリの現行実装では、本番運用で MOLTBOT_GATEWAY_TOKEN と CF_ACCESS_* を揃えて設定する前提です（未設定だと Worker が 503 を返します）。

3.2 デバイスペアリング（承認フロー）

Moltbot は、未承認のクライアント接続を「ペンディング」として保持し、管理者が承認して初めて利用できる仕組みがあります。
本プロジェクトでは /_admin/ の管理 UI から承認操作を行います。

  • ペンディング/ペア済みの一覧取得: clawdbot devices list --json --url ws://localhost:18789
  • 承認: clawdbot devices approve <requestId> --url ws://localhost:18789

※ CLI は WebSocket 接続の都合で 10〜15 秒程度かかることがあります。

3.3 永続化（R2 は “マウント” ではなく “バックアップ/リストア” として使う）

コンテナ内の重要データ（設定・ペアリング情報・会話履歴など）は、デフォルトではコンテナ再起動で消える可能性があります。
このプロジェクトは、R2 を S3FS で /data/moltbot にマウントし、以下の運用にしています。

  • 起動時: start-moltbot.sh が R2 側にバックアップがあればリストア（タイムスタンプ比較で新しい方を採用）
  • 運用中: Worker の cron（5分毎）が rsync でバックアップを更新（--no-times 使用）
  • 管理 UI: 「Backup Now」で手動同期

重要: /data/moltbot は R2 の実体です。コンテナ内で rm -rf /data/moltbot/* すると R2 のデータを消します。

3.4 起動（Cold start と keep-alive）

  • 初回アクセスやスリープ復帰時は、コンテナ起動に 1〜2 分程度かかる場合があります。
  • Worker は最大 3 分まで Gateway 起動を待つ設計です（STARTUP_TIMEOUT_MS=180_000）。
  • SANDBOX_SLEEP_AFTER を設定すると、無通信時にコンテナをスリープさせコストを下げられますが、その分 cold start が増えます。

4. 初回デプロイ手順（推奨の最短ルート）

ここでは「workers.dev 上にデプロイし、Access でログイン制御し、R2 で永続化する」最も堅い運用手順を示します。

4.1 リポジトリ取得と依存関係インストール

git clone <your-fork-or-repo-url>
cd moltbot-sandbox
npm install

4.2 Worker 名の確認（必要なら変更）

wrangler.jsonc の name が Worker 名になります。あなたのアカウント内でユニークな名前にしてください。

  • 設定ファイル: wrangler.jsonc
    • name: Worker 名
    • containers: instance_type, max_instances
    • r2_buckets: bucket_name（デフォルト moltbot-data）
    • triggers.crons: */5 * * * *（5分毎バックアップ）

4.3 必須 secret の投入（最低限これで起動可能）

A. Gateway Token を作る（推奨: ランダム 32 文字程度）

export MOLTBOT_GATEWAY_TOKEN=$(openssl rand -base64 32 | tr -d '=+/' | head -c 32)
echo "$MOLTBOT_GATEWAY_TOKEN"
echo "$MOLTBOT_GATEWAY_TOKEN" | npx wrangler secret put MOLTBOT_GATEWAY_TOKEN

このトークンは Control UI の URL に付与して使います。漏洩すると危険なので厳重に管理してください。

B. LLM プロバイダ設定（どちらか必須）

本実装は次のどちらかが必要です。

  • (推奨) Cloudflare AI Gateway 経由: AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL
  • (簡易) 直接 Anthropic: ANTHROPIC_API_KEY

例: 直接 Anthropic を使う場合

npx wrangler secret put ANTHROPIC_API_KEY

例: AI Gateway を使う場合（Anthropic）

npx wrangler secret put AI_GATEWAY_API_KEY
npx wrangler secret put AI_GATEWAY_BASE_URL
# 例: https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic

AI_GATEWAY_BASE_URL の末尾が /openai の場合、コンテナ側は OpenAI 用設定として扱います（start-moltbot.sh の挙動）。

C. Cloudflare Access（Worker が JWT 検証するための値）

npx wrangler secret put CF_ACCESS_TEAM_DOMAIN
# 例: myteam.cloudflareaccess.com

npx wrangler secret put CF_ACCESS_AUD
# Access Application の Audience (AUD) を入力

4.4 Cloudflare Access の設定（Zero Trust）

Worker 側は JWT を検証するだけなので、Access による保護（JWT の付与）は Cloudflare 側で別途設定が必要です。

推奨: 最初は「Worker 全体」を Access で保護

最短で確実に動かすには、workers.dev ドメインの Access を有効化して Worker 全体にログインを要求するのが簡単です。

  1. Cloudflare Dashboard → Workers & Pages → 対象 Worker
  2. Settings → Domains & Routes
  3. workers.dev の行で Cloudflare Access を有効化
  4. Zero Trust 側で許可ユーザー（メール/IdP）を設定
  5. Application の Audience (AUD) を控える → CF_ACCESS_AUD に設定済みか確認

補足: もし /api/status を外部監視で “公開” したい等がある場合は、パス単位で Access を適用する設計にしてください（上級者向け）。

4.5 R2 永続化（推奨）

4.5.1 バケット名の方針

デフォルトは moltbot-data です。

  • そのまま使う: R2 に moltbot-data バケットを作成（または wrangler が作れない場合に手動作成）
  • 変える: wrangler.jsonc の r2_buckets.bucket_name と、src/config.ts の R2_BUCKET_NAME を一致させる

4.5.2 R2 API Token（Access Key）を作成

R2 の「S3互換 API」用のアクセスキーが必要です。

Cloudflare Dashboard → R2 → API Tokens（名称は画面により異なる）で以下を作成:

  • 対象バケット: moltbot-data（または自分のバケット）
  • 権限: Object Read & Write（読み書き）
  • 取得する値:
    • Access Key ID
    • Secret Access Key

4.5.3 R2 用 secret を投入

npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
npx wrangler secret put CF_ACCOUNT_ID

CF_ACCOUNT_ID は Cloudflare ダッシュボードで確認できます（アカウントの ID）。

4.6 デプロイ

npm run deploy

初回はコンテナビルド（Dockerfile）が走るため時間がかかることがあります。

デプロイ後、ログ監視を開始:

npx wrangler tail

5. 初回起動確認（チェックリスト）

5.1 Worker の疎通

  • GET https://<your-worker>.workers.dev/sandbox-health
    → {"status":"ok", ...} が返る

（Access を Worker 全体に掛けた場合は、まず Access ログインが必要です）

5.2 Gateway の起動状態

  • GET https://<your-worker>.workers.dev/api/status
    • not_running → まだ起動していない（初回アクセス前）
    • running → 起動済み
    • not_responding → 起動途中/異常の可能性

5.3 Control UI へアクセス

Control UI は Gateway Token をクエリで渡します。

https://<your-worker>.workers.dev/?token=<MOLTBOT_GATEWAY_TOKEN>
  • 初回/スリープ復帰直後はローディング画面が出ることがあります（バックグラウンドで gateway 起動）。
  • うまく行かない場合は npx wrangler tail で起動ログを確認してください。

5.4 管理 UI（デバイス承認）

https://<your-worker>.workers.dev/_admin/

管理 UI でできること:

  • R2 バックアップ状態（未設定だと警告）
  • 「Backup Now」（手動同期）
  • 「Restart Gateway」（gateway 再起動）
  • ペアリング要求の承認（Approve / Approve All）

反映まで 10〜15 秒かかることがあるため、Refresh しながら待つのがコツです。

6. 運用（Runbook）

6.1 日次/定期確認

  • /_admin/ の Last backup が更新されている（R2 利用時）
  • GET /api/status が running
  • エラー/リトライが増えていない（npx wrangler tail）

6.2 バックアップ運用（R2）

自動バックアップ

  • 5分毎に cron が動き、以下を R2 に同期します:
    • /root/.clawdbot/ → /data/moltbot/clawdbot/
    • /root/clawd/skills/ → /data/moltbot/skills/
    • /data/moltbot/.last-sync に ISO 時刻を書き込み

手動バックアップ

  • /_admin/ → Backup Now

バックアップの整合性（考え方）

  • 同期は rsync --delete を使うため、ソース側の状態が壊れていると危険です。
    そのため実装では「/root/.clawdbot/clawdbot.json が存在する」ことを確認してから同期します。

6.3 Gateway 再起動

再起動が有効なケース:

  • 設定変更後（モデル/プロバイダ/チャンネル等）に反映したい
  • 何らかのエラーで動作が不安定
  • WebSocket が切断/再接続を繰り返す

手順:

  1. /_admin/ → Restart Gateway
  2. 一時的に全クライアントが切断されるが、自動で再接続されます

6.4 監視・ログ

リアルタイムログ

npx wrangler tail

公開ヘルス（Access の掛け方次第）

  • GET /sandbox-health
  • GET /api/status

Access を Worker 全体に掛けると、これらもログインが必要になります。運用ポリシーに合わせて設計してください。

6.5 デバッグルート（本番は慎重に）

DEBUG_ROUTES=true を設定すると /debug/* が有効になります（Access 必須）。

npx wrangler secret put DEBUG_ROUTES
# true と入力
npm run deploy

主なエンドポイント:

  • GET /debug/version（コンテナ内の clawdbot / node バージョン）
  • GET /debug/processes（プロセス一覧、?logs=true でログも）
  • GET /debug/logs?id=<process_id>（指定プロセスのログ）
  • GET /debug/env（環境設定の有無をマスクして表示）
  • GET /debug/container-config（/root/.clawdbot/clawdbot.json を取得）
  • GET /debug/cli?cmd=<command>（任意コマンドの実行: 取り扱い注意）
  • GET /debug/ws-test（WebSocket の簡易テストページ）

debug/cli は強力です。Access の許可ユーザーを最小にし、必要な時だけ有効化してください。

7. 変更作業（アップデート/設定変更/秘密情報ローテーション）

7.1 clawdbot（Moltbot）バージョンを上げる

コンテナは Dockerfile で clawdbot@... を pin しています。

  1. Dockerfile の以下を更新:
    • npm install -g clawdbot@<new-version>
  2. キャッシュバストのため、Dockerfile のコメントを変更:
    • # Build cache bust: YYYY-MM-DD-vNN-...
  3. 再デプロイ:
npm run deploy

7.2 モデル/プロバイダ切替（Anthropic / OpenAI / AI Gateway）

コンテナ起動時に start-moltbot.sh が clawdbot.json を更新します。

  • AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL があると優先
  • AI_GATEWAY_BASE_URL の末尾が /openai なら OpenAI 扱い
  • それ以外は Anthropic 扱い

変更手順（例: AI Gateway を導入）:

npx wrangler secret put AI_GATEWAY_API_KEY
npx wrangler secret put AI_GATEWAY_BASE_URL
npm run deploy

反映が怪しい時:

  • /_admin/ → Restart Gateway
  • DEBUG_ROUTES=true の上で GET /debug/container-config で実際の設定を確認

7.3 Gateway Token（MOLTBOT_GATEWAY_TOKEN）のローテーション

  1. 新しいトークンを生成
  2. wrangler secret put MOLTBOT_GATEWAY_TOKEN で更新
  3. 再デプロイ（または Worker 側は即反映でも、コンテナに渡すためには再起動が必要になりやすい）
  4. /_admin/ で Restart Gateway
  5. 利用者に新 URL を配布（古い URL は無効化）

7.4 Cloudflare Access の変更（許可ユーザー/IdP 変更）

Access 側のポリシー変更だけなら Worker 側の redeploy は不要です。
ただし、以下を変更した場合は Worker secret も更新が必要です。

  • Access Application を作り直して AUD が変わった → CF_ACCESS_AUD を更新
  • Team domain が変わった → CF_ACCESS_TEAM_DOMAIN を更新

7.5 永続化バケットの変更（上級者向け）

バケット名を変える場合は Worker とコンテナの両方が同じ名前を見る必要があります。

  1. wrangler.jsonc の r2_buckets.bucket_name を変更
  2. src/config.ts の R2_BUCKET_NAME を変更
  3. デプロイ

8. トラブルシューティング

8.1 503: Configuration error（必要な secret が無い）

症状:

  • ブラウザで 503 が返る
  • HTML のエラーページに「Missing variables」が出る

対処:

npx wrangler secret list

本番で最低限必要になりやすいもの:

  • MOLTBOT_GATEWAY_TOKEN
  • CF_ACCESS_TEAM_DOMAIN
  • CF_ACCESS_AUD
  • ANTHROPIC_API_KEY または AI_GATEWAY_API_KEY（+ AI_GATEWAY_BASE_URL）

8.2 401: Unauthorized（Access が効いていない / JWT が来ない）

症状:

  • /_admin/ や /api/admin/* が 401

原因候補:

  • Cloudflare Access アプリケーションの対象ドメイン/パスが間違っている
  • CF_ACCESS_TEAM_DOMAIN / CF_ACCESS_AUD が間違っている
  • Access ログインが済んでいない（Cookie が無い）

確認:

  • Access の設定（対象 URL, paths, policy）
  • DEBUG_ROUTES=true の上で GET /debug/env を見る（has_cf_access_aud 等）

8.3 Control UI が開けない: “Invalid or missing token”

症状:

  • WebSocket エラー/画面エラーで token mismatch と出る

対処:

  • URL に ?token=<MOLTBOT_GATEWAY_TOKEN> を付ける
  • トークンが合っているか確認（wrangler secret list では値は見えないので、手元の保管値と照合）
  • 変更した直後なら /_admin/ で Restart Gateway

8.4 初回アクセスが遅い / タイムアウトする

想定:

  • cold start は 1〜2 分程度かかることがあります

対処:

  • まず 2〜3 分待って再試行
  • npx wrangler tail で gateway 起動ログを確認
  • 省コスト目的で SANDBOX_SLEEP_AFTER を設定している場合は、cold start が増えます

8.5 R2 が効かない（バックアップされない / 復元されない）

よくある原因:

  • R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, CF_ACCOUNT_ID が未設定
  • バケット名の不一致（wrangler.jsonc と src/config.ts）
  • wrangler dev では R2 マウントが成立しない（本番のみ）

確認ポイント:

  • /_admin/ で R2 未設定警告が出ていないか
  • DEBUG_ROUTES=true で GET /debug/processes?logs=true を見て mount/rsync のエラーを確認

8.6 デバイスが管理 UI に出てこない

前提:

  • デバイス一覧取得 CLI は遅い（10〜15 秒）

対処:

  • /_admin/ で Refresh を数回（待ちながら）実行
  • DEBUG_ROUTES=true で GET /debug/cli?cmd=clawdbot%20devices%20list%20--json%20--url%20ws://localhost:18789 を実行して raw を確認

8.7 設定変更が反映されない

原因候補:

  • コンテナイメージがビルドキャッシュで更新されていない
  • gateway が古いプロセスのまま

対処:

  • Dockerfile の # Build cache bust: を更新して redeploy
  • /_admin/ で Restart Gateway

9. 付録

9.1 Secret 一覧（本リポジトリ準拠）

目的 Secret 必須 備考
Gateway 認証 MOLTBOT_GATEWAY_TOKEN ✅ Control UI へ ?token= で渡す
Access JWT 検証 CF_ACCESS_TEAM_DOMAIN ✅ myteam.cloudflareaccess.com 形式
Access JWT 検証 CF_ACCESS_AUD ✅ Access Application の AUD
LLM（直） ANTHROPIC_API_KEY ✅* AI Gateway 未使用時
LLM（AI Gateway） AI_GATEWAY_API_KEY ✅* 使う場合は必須
LLM（AI Gateway） AI_GATEWAY_BASE_URL ✅* AI_GATEWAY_API_KEY とセット
R2 永続化 R2_ACCESS_KEY_ID 推奨 未設定でも動くが永続化なし
R2 永続化 R2_SECRET_ACCESS_KEY 推奨 同上
R2 永続化 CF_ACCOUNT_ID 推奨 R2 endpoint 組み立てに使用
デバッグ DEBUG_ROUTES 任意 true で /debug/* 有効
スリープ SANDBOX_SLEEP_AFTER 任意 never / 10m など
Telegram TELEGRAM_BOT_TOKEN 任意 連携する場合
Telegram TELEGRAM_DM_POLICY 任意 pairing（既定）/open
Discord DISCORD_BOT_TOKEN 任意 連携する場合
Discord DISCORD_DM_POLICY 任意 pairing（既定）/open
Slack SLACK_BOT_TOKEN 任意 連携する場合（App Token も必要）
Slack SLACK_APP_TOKEN 任意 同上
CDP CDP_SECRET 任意 /cdp?secret=... で利用
CDP WORKER_URL 任意 スキル側設定で参照する想定

✅* は「AI Gateway か直 API かどちらか必須」の意味です。

9.2 よく使うコマンド

# デプロイ
npm run deploy

# ログ監視
npx wrangler tail

# secret 一覧
npx wrangler secret list

# secret 設定（例）
npx wrangler secret put MOLTBOT_GATEWAY_TOKEN

# ローカル開発（注意: WS 制約あり）
cp .dev.vars.example .dev.vars
npm run start

9.3 参考: CDP（Browser Rendering）を使う場合の URL 形

この Worker の CDP は「secret をクエリで渡す」方式です。

  • Discovery:
    • GET https://<worker>/cdp/json/version?secret=<CDP_SECRET>
    • GET https://<worker>/cdp/json/list?secret=<CDP_SECRET>
  • WebSocket:
    • wss://<worker>/cdp?secret=<CDP_SECRET>

（スキル skills/cloudflare-browser では cdpUrl を https://<worker>/cdp?secret=... として設定する例が載っています）

途工街をもっと見る

購読すると最新の投稿がメールで送信されます。

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。

こんにちは !

I’m Lex, a Salesforce consultant/engineer based in Tokyo. I love photography and motorcycles. Welcome to my website!

入会する

最新のコツやその他のニュースを知りたい場合は、ニュースレターに参加して最新情報を入手しましょう。

カテゴリー

タグ

35mm AI AI Agent browseruse browseruse webui case cbr400r cbr500r cline CMY染料层 Film Digitization Film Scanning LED光源 Moltbot motocycle negative OpenClaw python RGB三色混光 salesforce SONY FDR-X3000 viewer ケース セールスフォース ネガフィルム フィルムカメラ フィルムスキャナー フィルムデジタル 专业摄影灯 千葉県 山路 摩托 日常 日本 氙气闪光灯 胶片 胶片扫描 胶片翻拍 色彩校准 色彩管理 色彩还原 骑士 骑行 骑行录影设备 高CRI LED

最近の投稿