OpenClaw on Kubernetes

Kubernetes 上で OpenClaw を実行するための最小限の出発点です。本番対応のデプロイではなく、コアリソースをカバーし、各環境に合わせてカスタマイズすることを前提としています。

Helm を使わない理由

OpenClaw は設定ファイルを伴う単一コンテナです。カスタマイズのポイントはインフラストラクチャテンプレートではなく、エージェントのコンテンツ（Markdown ファイル、スキル、設定のオーバーライド）にあります。Kustomize は Helm チャートのオーバーヘッドなしにオーバーレイを処理できます。デプロイがより複雑になった場合は、これらのマニフェストの上に Helm チャートを重ねることもできます。

必要なもの

  • 稼働中の Kubernetes クラスタ（AKS、EKS、GKE、k3s、kind、OpenShift など）
  • クラスタに接続された kubectl
  • 少なくとも 1 つのモデルプロバイダーの API キー

クイックスタート

# プロバイダーに合わせて置き換え：ANTHROPIC、GEMINI、OPENAI、または OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

Gateway トークンを取得してコントロール UI に貼り付けます：

kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d

ローカルデバッグ用に、./scripts/k8s/deploy.sh --show-token でデプロイ後にトークンを表示できます。

Kind でのローカルテスト

クラスタがない場合、Kind でローカルに作成できます：

./scripts/k8s/create-kind.sh           # docker または podman を自動検出
./scripts/k8s/create-kind.sh --delete  # 削除

その後、./scripts/k8s/deploy.sh で通常通りデプロイしてください。

ステップバイステップ

1) デプロイ

方法 A — 環境変数に API キーを設定（ワンステップ）：

# プロバイダーに合わせて置き換え：ANTHROPIC、GEMINI、OPENAI、または OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

スクリプトが API キーと自動生成された Gateway トークンを含む Kubernetes Secret を作成し、デプロイします。Secret が既に存在する場合、現在の Gateway トークンと変更されていないプロバイダーキーは保持されます。

方法 B — Secret を別途作成：

export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

ローカルテスト用にトークンを stdout に表示したい場合は、どちらのコマンドでも --show-token を使用してください。

2) Gateway へのアクセス

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

デプロイされるもの

Namespace: openclaw（OPENCLAW_NAMESPACE で変更可能）
├── Deployment/openclaw        # 単一 Pod、init コンテナ + Gateway
├── Service/openclaw           # ポート 18789 の ClusterIP
├── PersistentVolumeClaim      # エージェントの状態と設定用に 10Gi
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Gateway トークン + API キー

カスタマイズ

エージェントの指示

scripts/k8s/manifests/configmap.yaml 内の AGENTS.md を編集して再デプロイ：

./scripts/k8s/deploy.sh

Gateway 設定

scripts/k8s/manifests/configmap.yaml 内の openclaw.json を編集してください。完全なリファレンスは Gateway 設定を参照してください。

プロバイダーの追加

追加のキーをエクスポートして再実行：

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

既存のプロバイダーキーは上書きしない限り Secret に保持されます。

または Secret を直接パッチ：

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

カスタム Namespace

OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

カスタムイメージ

scripts/k8s/manifests/deployment.yaml の image フィールドを編集：

image: ghcr.io/openclaw/openclaw:2026.3.1

port-forward 以外での公開

デフォルトのマニフェストでは、Pod 内で Gateway をループバックにバインドしています。kubectl port-forward では動作しますが、Pod IP に到達する必要がある Kubernetes Service や Ingress パスでは動作しません。

Gateway を Ingress やロードバランサーを通じて公開する場合：

  • scripts/k8s/manifests/configmap.yaml の Gateway バインドを loopback からデプロイモデルに合った非ループバックバインドに変更
  • Gateway 認証を有効に保ち、適切な TLS 終端エントリポイントを使用
  • サポートされている Web セキュリティモデルに従ってコントロール UI をリモートアクセス用に設定（例：HTTPS/Tailscale Serve、必要に応じて許可オリジンを明示指定）

再デプロイ

./scripts/k8s/deploy.sh

すべてのマニフェストを適用し、設定や Secret の変更を反映するために Pod を再起動します。

削除

./scripts/k8s/deploy.sh --delete

Namespace とその中のすべてのリソース（PVC を含む）を削除します。

アーキテクチャに関する注意事項

  • Gateway はデフォルトで Pod 内のループバックにバインドするため、付属のセットアップは kubectl port-forward 用です
  • クラスタスコープのリソースなし — すべて単一の Namespace 内に収まります
  • セキュリティ：readOnlyRootFilesystem、drop: ALL ケイパビリティ、非 root ユーザー（UID 1000）
  • デフォルト設定では、コントロール UI がより安全なローカルアクセスパスに保たれます：ループバックバインド + kubectl port-forward で http://127.0.0.1:18789
  • localhost アクセスを超える場合は、サポートされているリモートモデル（HTTPS/Tailscale + 適切な Gateway バインドとコントロール UI オリジン設定）を使用
  • Secret は一時ディレクトリで生成され、クラスタに直接適用されます — リポジトリチェックアウトにシークレットマテリアルは書き込まれません

ファイル構造

scripts/k8s/
├── deploy.sh                   # Namespace + Secret を作成、kustomize でデプロイ
├── create-kind.sh              # ローカル Kind クラスタ（docker/podman を自動検出）
└── manifests/
    ├── kustomization.yaml      # Kustomize ベース
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # セキュリティハードニング付き Pod スペック
    ├── pvc.yaml                # 10Gi の永続ストレージ
    └── service.yaml            # ポート 18789 の ClusterIP
arrow_back
前へ
VPS
次へ
Fly
arrow_forward