نحوه‌ی استقرار OpenClaw روی نمونه‌های Cloud Run

۱. مقدمه

نمای کلی

در این آزمایشگاه، شما یک نمونه کاملاً پایدار و امن از OpenClaw - یک چارچوب عامل هوش مصنوعی متن‌باز - را در Cloud Run Instances مستقر خواهید کرد. شما مستقیماً با استفاده از رابط کاربری وب داخلی OpenClaw (با امکان اتصال کانال‌های پیام‌رسان مانند تلگرام یا واتس‌اپ ) با عامل هوش مصنوعی خود تعامل خواهید داشت، فضای کاری خانگی آن را با Google Cloud Storage پشتیبانی می‌کنید و اعتبارنامه‌های API را با استفاده از Google Cloud Secret Manager به صورت ایمن مدیریت خواهید کرد.

قبل از شروع، می‌توانید مستندات OpenClaw را بررسی کنید تا با معماری، ابزارها و گردش‌های کاری عامل OpenClaw آشنا شوید.

کاری که انجام خواهید داد

  • APIهای مورد نیاز Google Cloud را فعال کنید و یک حساب کاربری سرویس اختصاصی با مجوزهای IAM مورد نیاز ایجاد کنید.
  • کلیدهای API و رمزهای عبور دروازه را به طور ایمن در Secret Manager ذخیره کنید.
  • یک فایل پیکربندی openclaw.json با تنظیمات مدل Gemini و رابط کاربری gateway فعال آماده کنید.
  • یک سطل ذخیره‌سازی ابری برای حفظ وضعیت کانتینر آماده کنید.
  • OpenClaw را با استفاده gcloud beta run instances deploy کنید.
  • با استفاده از رابط کاربری وب داخلی OpenClaw، مستقیماً با عامل هوش مصنوعی آن تعامل داشته باشید.
  • (اختیاری) یک کانال پیام‌رسانی ( تلگرام یا واتس‌اپ ) پیکربندی کنید.
  • (اختیاری) با افزودن مهارت‌های سفارشی به فضای ذخیره‌سازی ابری، قابلیت‌های نماینده خود را گسترش دهید.

آنچه یاد خواهید گرفت

  • نحوه‌ی استقرار OpenClaw در Cloud Run Instances با رابط کاربری وب داخلی Control آن.
  • نحوه‌ی اتصال سطل‌های ذخیره‌سازی ابری به نمونه‌های اجرای ابری.
  • چگونه می‌توان به طور ایمن رمزهای Secret Manager را به عنوان متغیرهای محیطی به Cloud Run تزریق کرد.
  • نحوه اجرای بارهای کاری عامل (agent) با مدت زمان طولانی و مداوم در نمونه‌های ابری (Cloud Run Instances).
  • نحوه پیکربندی و آپلود مهارت‌های سفارشی عامل در فضای ذخیره‌سازی ابری.

۲. تنظیمات و الزامات

راه‌اندازی پروژه GCP

  1. وارد کنسول ابری گوگل شوید.
  2. یک پروژه Google Cloud ایجاد یا انتخاب کنید.
  3. مطمئن شوید که پرداخت برای پروژه Google Cloud شما فعال است.

پوسته ابری را باز کنید

Google Cloud Shell را از نوار ابزار بالای کنسول ابری فعال کنید.

تنظیم پروژه و نصب نسخه بتای جی‌کلود

ابتدا، پروژه و منطقه خود را به عنوان متغیرهای محیطی تنظیم کنید.

export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION=<YOUR_REGION>

حالا پروژه خود را تنظیم کنید و تایید کنید.

gcloud config set project $PROJECT_ID
gcloud config get project

مطمئن شوید که کامپوننت beta برای gcloud beta run instances نصب شده است:

gcloud components install beta --quiet

و مطمئن شوید که gcloud شما به‌روز است.

gcloud components update

فعال کردن API های مورد نیاز Google Cloud

در Cloud Shell، رابط‌های برنامه‌نویسی کاربردی Cloud Run، Secret Manager، Cloud Storage و Gemini را فعال کنید:

gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com \
  generativelanguage.googleapis.com \
  compute.googleapis.com

۳. (اختیاری) تنظیم ادغام پیام‌رسان‌ها (تلگرام یا واتس‌اپ)

می‌توانید OpenClaw را به تلگرام یا واتس‌اپ متصل کنید. گزینه A یا گزینه B را در زیر انتخاب کنید.

گزینه الف: راه‌اندازی ربات تلگرام

  1. تلگرام را باز کنید و @BotFather را جستجو کنید.
  2. دستور /newbot را ارسال کنید و دستورالعمل‌ها را برای مشخص کردن نام ربات و نام کاربری دنبال کنید.
  3. توکن HTTP API تولید شده را کپی کنید (مثلاً، 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ ).
  4. در تلگرام عبارت @userinfobot را جستجو کنید، عبارت /start را ارسال کنید و شناسه کاربری عددی خود (مثلاً 8035936176 ) را کپی کنید.

گزینه ب: تنظیمات واتس‌اپ

  1. شماره تلفن شخصی واتس‌اپ خود را در قالب بین‌المللی و بدون فاصله یا نماد (مثلاً +15551234567 ) دریافت کنید.
  2. OpenClaw از طریق خط‌مشی لیست مجاز کانال‌های واتس‌اپ متصل می‌شود.

۴. ایجاد حساب کاربری اختصاصی برای سرویس

برای پایبندی به اصل حداقل امتیاز، یک حساب کاربری سرویس IAM اختصاصی برای OpenClaw ایجاد کنید:

export SERVICE_ACCOUNT_NAME="openclaw-sa"
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \
  --display-name="OpenClaw Service Account"

export SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

۵. ذخیره اطلاعات کاربری در Secret Manager

ما اعتبارنامه‌های حساس API را در Google Cloud Secret Manager ذخیره خواهیم کرد تا Cloud Run بتواند آنها را به طور ایمن در زمان بوت به کانتینر تزریق کند.

۱. دریافت و ذخیره کلید API جمینی

  1. به Google AI Studio مراجعه کنید و با حساب گوگل خود وارد شوید.
  2. روی ایجاد کلید API کلیک کنید و پروژه Google Cloud خود ( ${PROJECT_ID} ) را انتخاب کنید.
  3. کلید API تولید شده را کپی کنید.

کلید API را در Secret Manager ذخیره کنید و به حساب کاربری سرویس دسترسی بدهید:

echo -n "YOUR_GEMINI_API_KEY" | gcloud secrets create gemini-api-key \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding gemini-api-key \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

۲. ایجاد و ذخیره رمز عبور دروازه

برای محافظت از نمونه OpenClaw که در دسترس عموم است، یک رمز عبور تصادفی ایمن ایجاد کنید و آن را در Secret Manager ذخیره کنید:

export OPENCLAW_GATEWAY_PASSWORD=$(openssl rand -hex 16)
echo "Generated Gateway Password: ${OPENCLAW_GATEWAY_PASSWORD}"

echo -n "${OPENCLAW_GATEWAY_PASSWORD}" | gcloud secrets create openclaw-gateway-password \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding openclaw-gateway-password \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

۳. (اختیاری) ایجاد کانال مخفی (تلگرام یا واتس‌اپ)

  • برای تلگرام : 
    echo -n "YOUR_TELEGRAM_BOT_TOKEN" | gcloud secrets create telegram-bot-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding telegram-bot-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"
  • برای واتس‌اپ : 
    echo -n "YOUR_WHATSAPP_TOKEN_OR_KEY" | gcloud secrets create whatsapp-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding whatsapp-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

۶. آماده‌سازی مخزن ذخیره‌سازی ابری و پیکربندی openclaw.json

OpenClaw به یک فایل پیکربندی با نام openclaw.json در /home/node/.openclaw/openclaw.json نیاز دارد.

  1. ایجاد یک فضای ذخیره‌سازی ابری و اعطای دسترسی : 
    export BUCKET_NAME="openclaw-state-${PROJECT_ID}"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/storage.objectUser"
  2. ایجاد openclaw.json : فایلی با نام openclaw.json در Cloud Shell ایجاد کنید. بخش channels را به‌روزرسانی کنید تا با کانال انتخابی شما (تلگرام یا واتس‌اپ) مطابقت داشته باشد: 
    {
  "gateway": {
    "mode": "local",
    "port": 18789,
    "trustedProxies": ["0.0.0.0/0"],
    "bind": "lan",
    "auth": {
      "password": "${OPENCLAW_GATEWAY_PASSWORD}"
    },
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true,
      "allowedOrigins": ["*"],
      "enabled": true
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3.1-pro-preview"
      },
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": true,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "YOUR_TELEGRAM_USER_ID"
          ]
        }
      }
    },
    "whatsapp": {
      "enabled": false,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": false,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "+15551234567"
          ]
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "google": { "enabled": true },
      "telegram": { "enabled": true },
      "whatsapp": { "enabled": false }
    }
  }
}
  3. openclaw.json را در Cloud Storage Bucket Root آپلود کنید :
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    طرح‌بندی سطل ذخیره‌سازی ابری را تأیید کنید : تأیید کنید که ساختار سطل شما شامل openclaw.json در ریشه باشد: 
    gs://${BUCKET_NAME}/
└── openclaw.json

۷. OpenClaw را روی نمونه‌های Cloud Run مستقر کنید

OpenClaw را با استفاده gcloud beta run instances deploy کنید: 

gcloud beta run instances deploy openclaw-instance \
  --image ghcr.io/openclaw/openclaw:2026.7.1 \
  --service-account ${SERVICE_ACCOUNT} \
  --port 18789 \
  --cpu 4 \
  --memory 4Gi \
  --public \
  --add-volume mount-path=/home/node/.openclaw,type=cloud-storage,mount-options="uid=1000;gid=1000;file-mode=0700;dir-mode=0700",bucket=${BUCKET_NAME} \
  --set-secrets GEMINI_API_KEY=gemini-api-key:latest,OPENCLAW_GATEWAY_PASSWORD=openclaw-gateway-password:latest \
  --region ${REGION}

تجزیه پارامترهای کلیدی:

  • --image ghcr.io/openclaw/openclaw:2026.7.1 : تصویر کانتینر OpenClaw (پین شده به 2026.7.1 ، آخرین نسخه پایدار 1.x).
  • --service-account ... : حساب سرویس اختصاصی openclaw-sa را ضمیمه می‌کند.
  • --add-volume ... : مخزن ذخیره‌سازی ابری را مستقیماً در /home/node/.openclaw نصب می‌کند. استفاده از file-mode=0700;dir-mode=0700 مجوزهای مناسب را برای OpenClaw تضمین می‌کند.
  • --set-secrets ... : اعتبارنامه‌ها را مستقیماً از Secret Manager به متغیرهای محیطی تزریق می‌کند. (اختیاری: اگر تلگرام را در مراحل اختیاری پیکربندی کرده‌اید، ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest به --set-secrets اضافه کنید .)
  • --public : دسترسی عمومی به URL را امکان‌پذیر می‌کند.

۸. مستقیماً از طریق رابط کاربری وب OpenClaw تعامل داشته باشید

OpenClaw شامل یک رابط کاربری وب داخلی است که به شما امکان می‌دهد مستقیماً از مرورگر خود، عامل هوش مصنوعی خود را مدیریت و با آن چت کنید:

  1. آدرس اینترنتی نمونه Cloud Run خود را بازیابی کنید : در Cloud Shell، دستور زیر را اجرا کنید: 
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. دسترسی به رابط کاربری کنترل OpenClaw :
    • آدرس خروجی (URL) را در مرورگر وب خود باز کنید.
    • وقتی در رابط کاربری OpenClaw Control از شما درخواست احراز هویت شد:
      • رمز عبور دروازه تولید شده ( ${OPENCLAW_GATEWAY_PASSWORD} ) را از Secret Manager وارد کنید.
      • اگر پنجره ورود، فیلدهای نام کاربری و رمز عبور را جداگانه نمایش می‌دهد، فیلد نام کاربری را خالی بگذارید (یا admin را وارد کنید) و در فیلد رمز عبور، ${OPENCLAW_GATEWAY_PASSWORD} را وارد کنید.
  3. به نماینده خود اطلاع دهید (موارد در عمل) :
    • پس از احراز هویت، داشبورد کنترل OpenClaw را مشاهده خواهید کرد.
    • با ارسال یک پیام در رابط کاربری چت، مانند «سلام»، عامل OpenClaw خود را آزمایش کنید.
    • برای آزمایش چرخه عمر طولانی نمونه Cloud Run، می‌توانید از عامل OpenClaw خود بخواهید که یک کار پیچیده‌تر و طولانی‌تر را انجام دهد. برای مثال، می‌توانید از آن بخواهید که یک فید خبری یا بازار سهام را ردیابی کرده و گزارش‌هایی تولید کند: 
      Track the USD-to-EUR exchange rate every 15 minutes for the next 24 hours, while also checking for any recent news updates in the US or the EU that may have an impact on the exchange rate. Generate an end-of-day report for me in this chat that tells me what you expect tomorrow's exchange rate will be.
    • سپس عامل باید این وظیفه را طی ۲۴ ساعت آینده انجام دهد.

۹. (اختیاری) تأیید ادغام کانال‌های پیام‌رسانی

اگر تلگرام یا واتس‌اپ را در مراحل تنظیمات اختیاری بالا پیکربندی کرده‌اید، می‌توانید دریافت پیام را تأیید کنید:

  1. بررسی لاگ‌های نمونه در Cloud Shell: 
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. تلگرام (یا واتس‌اپ) را باز کنید و یک پیام ارسال کنید (مثلاً /start یا Hello OpenClaw! ‎).
  3. ربات، شناسه کاربری شما را با استفاده از لیست مجوزهای موجود در openclaw.json احراز هویت می‌کند و با استفاده از Gemini پاسخ می‌دهد!

۱۰. نظارت و بررسی لاگ‌های نمونه

Cloud Run Instances خروجی استاندارد (stdout) و خروجی استاندارد (stderr) را از کانتینر شما ضبط کرده و مستقیماً به Google Cloud Logging ارسال می‌کند. می‌توانید از Cloud Shell یا Cloud Console برای نظارت بر ترافیک دروازه و بررسی اجراهای ابزار عامل به صورت بلادرنگ استفاده کنید.

۱. خواندن گزارش‌های اخیر نمونه‌ها

برای دریافت ورودی‌های اخیر لاگ از نمونه در Cloud Shell: 

gcloud beta run instances logs read openclaw-instance \
  --region ${REGION} \
  --limit 50

۲. امضاهای لاگ کلید برای مشاهده

هنگام مشاهده‌ی عامل در حال اجرا، به دنبال رویدادهای کلیدی لاگ زمان اجرا زیر باشید:

  • [gateway] ready : تأیید می‌کند که دروازه OpenClaw HTTP و WebSocket راه‌اندازی شده و روی پورت ۱۸۷۸۹ در حال گوش دادن است.
  • [gateway] agent model: ... : مدل فعال Gemini (مثلاً google/gemini-3.1-pro-preview یا google/gemini-3.5-flash ) را نمایش می‌دهد.
  • [agents/tool-policy] ‎: ابزارهای مجاز یا محدود شده تحت سیاست شما را نشان می‌دهد.
  • [agent/embedded] ‎: اجرا و فراخوانی ابزار توسط عامل را ردیابی می‌کند.

۳. بررسی لاگ‌ها در کنسول ابری گوگل

همچنین می‌توانید با استفاده از Logs Explorer در Cloud Console، لاگ‌ها را مشاهده و فیلتر کنید: 

resource.type="cloud_run_instance"
resource.labels.instance_name="openclaw-instance"

۱۱. (اختیاری) نماینده خود را با مهارت‌هایش گسترش دهید

OpenClaw از بسته‌های ماژولار Skills پشتیبانی می‌کند که گردش‌های کاری خاص، ابزارهای تخصصی CLI و دستورالعمل‌های خاص دامنه را به اپراتور شما آموزش می‌دهند.

مهارت‌ها چگونه کار می‌کنند؟

هر مهارت، یک دایرکتوری حاوی یک فایل SKILL.md است. این فایل با YAML frontmatter که متادیتا ( name و description ) را مشخص می‌کند، شروع می‌شود و به دنبال آن دستورالعمل‌های Markdown قرار می‌گیرد: 

---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs:
1. Parse error stack traces and group similar errors by frequency.
2. Identify root causes such as memory limits, timeouts, or permission errors.
3. Propose concrete remediation steps.
  • name : شناسه مهارت (همچنین مستقیماً به عنوان یک دستور اسلش قابل فراخوانی است، برای مثال /summarize-logs ).
  • description : به مدل OpenClaw می‌گوید چه زمانی به طور خودکار این مهارت را در مکالمه طبیعی فراخوانی کند.

یک مهارت سفارشی به فضای ذخیره‌سازی ابری خود اضافه کنید

از آنجا که سطل ذخیره‌سازی ابری شما مستقیماً در /home/node/.openclaw نصب شده است، مهارت‌هایی که در مسیر gs://${BUCKET_NAME}/skills/ قرار دارند، به‌طور خودکار هنگام بوت بارگذاری می‌شوند و در طول راه‌اندازی مجدد نمونه‌ها همچنان پابرجا می‌مانند:

  1. ایجاد یک فهرست مهارت‌های محلی : 
    mkdir -p my-skill
cat << 'EOF' > my-skill/SKILL.md
---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs, group errors by frequency and suggest actionable fixes.
EOF
  2. مهارت را در فضای ذخیره‌سازی ابری بارگذاری کنید : 
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. از مهارت در چت استفاده کنید :
    • به رابط کاربری وب OpenClaw Control برگردید.
    • اکنون می‌توانید با استفاده از /summarize-logs یا پرسیدن سوالات به زبان طبیعی که با شرح مهارت مطابقت دارند، نماینده خود را مطلع کنید!

۱۲. تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع مورد استفاده در این آزمایشگاه کد:

  1. نمونه Cloud Run را حذف کنید : 
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. حذف اسرار مدیر مخفی : 
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. حذف سطل ذخیره‌سازی ابری : 
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. حذف حساب کاربری سرویس اختصاصی : 
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

۱۳. نتیجه‌گیری

تبریک! شما با موفقیت یک نمونه امن و کاملاً پایدار از OpenClaw را روی Cloud Run Instances که توسط Cloud Storage، Secret Manager و کانال پیام‌رسانی دلخواه شما پشتیبانی می‌شود، مستقر کردید!