OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Hosting

Kubernetes

Un point de départ minimal pour exécuter OpenClaw sur Kubernetes, et non un déploiement prêt pour la production. Il couvre les ressources essentielles et doit être adapté à votre environnement.

Pourquoi ne pas utiliser Helm

OpenClaw est un conteneur unique accompagné de quelques fichiers de configuration. Les personnalisations pertinentes concernent le contenu de l’agent (fichiers Markdown, Skills, substitutions de configuration), et non la création de modèles d’infrastructure. Kustomize gère les superpositions sans la charge supplémentaire d’un chart Helm. Ajoutez un chart Helm au-dessus de ces manifestes si votre déploiement devient plus complexe.

Prérequis

  • Un cluster Kubernetes opérationnel (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
  • kubectl connecté à votre cluster
  • Une clé d’API pour au moins un fournisseur de modèles

Démarrage rapide

bash
# Remplacez par votre fournisseur : ANTHROPIC, GEMINI, OPENAI ou OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh kubectl port-forward svc/openclaw 18789:18789 -n openclawopen http://localhost:18789

Par défaut, deploy.sh crée une authentification par jeton. Récupérez le jeton Gateway généré pour l’interface de contrôle :

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

Pour le débogage local, ./scripts/k8s/deploy.sh --show-token affiche le jeton après le déploiement.

Tests locaux avec Kind

Si vous ne disposez pas d’un cluster, créez-en un localement avec Kind :

bash
./scripts/k8s/create-kind.sh           # détecte automatiquement docker ou podman./scripts/k8s/create-kind.sh --delete  # supprime le cluster

Déployez ensuite normalement avec ./scripts/k8s/deploy.sh.

Étapes détaillées

1) Déployer

Option A : clé d’API dans l’environnement (une seule étape)

bash
# Remplacez par votre fournisseur : ANTHROPIC, GEMINI, OPENAI ou OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh

Le script crée un Secret Kubernetes contenant la clé d’API et un jeton Gateway généré automatiquement, puis effectue le déploiement. Si le Secret existe déjà, il conserve le jeton Gateway actuel ainsi que toutes les clés de fournisseur qui ne sont pas modifiées.

Option B : créer le Secret séparément

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

Ajoutez --show-token à l’une ou l’autre commande pour afficher le jeton sur la sortie standard lors des tests locaux.

2) Accéder au Gateway

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

Ressources déployées

text
Espace de noms : openclaw (configurable via OPENCLAW_NAMESPACE)├── Deployment/openclaw        # Pod unique, conteneur d’initialisation + Gateway├── Service/openclaw           # ClusterIP sur le port 18789├── PersistentVolumeClaim      # 10 Gio pour l’état et la configuration de l’agent├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md└── Secret/openclaw-secrets    # Jeton Gateway + clés d’API

Personnalisation

Instructions de l’agent

Modifiez le fichier AGENTS.md dans scripts/k8s/manifests/configmap.yaml, puis redéployez :

bash
./scripts/k8s/deploy.sh

Configuration du Gateway

Modifiez openclaw.json dans scripts/k8s/manifests/configmap.yaml. Consultez la configuration du Gateway pour obtenir la référence complète.

Ajouter des fournisseurs

Réexécutez le déploiement après avoir exporté les clés supplémentaires :

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

Les clés de fournisseur existantes restent dans le Secret, sauf si vous les remplacez.

Vous pouvez également modifier directement le Secret :

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

Espace de noms personnalisé

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

Image personnalisée

Modifiez le champ image dans scripts/k8s/manifests/deployment.yaml :

yaml
image: ghcr.io/openclaw/openclaw:slim # principale ; miroir Docker Hub officiel : openclaw/openclaw

Exposer le service au-delà de la redirection de port

Les manifestes par défaut lient le Gateway à local loopback dans le pod. Cela fonctionne avec kubectl port-forward, mais pas avec un Service Kubernetes ou un chemin Ingress qui doit accéder directement à l’adresse IP du pod.

Pour exposer le Gateway au moyen d’un Ingress ou d’un équilibreur de charge :

  • Dans scripts/k8s/manifests/configmap.yaml, remplacez la liaison du Gateway loopback par une liaison qui n’utilise pas local loopback et qui correspond à votre modèle de déploiement.
  • Maintenez l’authentification du Gateway activée et utilisez un point d’entrée approprié avec terminaison TLS.
  • Configurez l’interface de contrôle pour l’accès distant à l’aide du modèle de sécurité Web pris en charge (par exemple, HTTPS/Tailscale Serve et des origines autorisées explicites si nécessaire).

Redéployer

bash
./scripts/k8s/deploy.sh

Cette commande applique tous les manifestes et redémarre le pod afin de prendre en compte toute modification de configuration ou de Secret.

Suppression

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

Cette commande supprime l’espace de noms et toutes les ressources qu’il contient, y compris le PVC.

Remarques sur l’architecture

  • Par défaut, le Gateway est lié à local loopback dans le pod ; la configuration fournie est donc destinée à kubectl port-forward.
  • Aucune ressource à l’échelle du cluster ; tout se trouve dans un seul espace de noms.
  • Renforcement de la sécurité : readOnlyRootFilesystem, capacités drop: ALL, utilisateur non-root (UID 1000).
  • La configuration par défaut maintient l’interface de contrôle sur la voie d’accès local la plus sûre : liaison local loopback et kubectl port-forward vers http://127.0.0.1:18789.
  • Si vous étendez l’accès au-delà de localhost, utilisez le modèle distant pris en charge : HTTPS/Tailscale, avec la liaison Gateway et les paramètres d’origine de l’interface de contrôle appropriés.
  • Les secrets sont générés dans un répertoire temporaire et appliqués directement au cluster ; aucun contenu secret n’est écrit dans la copie de travail du dépôt.

Structure des fichiers

text
scripts/k8s/├── deploy.sh                   # Crée l’espace de noms et le Secret, puis déploie via kustomize├── create-kind.sh              # Cluster Kind local (détecte automatiquement docker/podman)└── manifests/    ├── kustomization.yaml      # Base Kustomize    ├── configmap.yaml          # openclaw.json + AGENTS.md    ├── deployment.yaml         # Spécification du pod avec renforcement de la sécurité    ├── pvc.yaml                # Stockage persistant de 10 Gio    └── service.yaml            # ClusterIP sur le port 18789

Pages connexes

Was this useful?
On this page

On this page