Deployments

A deployment is an isolated OpenClaw gateway instance managed by ClusterClaw. This guide covers creation, lifecycle, networking, channels, inference, and runtime operations.

Deployment object

Each deployment exposes a protobuf Deployment message with:

Section	Fields
Identity	id, customer_id, name, status, plan
placement	cloud, region, target_class, network_cell, …
runtime	image_tag, size_class, channel_tier, model_credentials_mode
network	hostname, ingress_enabled
storage	pvc_size
provider_config	inference_mode, provider_name, endpoint_url
skills	Seeded skill bundles
Timestamps	created_at, updated_at

Creating a deployment

Required fields

• name — DNS-safe label; used in hostnames and resource naming

Common optional fields

Field	Default	Description
region	us-central1	GCP region
plan	Customer tier	Plan label stored on deployment
size_class	small	Compute profile (product currently standardizes on small)
channel_tier	bot-first	Channel capability tier
pvc_size	20Gi	Persistent storage
inference_mode	Platform-managed	See inference modes below
target_class	cloud_run	cloud_run or autopilot (enterprise only)
public_ingress_enabled	false	Expose HTTPS gateway
public_hostname	<name>.clusterclaw.ai	When ingress enabled
model_primary	Catalog default	Primary model ID (e.g. openai/gpt-5.4-mini)
auto_update / auto_update_channel	Chart defaults	Gateway auto-update settings
seed_overrides_json	—	Deep-merge JSON into seeded openclaw.json (max 64 KiB)
provider_api_key	—	Required for BYOK; never stored in DB or echoed back
skills	—	Inline or git-backed skill bundles

Inference modes

Enum	CLI flag	Description
INFERENCE_MODE_PLATFORM_MANAGED	platform-managed	Models via https://proxy.clusterclaw.ai; token usage metered
INFERENCE_MODE_BYOK	byok	Your provider key in Infisical; no ClusterClaw token charges
INFERENCE_MODE_SELF_HOSTED	self-hosted	Your Ollama/vLLM URL in provider_endpoint_url
INFERENCE_MODE_EXTERNAL_HOSTED	external-hosted	Third-party hosted endpoint

Target classes

Value	Description
cloud_run	Default — managed Cloud Run service per deployment, scales efficiently
autopilot	GKE Autopilot namespace — enterprise tier only

Aliases accepted by the API: cloudrun, cloud-run, gke, gke-autopilot.

Lifecycle and status

queued → provisioning → provisioning_service → dns_pending → tls_pending → healthy
                                    ↘ failed
healthy ↔ degraded / backup-warning
any → suspended (operator)
any → deleting

Status	Customer-visible meaning
QUEUED	Job accepted; waiting for worker
PROVISIONING	Resources being allocated
PROVISIONING_SERVICE	Cloud Run / GKE service coming online
DNS_PENDING	Public DNS record propagating
TLS_PENDING	Certificate issuance
HEALTHY	Gateway ready
DEGRADED	Running with issues — check logs/status message
BACKUP_WARNING	Storage backup attention needed
SUSPENDED	Stopped by policy or billing
FAILED	Provision error — see logs
DELETING	Teardown in progress

RPC operations

RPC	Effect
CreateDeployment	Provision new gateway
GetDeployment	Read deployment record
ListDeployments	Paginated list (page_size, page_token)
UpdateDeployment	Change plan, size, inference, hostname, image; refresh_runtime_image rolls platform image
StopDeployment	Stop runtime
StartDeployment	Start stopped runtime
RestartDeployment	Rolling restart
DeleteDeployment	Tear down resources
GetDeploymentStatus	Health + per-channel status
GetDeploymentLogs	Recent log lines (limit)
GetDeploymentGatewayCredentials	One-time gateway URL + SSO token

Public hostnames

When public_ingress_enabled is true:

Input	Result
Blank hostname	<name>.clusterclaw.ai
Bare label mybot	mybot.clusterclaw.ai
FQDN under *.clusterclaw.ai	Used as-is (wildcard cert)
BYO FQDN	Kept as-is; you must CNAME to gateway.clusterclaw.ai for HTTP-01 cert

When ingress is disabled, network.hostname reflects the internal routing hostname (not customer-facing).

Gateway SSO

From the dashboard Open gateway button or GetDeploymentGatewayCredentials:

• Requires public ingress enabled and status HEALTHY
• Returns gateway_url (HTTPS) and gateway_token (ccgw_*)
• Token is sensitive — use immediately; do not log

Chat channels

Fetch the launch catalog for supported channels and guided field schemas:

curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.CatalogService/GetLaunchCatalog' \
  -H 'Content-Type: application/json' -d '{}'

Tier 1 — guided setup

Channel	Setup	Notes
Discord	Bot token	Developer Portal bot token
Telegram	Bot token	From @BotFather
Slack	Bot + App token	Socket Mode recommended on hosted

Tier 2 — advanced config

WhatsApp, Signal, Matrix, Google Chat, iMessage, Mattermost, Microsoft Teams — configure via Advanced config (seed_overrides_json / YAML under channels.*). See OpenClaw channel docs.

Channel secrets are injected at provision time and are not returned by the API.

Connect Slack

Hosted deployments use Socket Mode (no public webhook URL required).

1. In api.slack.com/apps, create or open your Slack app.
2. Enable Socket Mode and create an App Token (xapp-...) with connections:write.
3. Install the app to your workspace and copy the Bot Token (xoxb-...).
4. Subscribe to bot events (app_mention, message.channels, message.im, etc.) — see OpenClaw Slack docs.
5. Paste both tokens in the deployment form (dashboard) or catalog field keys in the API.
6. Deploy and wait for HEALTHY.

After the gateway is healthy, approve DM pairing with openclaw pairing approve slack <code> when using the default pairing policy.

For HTTP Events API mode or multi-account setups, use Advanced config (channels.slack in YAML/JSON) instead of the guided fields.

Skills

Attach skill bundles at create time:

• Inline — skill_md, agents map, references map
• Git — git_url clones into ~/.openclaw/skills/<name>/ at init (git wins over inline)

Skills are materialized as ConfigMaps and copied into the deployment volume at first boot.

Connected integrations

Beyond chat channels, IntegrationService connects OAuth and credential-based apps to a deployment:

Provider	Auth type
Google Workspace	OAuth2
Microsoft 365	OAuth2
GitHub	OAuth2
Vercel	OAuth2
Stripe	OAuth2
Adobe Creative Cloud	OAuth2 (scaffolded)
iCloud	App-specific password

Use ListIntegrationProviders, StartIntegrationOAuth, or ConnectIntegrationWithCredentials. Credentials are stored securely and never echoed in API responses. Some providers require operator-side OAuth client configuration — configured: false in the catalog means connect flows return failed_precondition until enabled.

Logs and debugging

GetDeploymentLogs returns structured lines:

{
  "lines": [
    {"timestamp": "...", "source": "gateway", "message": "..."}
  ]
}

GetDeploymentStatus includes a human message and channels[] with per-channel status.

CLI quick reference

claw deploy create --name prod --region us-central1
claw deploy list
claw deploy get <id>
claw deploy status <id>
claw deploy delete <id>
claw enterprise status <id>   # enterprise lane summary

Platform image updates

Two update paths exist:

Mechanism	What it updates
In-gateway "Update now"	npm bundle inside the running container
UpdateDeployment with refresh_runtime_image: true	Cloud Run service to current Artifact Registry digest

Customer documentation for runtime versioning follows tagged releases on the gateway image.

Related guides

• Getting started
• Authentication — runtime tokens vs API keys
• Session management — list, abort, and maintain gateway sessions
• Billing — compute and token metering
• API reference