Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Cloud Run 인스턴스에 OpenClaw를 배포하는 방법

1. 소개

개요

이 실습에서는 오픈소스 AI 에이전트 프레임워크인 OpenClaw의 완전 영구적이고 안전한 인스턴스를 Cloud Run 인스턴스에 배포합니다. OpenClaw의 내장 웹 UI (Telegram 또는 WhatsApp과 같은 메시지 채널을 연결하는 옵션 포함)을 사용하여 AI 에이전트와 직접 상호작용하고, Google Cloud Storage로 홈 작업공간을 지원하고, Google Cloud Secret Manager를 사용하여 API 사용자 인증 정보를 안전하게 관리합니다.

시작하기 전에 OpenClaw 문서를 살펴보고 OpenClaw의 아키텍처, 도구, 에이전트 워크플로를 숙지할 수 있습니다.

실습할 내용

필요한 Google Cloud API를 사용 설정하고 필요한 IAM 권한이 있는 전용 서비스 계정을 만듭니다.
Secret Manager에 API 키와 게이트웨이 비밀번호를 안전하게 저장합니다.
Gemini 모델 설정과 게이트웨이 UI가 사용 설정된 openclaw.json 구성 파일을 준비합니다.
컨테이너 상태를 유지할 Cloud Storage 버킷을 준비합니다.
gcloud beta run instances deploy를 사용하여 OpenClaw를 배포합니다.
내장 웹 UI를 사용하여 OpenClaw AI 에이전트와 직접 상호작용하세요.
(선택사항) 메시지 채널 (Telegram 또는 WhatsApp)을 구성합니다.
(선택사항) Cloud Storage에 맞춤 기술을 추가하여 에이전트의 기능을 확장합니다.

학습할 내용

기본 제공 제어 웹 UI를 사용하여 OpenClaw를 Cloud Run 인스턴스에 배포하는 방법
Cloud Storage 버킷을 Cloud Run 인스턴스에 마운트하는 방법
Secret Manager 보안 비밀을 환경 변수로 Cloud Run에 안전하게 삽입하는 방법
Cloud Run 인스턴스에서 장기 실행되는 영구 에이전트 워크로드를 실행하는 방법
커스텀 에이전트 스킬을 구성하고 Cloud Storage에 업로드하는 방법

2. 설정 및 요구사항

GCP 프로젝트 설정

Google Cloud 콘솔에 로그인합니다.
Google Cloud 프로젝트를 만들거나 선택합니다.
Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Shell 열기

Cloud 콘솔의 상단 툴바에서 Google Cloud Shell을 활성화합니다.

프로젝트 설정 및 gcloud 베타 설치

먼저 프로젝트와 리전을 환경 변수로 설정합니다.

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

이제 프로젝트를 설정하고 확인합니다.

gcloud config set project $PROJECT_ID
gcloud config get project

gcloud beta run instances에 beta 구성요소가 설치되어 있는지 확인합니다.

gcloud components install beta --quiet

gcloud가 최신 상태인지 확인합니다.

gcloud components update

필수 Google Cloud API 사용 설정

Cloud Shell에서 Cloud Run, Secret Manager, Cloud Storage, Gemini API를 사용 설정합니다.

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

3. (선택사항) 메시지 통합 설정 (Telegram 또는 WhatsApp)

OpenClaw를 Telegram 또는 WhatsApp에 연결할 수 있습니다. 아래에서 옵션 A 또는 옵션 B를 선택하세요.

옵션 A: Telegram 봇 설정

Telegram을 열고 @BotFather을 검색합니다.
/newbot 명령어를 보내고 메시지에 따라 봇 이름과 사용자 이름을 지정합니다.
생성된 HTTP API 토큰 (예: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ)을 복사합니다.
Telegram에서 @userinfobot를 검색하고 /start를 전송한 후 숫자 사용자 ID (예: 8035936176)를 복사합니다.

옵션 B: WhatsApp 설정

공백이나 기호 (예: +15551234567) 없이 국가 코드 포함 형식으로 개인 WhatsApp 전화번호를 가져옵니다.
OpenClaw는 WhatsApp 채널 허용 목록 정책을 통해 연결됩니다.

4. 전용 서비스 계정 만들기

최소 권한의 원칙을 준수하려면 OpenClaw용 전용 IAM 서비스 계정을 만드세요.

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"

5. Secret Manager에 사용자 인증 정보 저장

Cloud Run이 부팅 시 컨테이너에 안전하게 삽입할 수 있도록 민감한 API 사용자 인증 정보를 Google Cloud Secret Manager에 저장합니다.

1. Gemini API 키 획득 및 저장

Google AI Studio로 이동하여 Google 계정으로 로그인합니다.
API 키 만들기를 클릭하고 Google Cloud 프로젝트 (${PROJECT_ID})를 선택합니다.
생성된 API 키를 복사합니다.

Secret Manager에 API 키를 저장하고 서비스 계정 액세스 권한을 부여합니다.

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"

2. 게이트웨이 비밀번호 생성 및 저장

공개적으로 액세스할 수 있는 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"

3. (선택사항) 채널 보안 비밀 만들기 (Telegram 또는 WhatsApp)

Telegram의 경우:

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"

WhatsApp의 경우:

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"

6. Cloud Storage 버킷 및 openclaw.json 구성 준비

OpenClaw에는 /home/node/.openclaw/openclaw.json에 openclaw.json이라는 구성 파일이 필요합니다.

Cloud Storage 버킷 만들기 및 액세스 권한 부여:

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"

openclaw.json 만들기: Cloud Shell에서 openclaw.json라는 파일을 만듭니다. 선택한 채널 (Telegram 또는 WhatsApp)에 맞게 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 }
    }
  }
}

openclaw.json을 Cloud Storage 버킷 루트에 업로드합니다.
```
gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
```
Cloud Storage 버킷 레이아웃 확인: 버킷 구조의 루트에 openclaw.json가 포함되어 있는지 확인합니다.
```
gs://${BUCKET_NAME}/
└── openclaw.json
```

7. Cloud Run 인스턴스에 OpenClaw 배포

gcloud beta run instances deploy을 사용하여 OpenClaw를 배포합니다.

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 ...: Cloud Storage 버킷을 /home/node/.openclaw에 직접 마운트합니다. file-mode=0700;dir-mode=0700를 사용하면 OpenClaw에 적절한 권한이 부여됩니다.
--set-secrets ...: Secret Manager에서 환경 변수로 사용자 인증 정보를 직접 삽입합니다. (선택사항: 선택사항 단계에서 Telegram을 구성한 경우 --set-secrets에 ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest를 추가하세요.)
--public: URL에 대한 공개 액세스를 허용합니다.

8. OpenClaw 웹 UI를 통해 직접 상호작용

OpenClaw에는 브라우저에서 직접 AI 에이전트를 관리하고 채팅할 수 있는 기본 제공 제어 웹 UI가 포함되어 있습니다.

Cloud Run 인스턴스 URL 가져오기: Cloud Shell에서 다음을 실행합니다.

gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"

OpenClaw Control UI에 액세스:
- 웹브라우저에서 출력 URL을 엽니다.
- OpenClaw Control UI에서 인증을 요청하는 경우:
  - Secret Manager에서 생성된 게이트웨이 비밀번호 (${OPENCLAW_GATEWAY_PASSWORD})를 입력합니다.
  - 로그인 모달에 별도의 사용자 이름 및 비밀번호 필드가 표시되면 사용자 이름 필드를 비워 두거나 admin를 입력하고 비밀번호 필드에 ${OPENCLAW_GATEWAY_PASSWORD}를 입력합니다.
상담사 프롬프트 (실제 사용 사례):
- 인증이 완료되면 OpenClaw Control Dashboard가 표시됩니다.
- 채팅 UI에서 'Hello'와 같은 프롬프트를 보내 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.
```
- 그런 다음 상담사는 24시간 이내에 이 작업을 수행해야 합니다.

9. (선택사항) 메시지 채널 통합 확인

위의 선택적 설정 단계에서 Telegram 또는 WhatsApp을 구성한 경우 메시지 전송을 확인할 수 있습니다.

Cloud Shell에서 인스턴스 로그를 확인합니다.

gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20

Telegram (또는 WhatsApp)을 열고 메시지 (예: /start 또는 Hello OpenClaw!)를 보냅니다.
봇이 openclaw.json의 허용 목록에 대해 사용자 ID를 인증하고 Gemini를 사용하여 응답합니다.

10. 인스턴스 로그 모니터링 및 검사

Cloud Run 인스턴스는 컨테이너의 stdout 및 stderr을 캡처하여 Google Cloud Logging으로 직접 스트리밍합니다. Cloud Shell 또는 Cloud 콘솔을 사용하여 게이트웨이 트래픽을 모니터링하고 에이전트 도구 실행을 실시간으로 검사할 수 있습니다.

1. 최근 인스턴스 로그 읽기

Cloud Shell에서 인스턴스의 최근 로그 항목을 가져오려면 다음을 실행하세요.

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

2. 관찰할 주요 로그 서명

실행 중인 에이전트를 관찰할 때는 다음 주요 런타임 로그 이벤트를 확인하세요.

[gateway] ready: OpenClaw HTTP 및 WebSocket 게이트웨이가 초기화되었으며 포트 18789에서 리슨하고 있는지 확인합니다.
[gateway] agent model: ...: 활성 Gemini 모델 (예: google/gemini-3.1-pro-preview 또는 google/gemini-3.5-flash)을 표시합니다.
[agents/tool-policy]: 정책에 따라 허용되거나 제한된 도구를 표시합니다.
[agent/embedded]: 에이전트의 실행 및 도구 호출을 추적합니다.

3. Google Cloud 콘솔에서 로그 검사

Cloud 콘솔의 로그 탐색기를 사용하여 로그를 보고 필터링할 수도 있습니다.

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

11. (선택사항) 스킬로 에이전트 확장

OpenClaw는 에이전트에게 특정 워크플로, 전문 CLI 도구, 도메인별 안내를 가르치는 모듈식 기능 패키지인 스킬을 지원합니다.

스킬 작동 방식

모든 스킬은 SKILL.md 파일이 포함된 디렉터리입니다. 메타데이터 (name 및 description)를 지정하는 YAML 프런트매터로 시작하고 그 뒤에 마크다운 요청 사항이 이어집니다.

---
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의 모델에 알려줍니다.

Cloud Storage 버킷에 맞춤 기술 추가

Cloud Storage 버킷이 /home/node/.openclaw에 직접 마운트되므로 gs://${BUCKET_NAME}/skills/ 아래에 배치된 스킬은 부팅 시 자동으로 로드되고 인스턴스 재시작 시 유지됩니다.

로컬 스킬 디렉터리 만들기:

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

Cloud Storage에 스킬 업로드:

gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/

Chat에서 스킬 사용하기:
- OpenClaw Control 웹 UI로 돌아갑니다.
- 이제 /summarize-logs를 사용하여 에이전트에게 프롬프트를 표시하거나 스킬 설명과 일치하는 자연어 질문을 할 수 있습니다.

12. 삭제

이 Codelab에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 안내를 따르세요.

Cloud Run 인스턴스 삭제:

gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet

Secret Manager 보안 비밀 삭제:

gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet

Cloud Storage 버킷 삭제:

gcloud storage rm -r gs://${BUCKET_NAME}

전용 서비스 계정 삭제:

gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. 결론

수고하셨습니다 Cloud Storage, Secret Manager, 원하는 메시지 채널로 지원되는 Cloud Run 인스턴스에 보안이 유지되고 완전히 영구적인 OpenClaw 인스턴스를 배포했습니다.