کوبرنتیز

نقطه شروعی حداقلی برای اجرای OpenClaw روی Kubernetes است، نه استقراری آماده برای محیط تولید. این راهنما منابع اصلی را پوشش می‌دهد و برای سازگار شدن با محیط شما در نظر گرفته شده است.

چرا Helm نه

OpenClaw یک کانتینر واحد با چند فایل پیکربندی است. سفارشی‌سازی مهم در محتوای عامل (فایل‌های Markdown، Skills و بازنویسی‌های پیکربندی) انجام می‌شود، نه در قالب‌سازی زیرساخت. Kustomize هم‌پوشانی‌ها را بدون سربار یک نمودار Helm مدیریت می‌کند. اگر استقرار شما پیچیده‌تر شد، یک نمودار Helm روی این مانیفست‌ها قرار دهید.

آنچه نیاز دارید

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

شروع سریع

# 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

deploy.sh به‌طور پیش‌فرض احراز هویت مبتنی بر توکن ایجاد می‌کند. توکن تولیدشده Gateway را برای رابط کنترل دریافت کنید:

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           # auto-detects docker or podman./scripts/k8s/create-kind.sh --delete  # tear down

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

گام‌به‌گام

۱) استقرار

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

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

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

گزینه ب: ایجاد Secret به‌صورت جداگانه

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

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

۲) دسترسی به Gateway

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

مواردی که مستقر می‌شوند

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

سفارشی‌سازی

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

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

./scripts/k8s/deploy.sh

پیکربندی Gateway

فایل openclaw.json را در scripts/k8s/manifests/configmap.yaml ویرایش کنید. برای مرجع کامل، به پیکربندی 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

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

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

ایمیج سفارشی

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

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

در معرض دسترسی قرار دادن فراتر از هدایت پورت

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

برای در معرض دسترسی قرار دادن Gateway از طریق Ingress یا متعادل‌کننده بار:

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

استقرار مجدد

./scripts/k8s/deploy.sh

این فرمان همه مانیفست‌ها را اعمال و پاد را راه‌اندازی مجدد می‌کند تا هرگونه تغییر در پیکربندی یا Secret اعمال شود.

برچیدن

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

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

نکات معماری

• Gateway به‌طور پیش‌فرض داخل پاد به local loopback متصل می‌شود؛ بنابراین، راه‌اندازی ارائه‌شده برای kubectl port-forward است.
• هیچ منبعی در سطح کلاستر وجود ندارد؛ همه‌چیز در یک فضای نام واحد قرار دارد.
• مقاوم‌سازی امنیتی: readOnlyRootFilesystem، قابلیت‌های drop: ALL و کاربر غیرریشه (UID 1000).
• پیکربندی پیش‌فرض، رابط کنترل را در مسیر امن‌تر دسترسی محلی نگه می‌دارد: اتصال local loopback به‌همراه kubectl port-forward به http://127.0.0.1:18789.
• اگر از دسترسی localhost فراتر می‌روید، از مدل راه دور پشتیبانی‌شده استفاده کنید: HTTPS/Tailscale به‌همراه اتصال مناسب Gateway و تنظیمات مبدأ رابط کنترل.
• Secretها در یک پوشه موقت تولید و مستقیماً روی کلاستر اعمال می‌شوند؛ هیچ داده محرمانه‌ای در نسخه کاری مخزن نوشته نمی‌شود.

ساختار فایل‌ها

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

مرتبط

• Docker
• محیط اجرای ماشین مجازی Docker
• نمای کلی نصب