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

Hosting

Kubernetes

نقطه‌ی شروعی حداقلی برای اجرای OpenClaw روی Kubernetes — نه یک استقرار آماده‌ی تولید. این راهنما منابع اصلی را پوشش می‌دهد و قرار است متناسب با محیط شما تطبیق داده شود.

چرا نه Helm؟

OpenClaw یک کانتینر واحد با چند فایل پیکربندی است. سفارشی‌سازی مهم در محتوای agent است (فایل‌های markdown، Skills، بازنویسی‌های پیکربندی)، نه قالب‌بندی زیرساخت. Kustomize overlayها را بدون سربار یک chart در Helm مدیریت می‌کند. اگر استقرار شما پیچیده‌تر شود، می‌توان یک chart در Helm را روی این manifestها قرار داد.

چه چیزهایی لازم دارید

  • یک کلاستر Kubernetes در حال اجرا (AKS، EKS، GKE، k3s، kind، OpenShift و غیره)
  • kubectl متصل به کلاستر شما
  • یک کلید API برای دست‌کم یک ارائه‌دهنده‌ی مدل

شروع سریع

bash
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh kubectl port-forward svc/openclaw 18789:18789 -n openclawopen http://localhost:18789

راز مشترک پیکربندی‌شده برای Control UI را بازیابی کنید. این اسکریپت استقرار به‌صورت پیش‌فرض احراز هویت مبتنی بر توکن ایجاد می‌کند:

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

برای اشکال‌زدایی محلی، ./scripts/k8s/deploy.sh --show-token پس از استقرار توکن را چاپ می‌کند.

آزمایش محلی با Kind

اگر کلاستر ندارید، یکی را به‌صورت محلی با Kind بسازید:

bash
./scripts/k8s/create-kind.sh           # auto-detects docker or podman./scripts/k8s/create-kind.sh --delete  # tear down

سپس طبق معمول با ./scripts/k8s/deploy.sh استقرار را انجام دهید.

گام‌به‌گام

1) استقرار

گزینه A — کلید API در محیط (یک مرحله):

bash
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh

اسکریپت یک Secret در Kubernetes با کلید API و یک توکن Gateway تولیدشده به‌صورت خودکار ایجاد می‌کند و سپس استقرار را انجام می‌دهد. اگر Secret از قبل وجود داشته باشد، توکن فعلی Gateway و هر کلید ارائه‌دهنده‌ای را که تغییر نمی‌کند حفظ می‌کند.

گزینه B — secret را جداگانه ایجاد کنید:

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

اگر می‌خواهید توکن برای آزمایش محلی در stdout چاپ شود، با هرکدام از فرمان‌ها از --show-token استفاده کنید.

2) دسترسی به Gateway

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

چه چیزهایی مستقر می‌شود

Code
Namespace: openclaw (configurable via OPENCLAW_NAMESPACE)├── Deployment/openclaw        # Single pod, init container + gateway├── Service/openclaw           # ClusterIP on port 18789├── PersistentVolumeClaim      # 10Gi for agent state and config├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md└── Secret/openclaw-secrets    # Gateway token + API keys

سفارشی‌سازی

دستورالعمل‌های agent

AGENTS.md را در scripts/k8s/manifests/configmap.yaml ویرایش کنید و دوباره استقرار دهید:

bash
./scripts/k8s/deploy.sh

پیکربندی Gateway

openclaw.json را در scripts/k8s/manifests/configmap.yaml ویرایش کنید. برای مرجع کامل، پیکربندی Gateway را ببینید.

افزودن ارائه‌دهنده‌ها

با کلیدهای اضافی exportشده دوباره اجرا کنید:

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

کلیدهای ارائه‌دهنده‌ی موجود در Secret باقی می‌مانند مگر اینکه آن‌ها را بازنویسی کنید.

یا Secret را مستقیما patch کنید:

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

فضای نام سفارشی

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

image سفارشی

فیلد image را در scripts/k8s/manifests/deployment.yaml ویرایش کنید:

yaml
image: ghcr.io/openclaw/openclaw:latest # primary; official Docker Hub mirror: openclaw/openclaw:latest

ارائه فراتر از port-forward

manifestهای پیش‌فرض Gateway را داخل pod به loopback متصل می‌کنند. این با kubectl port-forward کار می‌کند، اما با یک Service در Kubernetes یا مسیر Ingress که باید به IP مربوط به pod برسد کار نمی‌کند.

اگر می‌خواهید Gateway را از طریق Ingress یا load balancer ارائه کنید:

  • اتصال Gateway را در scripts/k8s/manifests/configmap.yaml از loopback به یک اتصال غیر-loopback تغییر دهید که با مدل استقرار شما سازگار باشد
  • احراز هویت Gateway را فعال نگه دارید و از یک نقطه‌ی ورود مناسب با TLS پایان‌یافته استفاده کنید
  • Control UI را برای دسترسی راه دور با مدل امنیت وب پشتیبانی‌شده پیکربندی کنید (برای مثال HTTPS/Tailscale Serve و originهای مجاز صریح در صورت نیاز)

استقرار دوباره

bash
./scripts/k8s/deploy.sh

این همه‌ی manifestها را اعمال می‌کند و pod را restart می‌کند تا هر تغییر پیکربندی یا secret اعمال شود.

حذف

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

این فضای نام و همه‌ی منابع داخل آن، از جمله PVC، را حذف می‌کند.

یادداشت‌های معماری

  • Gateway به‌صورت پیش‌فرض داخل pod به loopback متصل می‌شود، بنابراین راه‌اندازی ارائه‌شده برای kubectl port-forward است
  • هیچ منبعی در سطح کلاستر وجود ندارد — همه‌چیز در یک فضای نام واحد قرار دارد
  • امنیت: قابلیت‌های readOnlyRootFilesystem، drop: ALL، کاربر غیر-root (UID 1000)
  • پیکربندی پیش‌فرض Control UI را روی مسیر امن‌تر دسترسی محلی نگه می‌دارد: اتصال loopback به‌علاوه‌ی kubectl port-forward به http://127.0.0.1:18789
  • اگر فراتر از دسترسی localhost می‌روید، از مدل راه دور پشتیبانی‌شده استفاده کنید: HTTPS/Tailscale به‌علاوه‌ی اتصال مناسب Gateway و تنظیمات origin در Control UI
  • secretها در یک دایرکتوری موقت تولید و مستقیما روی کلاستر اعمال می‌شوند — هیچ ماده‌ی محرمانه‌ای در checkout مخزن نوشته نمی‌شود

ساختار فایل

Code
scripts/k8s/├── deploy.sh                   # Creates namespace + secret, deploys via kustomize├── create-kind.sh              # Local Kind cluster (auto-detects docker/podman)└── manifests/    ├── kustomization.yaml      # Kustomize base    ├── configmap.yaml          # openclaw.json + AGENTS.md    ├── deployment.yaml         # Pod spec with security hardening    ├── pvc.yaml                # 10Gi persistent storage    └── service.yaml            # ClusterIP on 18789

مرتبط

Was this useful?
On this page

On this page