openclaw-dev

name	openclaw-dev
description	Deploy, operate, and troubleshoot the openclaw-dev template: a secure, hosted OpenClaw AI assistant on Azure (Azure Container Apps + Azure OpenAI in Foundry Models, passwordless via Managed Identity, Entra ID Easy Auth, ephemeral sandbox execution, optional Microsoft Teams channel) using the repo's `devclaw` wrapper around the Azure Developer CLI (azd). USE FOR: deploy openclaw-dev / OpenClaw to Azure in one prompt, "devclaw up" / "azd up" failing, set the model or region, switch tool execution to ephemeral sandboxes (EXECUTION_MODE=sandbox / devclaw exec-mode), clone another sandbox, connect OpenClaw to Microsoft Teams / use it from a phone, stop to save cost, start/restart, stream logs, verify the deployment, configure Entra ID sign-in, restrict access to specific users, tear everything down (nuke & pave). DO NOT USE FOR: editing OpenClaw's own source on npm, general Azure resource creation unrelated to this template, non-Azure hosting.
license	MIT

OpenClaw on Azure — setup & operations playbook

This skill lets an AI assistant set up, run, and fix the openclaw-dev template in plain English. It deploys OpenClaw as a secure, always-on AI assistant on Azure Container Apps, wired to Azure OpenAI in Foundry Models over a Managed Identity (no API keys), gated by Entra ID Easy Auth, and optionally reachable from Microsoft Teams on the user's phone.

Use this repo's own scripts, env-var contract, region list, and error catalog instead of guessing. Always confirm with the user before any destructive action (devclaw down, azd down, deleting app registrations, RBAC removal).

Alpha / dev-test template, single-tenant. Today it targets Azure OpenAI in Foundry Models (default gpt-5.4-mini), with scope to add Claude and other Foundry Models later. Do not promise non-OpenAI models work today.

---

The one thing to know

Everything is driven by the devclaw wrapper (a thin shell around azd):

./devclaw up        # macOS/Linux/WSL  — provision + build + deploy (~6 min first run)
.\devclaw.cmd up    # Windows (cmd or PowerShell)

On first up, azd prompts for a subscription, region, and environment name; it creates resource group rg-<env-name> automatically. There is no separate .env to edit — configuration is done with azd env set <KEY> <VALUE> before up.

If devclaw/devclaw.cmd is not executable, call azd directly (azd up, azd down, azd deploy) — devclaw only adds friendly status/logs/start/stop/teams helpers.

---

Deploy in one prompt (zero-effort path)

This skill is built so the user can drive the whole lifecycle in plain English — no hand-typed azd/az. When the user asks, do the work for them end to end and report the result:

• "Deploy openclaw-dev to eastus2." → confirm prereqs, azd env set AZURE_LOCATION eastus2, ./devclaw up, then open/print the URL from devclaw status.
• "Run tool execution in ephemeral sandboxes." → devclaw exec-mode sandbox then ./devclaw up.
• "Connect it to Teams so I can use it from my phone." → devclaw teams, then walk the one-time sideload step.
• "Stop it to save money." → devclaw stop. "Bring it back." → devclaw start.
• "Why is devclaw up failing?" → read the error, match the catalog below, apply the fix.
• "Tear it all down." → state exactly what will be deleted, get confirmation, then devclaw down.

Minimal happy path (browser-only, default in-process execution):

azd env set AZURE_LOCATION eastus2     # an allowed region (list below)
./devclaw up                            # provision + build + deploy (~6 min)
./devclaw status                        # open the printed URL, sign in

Everything else — Teams, sandbox execution, cost controls — is an opt-in layer on top of that same devclaw up.

---

Command map (devclaw <cmd>)

Command	What it does	Underlying call
up	Provision + remote build + deploy	azd up
deploy	Rebuild & redeploy after code changes (~3–4 min)	azd deploy
status	Container state, FQDN, URL, resource group	az containerapp ...
logs	Stream live container logs	az containerapp logs show --follow
test	Print container/auth/identity summary + console hint (NOT an e2e model test)	az containerapp show
start	Scale to 1 replica (resume after stop)	az containerapp update --min/max-replicas 1
stop	Scale to 0 replicas — $0, state preserved on Azure Files	az containerapp update --min/max-replicas 0
restart	Restart the active revision	az containerapp revision restart
teams	Opt-in. Enables Teams (re-provisions + redeploys on first run) and builds the sideload zip	azd provision + azd deploy + enable Teams channel + zip
exec-mode <inproc|sandbox>	Choose where tools run: in the Gateway container (inproc, default) or in ephemeral ACA Sandboxes (sandbox). Apply with devclaw up	azd env set EXECUTION_MODE …
clone	(ACA Sandboxes host only) Boot another OpenClaw from the existing disk image — independent URL + token	aca sandbox …
login	Switch Azure account	az login + azd auth login

The fastest real smoke test is the WebChat UI (open the URL from devclaw status), not devclaw test.

---

Prerequisites (check before deploying)

• Azure CLI (az) and Azure Developer CLI (azd) installed and logged in (az login, azd auth login). devclaw checks for both and exits if missing.
• An Azure subscription and a tenant where the user can create one Entra ID app registration for the Easy Auth login gate. The optional Teams add-on creates a second app registration (the Bot) plus a client secret — some tenants restrict this (see error catalog).
• Either local Docker Desktop running or the default remoteBuild: true in azure.yaml (ACR builds the image — no local Docker needed).
• PowerShell 7+ (pwsh) on Windows only if running devclaw teams (optional Teams add-on).

---

Configuration contract (azd env set before devclaw up)

Env var	Required	Default	Notes
AZURE_ENV_NAME	prompted	—	Names the env and rg-<env-name>
AZURE_LOCATION	prompted	—	Must be in the allowed region list (below)
AZURE_SUBSCRIPTION_ID	no	prompted	Set to skip the interactive picker
AZURE_OPENAI_LOCATION	no	= AZURE_LOCATION	Override when the chosen region lacks the model SKU (e.g. ACA in eastasia, OpenAI in eastus2)
USE_EXPRESS_ENV	no	false	ACA Express mode (preview); only in supported regions (East Asia, West Central US)
USE_SANDBOX	no	false	Use the ACA Sandboxes host (preview / Early Access) instead of Azure Container Apps. Mutually exclusive with the Container Apps host and the Teams add-on. Bicep provisions a Microsoft.App/SandboxGroups resource + user-assigned managed identity (keyless Azure OpenAI); the postprovision hook (infra/hooks/sandbox.*) installs the aca CLI, builds the OpenClaw image into ACR, imports it as a disk image, boots a sandbox, and exposes the gateway port. devclaw up runs azd provision only (sandboxes aren't an azd-native host). Requires the Early Access feature enabled on the subscription; if SandboxGroups fails with an api-version error, update the literal in infra/sandbox.bicep.
SANDBOX_PUBLIC	no	false	Only with USE_SANDBOX=true. false = the sandbox port is Entra-gated to the deployer via the ADC data plane: an allow-list of the deployer's object id (the reliable oid claim) + email. true = anonymous public URL (anyone with the link).
SANDBOX_ALLOW_DOMAIN	no	false

Allowed AZURE_LOCATION values: australiaeast, eastasia, eastus, eastus2, japaneast, koreacentral, southindia, swedencentral, switzerlandnorth, uksouth, westcentralus.

Model: gpt-5.4-mini (version 2026-03-17, capacity 50 TPM-thousands) is set in infra/main.bicep. To change the model/version/capacity, edit the openai module params there (aiModelName, aiModelVersion, aiModelCapacity) — they are not env vars. Keep it to an Azure OpenAI model available in AZURE_OPENAI_LOCATION, and keep src/openclaw.json's model id in sync with aiModelName.

Example region split when the model isn't in your ACA region:

azd env set AZURE_LOCATION eastasia
azd env set AZURE_OPENAI_LOCATION eastus2
./devclaw up

---

Execution & host modes (pick one)

Mode	How	What it means
In-process (default)	nothing to set, or devclaw exec-mode inproc	The Gateway runs tools itself, inside its own ACA container. Simplest.
Sandbox execution (recommended for untrusted work)	devclaw exec-mode sandbox then devclaw up	The Gateway stays on ACA but offloads each untrusted tool run (shell / codegen / browser) to an ephemeral ACA Sandbox via the sandbox MCP server, then throws it away. Teams-compatible. This is the "one brain, many disposable sandboxes" model in the architecture diagram.
Sandbox host (experimental)	azd env set USE_SANDBOX true then devclaw up	The entire Gateway runs inside an ACA Sandbox instead of a Container App. Provision-only; no Teams. Most users should prefer sandbox execution over this.

EXECUTION_MODE=sandbox and USE_SANDBOX=true are mutually exclusive. Both require the ACA Sandboxes Early Access feature enabled on the subscription.

---

Common tasks

Deploy from scratch

1. Confirm az/azd installed and logged in (devclaw login if not).
2. Optional: azd env set AZURE_SUBSCRIPTION_ID <id> / AZURE_LOCATION <region> / AZURE_OPENAI_LOCATION <region>.
3. ./devclaw up (or .\devclaw.cmd up). First run ~6 min.
4. Verify: devclaw status (expect Running), then open the URL in a browser — Entra ID prompts for Microsoft sign-in, then the WebChat UI loads.

Save cost when idle

devclaw stop scales to 0 replicas ($0, state preserved on Azure Files); devclaw start resumes. Don't use down for this — down deletes everything.

Connect to Microsoft Teams (optional add-on — phone access)

Teams is off by default. Enable it with:

azd env set ENABLE_TEAMS true
devclaw teams      # first run: re-provisions + redeploys, then enables channel + builds zip

If the user runs devclaw teams without setting ENABLE_TEAMS, the wrapper will prompt to enable it and re-provision in one step.

1. devclaw teams — (re-)provisions the bot app reg + Azure Bot when needed, enables the Teams channel, and builds teams/openclaw-teams-app.zip (regenerated; gitignored). The zip is baked from teams/manifest.json (committed source); teams/package/manifest.json is the generated copy and is gitignored — only edit the source.
2. In Teams: Apps → Manage your apps → Upload a custom app → select the zip → Add → DM the bot.

• Requires pwsh on Windows. The msteams plugin must be active in src/openclaw.json (plugins.allow: ["msteams"] + plugins.entries.msteams.enabled: true) — already shipped. When Teams is disabled the entrypoint disables the plugin at boot so the gateway doesn't try to authenticate with empty Bot Framework credentials.
• Legal URLs in the manifest show up in Teams' About dialog ("Created by …", Privacy policy, Terms of use). The shipped teams/manifest.json points privacyUrl and termsOfUseUrl at Microsoft's generic statements (microsoft.com/en-us/privacy/privacystatement, microsoft.com/en-us/legal/terms-of-use) and websiteUrl at the README's #alpha anchor so users see the alpha caveat. Anyone forking under a different org must repoint these to their own policy URLs before sideloading.

Restrict access to specific users/groups

Easy Auth is configured automatically by devclaw up. To lock it down: Azure Portal → Entra ID → App registrations → openclaw-auth-<env> → Enterprise applications → set Assignment required? = Yes and assign users/groups.

Tear everything down (DESTRUCTIVE — confirm first)

devclaw down deletes the resource group, ACA, OpenAI, storage, and the Entra app registrations that were created (Easy Auth always; Bot only when the Teams add-on is enabled). Always confirm with the user before running it.

---

Error catalog (match symptom → fix)

Symptom	Cause	Fix
Please run 'az login' to setup account. inside the [preprovision] hook even though az account show works in your normal shell	azd points AZURE_CONFIG_DIR at the repo-local .azure/ folder; that folder has no signed-in account.	Already shipped: the preprovision hook detects this and unsets AZURE_CONFIG_DIR so az falls back to the user's default (~/.azure / %USERPROFILE%\.azure). If you still see it, run az login in the same shell you'll run devclaw up from.
[preprovision] ERROR: Failed to create ... app registration and ServiceManagementReference field is required for Create	Restricted tenant requires serviceManagementReference (a service-management-reference GUID) on every new app registration.	azd env set SERVICE_MANAGEMENT_REFERENCE <guid> and re-run devclaw up. The hook forwards it to both az ad app create calls (Easy Auth + Bot). Get the GUID from your tenant admin.
Resource 'acr...' was disallowed by policy ... Container registries should have local admin account disabled.	Subscription policy requires adminUserEnabled: false on ACR.	Already shipped: ACR is created with admin disabled and the container app pulls images via its system-assigned managed identity (AcrPull role assigned by Bicep). No env var needed.
Local authentication methods are not allowed on the storage account, or allowSharedKeyAccess: true is disallowed by policy	Subscription policy blocks shared-key access on storage; ACA file mounts require shared keys today.	azd env set SKIP_STORAGE true then re-run devclaw up. The storage account, file share, and volume mount are skipped; the entrypoint falls back to an in-container ephemeral state dir. Gateway token + sessions won't survive a replica restart.
Failed to provision revision for container app — Operation expired (~20 min timeout) on first provision	The placeholder image (mcr.microsoft.com/k8se/quickstart:latest) listens on , but probes/ingress were targeting .

Test the model endpoint directly (keyless)

TOKEN=$(az account get-access-token --resource "https://cognitiveservices.azure.com" --query accessToken -o tsv)
ENDPOINT=$(az cognitiveservices account list -g <rg> --query "[0].properties.endpoint" -o tsv)
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Hello"}]}' \
  "$ENDPOINT/openai/v1/chat/completions"

---

Architecture (for accurate answers)

• Azure Container Apps hosts the OpenClaw gateway; public HTTPS on :18789. Inside the container, src/entrypoint.sh starts three Node processes: gateway-proxy (:18789, splits ingress by path), the OpenClaw gateway (:18788), and the auth-proxy (:18790, injects a fresh MI bearer token).
• Azure OpenAI in Foundry Models is called via the OpenAI-compatible REST API under /openai/v1/... — src/openclaw.json sets the adapter to "api": "openai-completions" and src/auth-proxy.mjs injects the MI bearer. No openai npm SDK. disableLocalAuth: true (no keys). To target a non-v1 AOAI surface, set AOAI_DEFAULT_API_VERSION (see env-var table).
• Managed Identity has the Cognitive Services User role on the model account.
• Entra ID Easy Auth forces Microsoft sign-in before the container; /api/messages is excluded so Bot Framework can call in with its own JWT.
• Azure Bot Service fronts the Teams channel; Azure Files persists state; Container Registry stores the image; Log Analytics holds logs.

Security model (defense in depth — 4 layers)

1. Entra ID Easy Auth (Microsoft login, tenant-scoped) before the container.
2. Gateway token — random per-container token required for the WebSocket API.
3. Managed Identity — short-lived Entra tokens, disableLocalAuth: true, no keys.
4. Ephemeral container — disposable; devclaw down && devclaw up = clean slate.

Warn the user that: OpenClaw runs arbitrary code and is susceptible to prompt injection (don't run it on a work laptop — that's the whole point of this template); only install trusted skills; don't paste highly sensitive data (it flows through the model endpoint); the container runs as root (harden for production).

---

Destructive-action policy (always follow)

Before running any of these, state what will be deleted and ask the user to confirm:

• devclaw down / azd down --purge (deletes the whole resource group)
• az ad app delete (removes the Bot / Easy Auth app registrations)
• removing role assignments, or rm -rf .azure* / state files

Never use --no-prompt/--force to skip a confirmation the user hasn't given.