OpenClaw on Ubuntu 24.04 LTS on Azure User Guide

Overview

This guide covers the deployment and first use of OpenClaw 2026.10.3 on Microsoft Azure using cloudimg's pre configured virtual machine image from the Azure Marketplace.

OpenClaw is an open source AI agent gateway, published under the MIT licence. A single long running process, the Gateway, owns your agents, their sessions and workspaces, the tools they can use, scheduled automations and any chat channels you connect. It also serves the Control UI, a browser application where you talk to agents, watch what they are doing, and approve the actions that need a human.

OpenClaw does not include a language model. You connect the providers you already use, such as Anthropic, OpenAI, OpenRouter or an Ollama server, and the agents run on those models.

What's included:

• OpenClaw 2026.10.3, released 13 October 2026, the newest stable release at build time, installed from the official openclaw npm package
• Node.js 24 LTS from the signed NodeSource repository, pinned and included in unattended security upgrades
• nginx as the only public entry point, with HTTPS and a password gate in front of the Gateway
• A per machine gateway token, web password and TLS certificate, all generated on your virtual machine at first boot
• Ubuntu 24.04 LTS, fully patched at build time, with unattended security upgrades enabled

How this image is put together

browser ──HTTPS :443──> nginx (TLS + password) ──> 127.0.0.1:18789 OpenClaw Gateway (token)
          HTTP  :80 ──> redirect to HTTPS

The Gateway listens on the loopback interface only and is never reachable from the network directly. nginx is the front door, and reaching an agent takes two separate secrets, both unique to your machine:

1. the web password for the user admin, checked by nginx before any request reaches the Gateway, and
2. the gateway token, which the Control UI asks for once and which the Gateway checks itself.

nginx also refuses any request whose browser origin is not the page's own address, so another website cannot drive your Gateway from a visitor's browser. After nginx has authenticated a request it presents it to the Gateway as a connection from the same machine, which is why a browser that supplies the correct gateway token is paired automatically and you never need to approve it from the command line.

Exposed ports: 22, 80 and 443, and nothing else.

Security model

OpenClaw agents are powerful by design: they read and write files, run commands and call web services on your behalf. On this image the Gateway, and therefore every tool an agent runs, executes as the unprivileged system user openclaw, whose home is /var/lib/openclaw. That account has no sudo rights and cannot read root's files. This is OpenClaw's standard personal assistant model: one trusted operator per Gateway. If several people who do not trust each other need agents, give each of them their own virtual machine.

The OpenClaw project fixes security issues quickly and often. Plan to update regularly; the procedure is in the Updating OpenClaw section below.

Deploying the virtual machine

Create the machine from the Marketplace image. Standard_B2ms (2 vCPU, 8 GiB) is the recommended size. The idle Gateway uses about 1 GiB of memory, and agents that run builds, browsers or other tools need headroom on top of that.

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn cloudimg1647283583153:openclaw-ubuntu-24-04:default:latest

az vm create \
  --resource-group my-agents-rg \
  --name openclaw01 \
  --image cloudimg1647283583153:openclaw-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

az vm open-port --resource-group my-agents-rg --name openclaw01 --port 443 --priority 1001
az vm open-port --resource-group my-agents-rg --name openclaw01 --port 80 --priority 1002

Restrict the source addresses on those rules to your own network if you can. Port 80 only redirects to HTTPS and answers a health probe, so you may leave it closed.

On the first boot the machine creates a fresh OpenClaw state for itself: a new gateway token, new encryption and signing keys and a new database, then a web password and a TLS certificate that names the machine's IP addresses. Only when all of that exists does it start the Gateway and then nginx. The Gateway service is gated on that first boot work, so it can never start with state that was not generated on your machine. This takes about a minute after the machine reports that it is running.

Step 1: check the services

Connect over SSH as azureuser and confirm that the first boot completed and both services are running.

sudo systemctl is-active openclaw-firstboot.service openclaw-gateway.service nginx.service
openclaw --version
node --version
curl -s https://127.0.0.1/healthz -k

All three units should report active, followed by the OpenClaw and Node.js versions and ok from the unauthenticated health endpoint.

Next, confirm that only nginx and SSH are listening on the network, that the Gateway is bound to loopback, and that nginx refuses requests without the password or from a foreign origin:

sudo ss -ltn | awk 'NR==1 || /:22 |:80 |:443 |:18789 /'
curl -sk -o /dev/null -w 'no password:     HTTP %{http_code}\n' https://127.0.0.1/
curl -sk -o /dev/null -w 'wrong password:  HTTP %{http_code}\n' -u admin:wrong https://127.0.0.1/

Step 2: read your credentials

The first boot writes everything you need to a file only root can read:

sudo cat /root/openclaw-credentials.txt

It contains the address of your Control UI, the web user and password, and the gateway token. Copy the web password and the gateway token into your password manager.

Step 3: sign in to the Control UI

Browse to https://<public-ip>/. Your browser will warn about the certificate on the first visit. That is expected: the machine issued its own certificate at first boot because it cannot know your domain name in advance. Accept it for now, and replace it with a trusted certificate when you are ready (see Using your own domain and certificate, below).

The browser then asks for a user name and password. Use admin and the OPENCLAW_WEB_PASSWORD value from the credentials file.

The Control UI loads and asks for the Gateway secret. Paste the OPENCLAW_GATEWAY_TOKEN value and click Connect.

The browser is paired with the Gateway as the owner and remembers its own device credential, so the next visit from the same browser profile goes straight in after the web password. A private window, or a browser profile that clears site data, counts as a new device and asks for the token again.

The composer shows No models available until you connect a model provider, which is the next step.

The Control UI needs a current browser: Chrome, Edge or Firefox released within the last six months, or Safari 26.2 or later.

Step 4: connect a model provider

Every OpenClaw command on this machine is run as the openclaw user, so that it reads and writes the same configuration as the Gateway service. Prefix commands with sudo -u openclaw -H. Commands that write files, such as backups, should be run from that user's home directory with sudo -u openclaw -H bash -c 'cd && openclaw <command>'.

The quickest way to add a provider is to paste an API key. The command prompts for the key so it never appears in your shell history:

sudo -u openclaw -H bash -c 'cd && openclaw models auth paste-api-key --provider anthropic'
sudo systemctl restart openclaw-gateway
sudo -u openclaw -H openclaw models list
sudo -u openclaw -H openclaw models set <provider/model-id>
sudo -u openclaw -H openclaw models status

Use --provider openai, --provider openrouter or any other provider OpenClaw supports in the same way. openclaw models list shows the model ids available once a key is saved; openclaw models set makes one of them the default for your agents. Restarting the Gateway after saving a key makes sure it picks the new provider up; give it about 30 seconds before the next command.

If you already run Ollama on another machine in your network, point OpenClaw at it instead. Use the native Ollama address, without /v1:

echo 'OLLAMA_API_KEY=ollama-local' | sudo -u openclaw -H tee -a /var/lib/openclaw/.openclaw/.env
sudo -u openclaw -H openclaw config patch --stdin <<'EOF'
{ models: { providers: { ollama: { baseUrl: "http://<ollama-host>:11434", api: "ollama",
    models: [ { id: "qwen3:8b", contextTokens: 32768, params: { num_ctx: 32768 } } ] } } },
  agents: { defaults: { model: { primary: "ollama/qwen3:8b" } } } }
EOF
sudo systemctl restart openclaw-gateway

OpenClaw agents send a large system prompt with every turn, so a local model needs a context window of at least 16,000 tokens, and small models on CPUs answer slowly. OpenClaw's security audit also reports models of 300 billion parameters or fewer as a critical finding unless agents using them are sandboxed and have the web tools turned off, because small models are easier to steer with hostile web content. A hosted frontier model is the practical choice for day to day work.

Step 5: talk to your agent

Back in the Control UI, the composer now shows your model. Type a message to the main agent and press Enter. While the agent works, the conversation shows its activity; when it finishes, the reply appears with how long the turn took and how many tokens it produced. Turns that use tools add an expandable summary of every tool call the agent made.

The reply above came from a small local model served by Ollama on a separate machine, which is why it is brief. With a frontier hosted model the same agent can plan multi step tasks, edit files in its workspace, run commands and browse the web.

Each agent has a workspace under /var/lib/openclaw/.openclaw/workspace, a git repository holding its persona and memory files (SOUL.md, IDENTITY.md, USER.md, AGENTS.md). Edit them to shape how the agent behaves. Agents in the sidebar lists your agents and lets you create more, and Automations schedules recurring work.

OpenClaw creates three automations for every new installation: a Heartbeat that wakes the main agent every 30 minutes so it can act on its own checklist, a nightly memory consolidation run and a weekly skills review. Each run calls your model provider, so pause the ones you do not want from the Automations page if you are watching token spend.

Step 6: manage the Gateway from the command line

The openclaw command line talks to the running Gateway over its loopback port using the token in its own configuration:

sudo -u openclaw -H openclaw gateway status
sudo -u openclaw -H openclaw health
sudo -u openclaw -H openclaw devices list

gateway status confirms the Gateway is bound to loopback and reachable, health reports its event loop and agents, and devices list shows every browser or app paired with the Gateway. Remove a device you no longer use with openclaw devices remove <device-id>.

OpenClaw's own security audit is a useful periodic check:

sudo -u openclaw -H openclaw security audit

It reports one warning on this image, gateway.trusted_proxies_missing. That is expected: nginx deliberately presents authenticated requests to the Gateway as local connections, as described in the overview, and the Gateway is not reachable from the network in any other way.

Updating OpenClaw

OpenClaw publishes security fixes frequently, so check for a new release at least monthly. The operating system, Node.js and nginx are patched automatically by unattended upgrades; OpenClaw itself is updated with npm:

npm view openclaw dist-tags.latest
sudo npm install -g openclaw@latest --allow-scripts=openclaw --no-fund --no-audit
sudo systemctl restart openclaw-gateway
openclaw --version

After an update, reload any open Control UI tabs so the browser picks up the matching interface.

If the release notes ask you to run openclaw doctor --fix, stop the Gateway first and run it from the openclaw user's home directory, then start the Gateway again yourself. Doctor cannot restart a system service, so it reports that the Gateway could not be restored; that message is expected here.

sudo systemctl stop openclaw-gateway
sudo -u openclaw -H bash -c 'cd && openclaw doctor --fix'
sudo systemctl start openclaw-gateway

Using your own domain and certificate

Point a DNS name at the machine's public IP address, then replace the self signed certificate. With a certificate and key from your own authority:

sudo cp fullchain.pem /etc/nginx/openclaw/tls.crt
sudo cp privkey.pem /etc/nginx/openclaw/tls.key
sudo chown root:www-data /etc/nginx/openclaw/tls.crt /etc/nginx/openclaw/tls.key
sudo chmod 0640 /etc/nginx/openclaw/tls.key
sudo nginx -t && sudo systemctl reload nginx

You can also use Let's Encrypt with certbot's nginx plugin once port 80 is open and the name resolves. No OpenClaw setting needs to change when you add a domain.

Changing the web password

The web password is an nginx Basic Auth entry. Replace it with one you choose:

NEWPW='<new-password>'
printf 'admin:%s\n' "$(printf '%s' "$NEWPW" | openssl passwd -apr1 -stdin)" | sudo tee /etc/nginx/openclaw/htpasswd >/dev/null
sudo systemctl reload nginx

Update /root/openclaw-credentials.txt too if you rely on it.

Rotating the gateway token

To issue a new gateway token, generate it, restart the Gateway and read it back:

sudo -u openclaw -H openclaw doctor --generate-gateway-token
sudo systemctl restart openclaw-gateway
sudo -u openclaw -H openclaw gateway auth-token --show

auth-token --show only prints the token in an interactive terminal, so run it in your SSH session rather than from a script.

Browsers that are already paired keep their own device credential. To force every browser to present the new token, remove the old devices with openclaw devices remove.

Backups

The Gateway's state, including configuration, credentials, sessions and agent workspaces, lives under /var/lib/openclaw/.openclaw. OpenClaw can write a verified archive of it:

sudo -u openclaw -H bash -c 'cd && openclaw backup create'
sudo ls -l /var/lib/openclaw/ | grep openclaw-backup

The archive is written to /var/lib/openclaw and is readable only by the openclaw user.

Copy the archives off the machine, for example to Azure Blob Storage, and also consider Azure Backup for the whole virtual machine.

Troubleshooting

The Control UI says the Gateway is unreachable or keeps reconnecting. Check that the Gateway is running and read its recent log:

sudo systemctl status openclaw-gateway --no-pager | head -8
sudo journalctl -u openclaw-gateway --no-pager -n 20

The browser shows 403 Forbidden. nginx refuses requests whose browser origin is not the page's own address. This happens when another site or browser extension makes the request; open the Control UI directly by its address.

The first boot did not finish. The first boot log explains why, and the Gateway will not start until it succeeds:

sudo journalctl -u openclaw-firstboot --no-pager | tail -20

An agent reply fails with "The AI service is having trouble". The model provider rejected or could not serve the request. Run sudo -u openclaw -H openclaw models status to check the provider's credentials, and confirm that the machine can reach the provider's API.

Support

This image is maintained by cloudimg. The operating system receives security updates automatically, and the image is rebuilt and republished as new OpenClaw releases appear.

For help with this image, contact cloudimg support. For questions about OpenClaw itself, see the upstream documentation at docs.openclaw.ai.

OpenClaw is published under the MIT licence, which ships with the image:

head -3 /usr/lib/node_modules/openclaw/LICENSE