GCP

تثبيت gcloud CLI (أو استخدام وحدة التحكم)

الخيار أ: gcloud CLI (موصى به للأتمتة)

ثبّت من https://cloud.google.com/sdk/docs/install

هيّئ وسجّل الدخول:

gcloud init
gcloud auth login

الخيار ب: Cloud Console

يمكن تنفيذ جميع الخطوات عبر واجهة الويب في https://console.cloud.google.com

إنشاء مشروع GCP

CLI:

gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
gcloud config set project my-openclaw-project

فعّل الفوترة في https://console.cloud.google.com/billing (مطلوبة لـ Compute Engine).

فعّل Compute Engine API:

gcloud services enable compute.googleapis.com

وحدة التحكم:

1. انتقل إلى IAM والمسؤول > إنشاء مشروع
2. سمّه وأنشئه
3. فعّل الفوترة للمشروع
4. انتقل إلى واجهات API والخدمات > تفعيل واجهات API > ابحث عن "Compute Engine API" > تفعيل

إنشاء VM

أنواع الأجهزة:

CLI:

gcloud compute instances create openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=20GB \
  --image-family=debian-12 \
  --image-project=debian-cloud

وحدة التحكم:

1. انتقل إلى Compute Engine > مثيلات VM > إنشاء مثيل
2. الاسم: openclaw-gateway
3. المنطقة: us-central1، النطاق: us-central1-a
4. نوع الجهاز: e2-small
5. قرص الإقلاع: Debian 12، 20GB
6. أنشئ

الدخول إلى VM عبر SSH

CLI:

gcloud compute ssh openclaw-gateway --zone=us-central1-a

وحدة التحكم:

انقر زر "SSH" بجوار VM الخاصة بك في لوحة معلومات Compute Engine.

ملاحظة: قد يستغرق نشر مفتاح SSH مدة 1-2 دقيقة بعد إنشاء VM. إذا رُفض الاتصال، انتظر ثم أعد المحاولة.

تثبيت Docker (على VM)

sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

سجّل الخروج ثم ادخل مجددًا لتطبيق تغيير المجموعة:

exit

ثم ادخل مرة أخرى عبر SSH:

gcloud compute ssh openclaw-gateway --zone=us-central1-a

تحقق:

docker --version
docker compose version

استنساخ مستودع OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw

يفترض هذا الدليل أنك ستبني صورة مخصصة لضمان استمرارية الثنائيات.

إنشاء أدلة مضيف دائمة

حاويات Docker مؤقتة. يجب أن تكون كل الحالة طويلة العمر على المضيف.

mkdir -p ~/.openclaw
mkdir -p ~/.openclaw/workspace

ضبط متغيرات البيئة

أنشئ .env في جذر المستودع.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

عيّن OPENCLAW_GATEWAY_TOKEN عندما تريد إدارة رمز Gateway المميز المستقر من خلال .env؛ وإلا فاضبط gateway.auth.token قبل الاعتماد على العملاء عبر عمليات إعادة التشغيل. إذا لم يكن أي من المصدرين موجودًا، يستخدم OpenClaw رمزًا مميزًا مخصصًا لوقت التشغيل فقط لذلك التشغيل. أنشئ كلمة مرور لسلسلة المفاتيح والصقها في GOG_KEYRING_PASSWORD:

openssl rand -hex 32

لا تودع هذا الملف في Git.

ملف .env هذا مخصص لبيئة الحاوية/وقت التشغيل مثل OPENCLAW_GATEWAY_TOKEN. توجد مصادقة مزود OAuth/مفاتيح API المخزنة في المسار المثبت ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

تكوين Docker Compose

أنشئ أو حدّث docker-compose.yml.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      # Recommended: keep the Gateway loopback-only on the VM; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]

--allow-unconfigured مخصص فقط لتسهيل التمهيد، وليس بديلًا عن تكوين Gateway صحيح. مع ذلك، اضبط المصادقة (gateway.auth.token أو كلمة مرور) واستخدم إعدادات ربط آمنة لنشرك.

خطوات وقت تشغيل Docker VM المشتركة

استخدم دليل وقت التشغيل المشترك لتدفق مضيف Docker العام:

• تضمين الثنائيات المطلوبة في الصورة
• البناء والتشغيل
• ما الذي يستمر وأين
• التحديثات

ملاحظات تشغيل خاصة بـ GCP

على GCP، إذا فشل البناء مع Killed أو exit code 137 أثناء pnpm install --frozen-lockfile، فهذا يعني أن ذاكرة VM نفدت. استخدم e2-small كحد أدنى، أو e2-medium لعمليات بناء أولى أكثر موثوقية.

عند الربط بالشبكة المحلية (LAN) (OPENCLAW_GATEWAY_BIND=lan)، اضبط أصل متصفح موثوقًا قبل المتابعة:

docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json

إذا غيّرت منفذ Gateway، فاستبدل 18789 بالمنفذ الذي ضبطته.

الوصول من حاسوبك المحمول

أنشئ نفق SSH لتمرير منفذ Gateway:

gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789

افتح في متصفحك:

http://127.0.0.1:18789/

أعد طباعة رابط نظيف للوحة المعلومات:

docker compose run --rm openclaw-cli dashboard --no-open

إذا طالبت واجهة المستخدم بمصادقة سر مشترك، فالصق الرمز المميز أو كلمة المرور المضبوطة في إعدادات واجهة التحكم. يكتب مسار Docker هذا رمزًا مميزًا افتراضيًا؛ إذا بدّلت تكوين الحاوية إلى مصادقة بكلمة مرور، فاستخدم تلك الكلمة بدلًا من ذلك.

إذا عرضت واجهة التحكم unauthorized أو disconnected (1008): pairing required، فوافق على جهاز المتصفح:

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

هل تحتاج مرة أخرى إلى مرجع الاستمرارية والتحديثات المشترك؟ راجع وقت تشغيل Docker VM وتحديثات وقت تشغيل Docker VM.