Run an AI Agent in Docker

Deploy a containerized AI agent with OpenClaw and connect it to OpenRouter.

Introduction

30 Second Summary

AI assistants are everywhere, but most people only use them through someone else's app. What if you could run your own AI agent on your machine, fully under your control?

In this project, you will deploy a personal AI agent inside a Docker container on your Mac. You will connect it to hundreds of AI models through a single API key and chat with it through a web dashboard.

What You'll Build

A containerized AI agent gateway powered by OpenClaw, running inside Docker and connected to AI models through OpenRouter.

By the end of this project, you'll have:

  • A running OpenClaw gateway container managed by Docker Compose.
  • A persistent configuration directory that survives container restarts, powered by bind mounts.
  • A working OpenRouter integration giving your agent access to hundreds of AI models through a single API key.
  • Secret Mission: Customize your agent's identity with a unique name and personality, then switch it to a specific AI model through OpenRouter.

Are there any prerequisites?

No prior experience with Docker or AI agents is required. This project walks you through setting up every tool you need, including Docker Desktop, Git, and an OpenRouter account.

Before We Start

Before We Start...

Verify Your Tools

Before you can run an AI agent, you need to confirm that the tools it depends on are installed and working.

In this step, you will verify that Docker Desktop, Docker Compose, and Git are all ready on your Mac.

You will also clone the OpenClaw repository, which contains everything Docker needs to build and run your agent's gateway container.

In this step, get ready to:
  • Confirm Docker Desktop and Docker Compose v2 are running.
  • Verify Git is installed.
  • Clone the OpenClaw repository to your local machine.
Check Docker Desktop is running

Docker Desktop is the application that runs the Docker engine on your Mac.

The engine must be active before you can run any docker commands in your terminal.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Docker Desktop and press Enter to open it.
  • Look for the Docker whale icon in the menu bar at the top of your screen.
  • Wait until the icon is solid and steady (not animating).

A solid whale icon means the Docker engine is running and ready to accept commands.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal and press Enter to open it.
  • Verify Docker is installed by running this command:
docker --version

✔️ I see a version number

Docker is installed and ready.

ⓧ Command not found

Docker Desktop is not installed or the engine is not running yet.

  • Download Docker Desktop from docker.com/products/docker-desktop.
  • Open the downloaded .dmg file and drag the Docker icon into your Applications folder.
  • Launch Docker Desktop from Applications and wait for the whale icon to appear in your menu bar.
  • Run docker --version again to confirm it works.
  • Verify Docker Compose is available by running this command:
docker compose version

✔️ I see a version number

Docker Compose v2 is installed and ready.

ⓧ It's not installed yet

Docker Compose v2 comes bundled with Docker Desktop.

  • Make sure Docker Desktop is up to date by opening it and going to Settings, then Software updates.
  • Install any available updates, then restart Docker Desktop.
  • Run docker compose version again to confirm it works.

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container applications with a single configuration file.

Instead of typing long docker run commands, you describe your containers in a docker-compose.yml file and start everything with one command.

Verify Git and clone the OpenClaw repository

Git is a version control tool that tracks changes to code.

You will use it to download (clone) the OpenClaw project from GitHub to your machine.

  • Check that Git is installed by running this command:
git --version

✔️ I see a version number

Git is installed and ready.

ⓧ Command not found

On macOS, Git comes with the Xcode Command Line Tools.

  • Install Git by running this command:
xcode-select --install
  • A system dialog will appear asking you to install the Command Line Tools.
  • Click Install and agree to the license agreement.
  • Wait for the installation to finish, then click Done.
  • Run git --version again to confirm it works.
  • Move to your Desktop by running this command:
cd ~/Desktop
  • Clone the OpenClaw repository and move into it by running these commands:
git clone https://github.com/openclaw/openclaw.git
cd openclaw

What does this command do?

  • git clone downloads the entire OpenClaw project from GitHub to a new folder called openclaw on your Desktop.
  • cd openclaw moves your terminal into that new folder so all future commands run from inside the project.
  • Confirm the repo was cloned by running:
ls

You should see a list of files and folders including Dockerfile, docker-compose.yml, and docker-setup.sh.

Clone failed or folder is empty?

  • Make sure you are connected to the internet. git clone downloads files from GitHub and needs a network connection.
  • Check that you ran cd ~/Desktop before the clone command. If you skipped that, the openclaw folder may be in a different location.
  • If you see fatal: destination path 'openclaw' already exists, the folder was already cloned. Run cd openclaw to move into it.

My git clone command is failing. How do I fix it?

Understand what you just downloaded

The OpenClaw repo contains the source code for the AI agent gateway, plus the Docker configuration files that tell Docker how to build and run it.

You do not need to understand every file. The three key files are the ones Docker uses.

What do the key files do?

  • Dockerfile is the recipe for building a Docker image. It lists every dependency and configuration step needed to package OpenClaw into a portable unit.
  • docker-compose.yml defines how the container runs. It sets the ports, environment variables, and storage volumes the gateway needs.
  • docker-setup.sh is the setup script you will run in the next step. It pulls the Docker image, walks you through onboarding, and starts the gateway.

Your tools are verified and the OpenClaw code is on your machine.

Next up, you will grab an API key from OpenRouter so your agent can connect to real AI models.

Get Your OpenRouter API Key

Your Docker tools are ready and the OpenClaw repository is cloned. Now your AI agent needs a brain.

OpenClaw doesn't ship with its own AI model. It connects to external models through a service called OpenRouter, which gives your agent access to hundreds of models behind a single API key.

In this step, get ready to:
  • Create an OpenRouter account and API key.
  • Understand how OpenRouter connects your agent to AI models.
Create an OpenRouter account and API key
  • Go to https://openrouter.ai/keys in your web browser.
  • Click Sign Up if you don't have an account and complete the registration.
  • Once you're signed in, click Create Key.
  • Enter OpenClaw as the key name.
  • Click Create to generate the key.
  • Copy the key that appears. It starts with sk-or-v1-.

Save your key before leaving the page

You won't be able to see the full key again after you navigate away from this page. Paste it into a notes app or text file on your Desktop right now.

  • Save the copied key somewhere safe, like a notes app or text file. You'll need it in the next step.

Can't find your key after creating it?

If you navigated away before copying, the full key is no longer visible on the page. Delete the key from your https://openrouter.ai/keys dashboard and create a new one.

Need more help? I'm having trouble creating or finding my OpenRouter API key.

Understand what OpenRouter does

What is OpenRouter?

OpenRouter is a unified API gateway that routes your requests to hundreds of AI models. One API key gives you access to models from Anthropic (Claude), OpenAI (GPT), Google (Gemini), and many more providers.

OpenClaw uses your OpenRouter API key to send messages to these models. When you chat with your agent, OpenClaw forwards your message through OpenRouter to whichever model is selected.

Why OpenRouter instead of signing up with each provider?

Without OpenRouter, you'd need separate accounts and API keys for every AI provider you want to use. OpenRouter consolidates all of them behind a single endpoint and key. It also offers free models and credits for new accounts, so you can experiment without spending anything.

You've got your API key ready. Next up, you'll use it to fire up your OpenClaw agent inside a Docker container.

Run the Docker Setup Script

Your OpenRouter API key is ready. Now it's time to launch your AI agent inside a Docker container.

OpenClaw ships with a setup script that does the heavy lifting. It pulls the correct Docker image, runs an onboarding wizard, and starts the gateway container.

In this step, get ready to:
  • Set an environment variable to use the pre-built OpenClaw image.
  • Run the setup script and complete the onboarding wizard.
  • Verify the gateway container is running.
Tell the setup script to use the pre-built image

Building the OpenClaw Docker image from source takes over 15 minutes and uses a lot of RAM. The faster approach is to point the setup script at a pre-built image from GitHub Container Registry.

  • Set the OPENCLAW_IMAGE environment variable by running this command:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

What does this command do?

export creates an environment variable in your current Terminal session. The setup script reads OPENCLAW_IMAGE to decide whether to build from source or pull a ready-made image.

The image ghcr.io/openclaw/openclaw:latest is the official pre-built release hosted on GitHub Container Registry. Using it skips the entire local build process.

Run the setup script

The setup script is interactive. It pulls the Docker image, launches an onboarding wizard, and then starts the gateway container.

  • Run the setup script from the repo root:
./docker-setup.sh

The script pulls the Docker image first, which may take a minute on the first run. It then launches an interactive onboarding wizard.

  • Select OpenRouter as your AI provider when prompted.
  • Paste your OpenRouter API key (the one starting with sk-or-v1-) when the wizard asks for it.

After you complete the wizard, the script generates a gateway token and starts the container automatically.

What just happened?

  • The script pulled the ghcr.io/openclaw/openclaw:latest Docker image. A Docker image is a pre-packaged snapshot of the entire application with all its dependencies bundled in.
  • It created a .env file in your openclaw/ directory containing your gateway token and OpenRouter API key.
  • It started the OpenClaw gateway container using Docker Compose, which reads the docker-compose.yml file to know how to configure and run the container.

Script not found or permission denied?

  • If you see "Permission denied", make the script executable by running chmod +x docker-setup.sh and try again.
  • If ./docker-setup.sh says "Docker setup script not found", try running ./scripts/docker/setup.sh instead. Some versions of the repo place the script at a different path.
  • If the image pull fails or times out, confirm Docker Desktop is running by checking the whale icon in your menu bar.

Help me troubleshoot the OpenClaw Docker setup script

Verify the container is running
  • Check that the gateway container is up by running:
docker compose ps

You should see a container named openclaw-gateway (or similar) with status "running".

Container showing 'restarting' or 'exited'?

Check the container logs for error details by running:

docker compose logs -f openclaw-gateway
  • If you see exit code 137, the container ran out of memory. Open Docker Desktop, go to Settings, then Resources, and increase the memory limit to at least 2 GB.
  • If the logs mention an API key error, your OpenRouter key may not have been saved correctly during onboarding. You can fix this in the next step.

Help me fix my OpenClaw gateway container that won't start

Your AI agent's gateway is running inside a Docker container. Next, you'll open the Control UI in your browser and start chatting with your agent.

Open the Control UI and Connect

Your gateway container is up and running inside Docker. The infrastructure setup is done.

OpenClaw includes a built-in web dashboard called the Control UI. In this step, you'll open it in your browser and authenticate with your gateway token.

In this step, get ready to:
  • Open the OpenClaw Control UI in your browser.
  • Authenticate using your gateway token.
  • Troubleshoot connection issues if they come up.
Access the Control UI in your browser

The OpenClaw gateway serves a web-based dashboard on port 18789 of your local machine. This is where you'll chat with your agent, configure channels, and manage skills.

  • Open your web browser (Chrome, Firefox, Safari, or any browser works).
  • Paste http://127.0.0.1:18789/ into the address bar and press Enter.

You should see the OpenClaw Control UI load. It will show an authentication prompt asking for your gateway token.

What is 127.0.0.1?

127.0.0.1 is your computer's localhost address. It means "this machine."

The Docker container mapped port 18789 from inside the container to your Mac. Your browser can reach the gateway as if it were a regular local web app.

Don't see anything loading?

  • Make sure your OpenClaw gateway container is still running. Switch to your terminal and run docker compose ps to check.
  • Confirm the URL is exactly http://127.0.0.1:18789/ with no typos or missing slashes.
  • Why can't I connect to the OpenClaw Control UI at 127.0.0.1:18789?
Authenticate with your gateway token

The setup script generated a unique gateway token during onboarding. This token secures access to your agent so only you can control it.

The token is stored in the .env file inside your openclaw directory.

  • Retrieve your gateway token by running this command:
grep OPENCLAW_GATEWAY_TOKEN .env

What does this command do?

grep searches a file for a specific text pattern. Here it finds the line containing OPENCLAW_GATEWAY_TOKEN in your .env file and prints it to the terminal.

You should see a line like OPENCLAW_GATEWAY_TOKEN=abc123... printed in your terminal.

  • Copy the token value (everything after the = sign).
  • Switch back to the Control UI in your browser.
  • Paste the token into the authentication field.
  • Click Confirm or press Enter to log in.

You should see the OpenClaw agent dashboard. It includes a chat interface, channels configuration, and skills management.

Seeing 'unauthorized' or a blank page?

  • Double-check that you copied the full token with no extra spaces before or after it.
  • Make sure the gateway container is still running by checking docker compose ps in your terminal.
  • Why am I getting an unauthorized error in the OpenClaw Control UI?
Troubleshoot if needed

If the Control UI shows disconnected (1008): pairing required or a persistent unauthorized error that won't go away after re-pasting the token, the gateway needs to re-pair with the dashboard.

If you logged in successfully, skip ahead to the next step.

  • Open a new dashboard pairing session by running this command:
docker compose run --rm openclaw-cli dashboard --no-open
  • List the pending device pairing requests by running:
docker compose run --rm openclaw-cli devices list

The output shows one or more pending requests, each with a request ID.

  • Approve the pending request by running this command with the request ID from the output:
docker compose run --rm openclaw-cli devices approve [[REQUEST_ID="request ID from the devices list output"]]

What do these recovery commands do?

  • dashboard --no-open creates a new dashboard connection request without opening a browser tab.
  • devices list shows all pending device pairing requests waiting for approval.
  • devices approve approves a specific request so the dashboard can securely connect to your gateway.
  • After approving, refresh the Control UI in your browser at http://127.0.0.1:18789/.

You should now see the agent dashboard with a chat interface.

Still can't connect after approving?

  • If devices list shows no pending requests, close the browser tab first, reopen http://127.0.0.1:18789/, and then run the three commands again.
  • Check the gateway logs for clues by running docker compose logs --tail 20 openclaw-gateway in your terminal.
  • How do I fix OpenClaw pairing errors with the Control UI?

Your Control UI is connected and your agent dashboard is ready. Next up, you'll send your first message and have a real conversation with your AI agent.

Chat With Your AI Agent

The OpenClaw gateway is running and you're logged into the Control UI. Time to put it all to the test.

In this step, you'll send your first message to the AI agent and confirm the full round-trip works. Your message travels from the browser to the Docker container, out to OpenRouter, and back with a response from an AI model.

In this step, get ready to:
  • Send your first message to the AI agent through the Control UI.
  • Verify that OpenRouter is correctly connected and routing requests to an AI model.
Send your first message

When you type a message in the Control UI, it kicks off a chain of events. The OpenClaw gateway container receives your message, forwards it to the OpenRouter API, and OpenRouter routes it to the best available AI model.

  • In the Control UI at http://127.0.0.1:18789/, click on the chat input field at the bottom of the screen.
  • Type Hello! Tell me what you can do. into the chat input.
  • Press Enter to send your message.

You should see a response from your agent within a few seconds.

What just happened?

Your message just completed a full round-trip through four stages.

  • Your browser sent the message to the OpenClaw gateway running inside the Docker container.
  • The gateway forwarded it to the OpenRouter API at https://openrouter.ai/api/v1.
  • OpenRouter selected an AI model and generated a response.
  • The response traveled back through the gateway to your browser.

The default model selection is openrouter/auto, which lets OpenRouter pick the best available model for each request.

Verify OpenRouter is working

A successful response means OpenRouter is connected and your agent is live. If something went wrong, you'll need to diagnose the connection.

✔️ My agent responded

Your OpenRouter connection is verified and your AI agent is fully operational.

Try a few more questions to explore what your agent can do. Ask it to explain a concept, write some code, or help with a task.

ⓧ I see an error or no response

If you see a 401 error or Missing Authentication header, your OpenRouter API key may not be configured correctly.

  • Check the model provider status by running this command:
docker compose exec openclaw-gateway node dist/index.js models status

What does this command do?

This runs a diagnostic command inside the running gateway container. It checks whether the OpenRouter provider is properly authenticated and can reach the API.

If the OpenRouter provider shows an error, re-add your API key and restart the gateway.

  • Open the file ~/.openclaw/.env in a text editor.
  • Add or update the following line, replacing the placeholder with your actual OpenRouter API key:
OPENROUTER_API_KEY=your-openrouter-api-key-here
  • Save the file, then restart the gateway by running:
docker compose restart openclaw-gateway
  • Wait a few seconds for the container to restart.
  • Refresh the Control UI in your browser and try sending a message again.

Still seeing an error?

Make sure your API key starts with sk-or-v1-. If it does not, the key may have been copied incorrectly from OpenRouter.

Check the gateway logs for more details by running:

docker compose logs -f openclaw-gateway

Help me debug my OpenRouter connection error in OpenClaw.

Your AI agent is live and responding. Next, you'll look under the hood at what Docker is actually running to power all of this.

Explore the Docker Internals

Your AI agent is live and chatting through the Control UI. But what is Docker actually doing behind the scenes?

In this step, you will peek under the hood of your Docker setup. You will learn the commands that every Docker user relies on to inspect, monitor, and manage running applications.

In this step, get ready to:
  • Inspect the running container, image, and logs.
  • Explore how OpenClaw stores persistent data using bind mounts.
  • Practice stopping and restarting your agent container.
Inspect what Docker is running

When something goes wrong with a Docker application, the first thing you do is check what is running and read the logs. These three commands are your diagnostic toolkit.

  • See your container status, image details, and recent logs by running these commands one at a time:
docker compose ps
docker images | grep openclaw
docker compose logs --tail 20 openclaw-gateway

What do these commands do?

  • docker compose ps shows all containers managed by Docker Compose in this project, along with their current status and port mappings.
  • docker images | grep openclaw filters your local images to show only the OpenClaw image you pulled from GitHub Container Registry.
  • docker compose logs --tail 20 openclaw-gateway prints the last 20 lines of log output from the gateway container. This is where you find error messages and startup information.
  • Check the output of docker compose ps. You should see one container with a status of running and port 18789 listed.
  • Check the output of docker images | grep openclaw. You should see the ghcr.io/openclaw/openclaw image with the latest tag.

Container not showing as running?

  • If docker compose ps shows no containers, make sure your terminal is inside the openclaw/ repo directory where the docker-compose.yml file lives.
  • If the status shows exited or restarting, check the full logs with docker compose logs openclaw-gateway to see what went wrong.

Help me debug why my OpenClaw container is not running

Understand persistent storage

Containers are designed to be disposable. So where does your agent's configuration and data go when you destroy one?

OpenClaw uses a bind mount to solve this. The ~/.openclaw/ directory on your Mac is mounted directly into the container, so your data lives on your host filesystem.

  • Inspect the persistent storage directory by running:
ls ~/.openclaw/

What is a bind mount?

A bind mount maps a specific folder on your Mac to a folder inside the container. When the container writes to its mounted path, the data goes straight to your Mac's filesystem.

This means you can destroy the container, recreate it from scratch, and all your configuration is still there. The container is disposable. Your data is not.

  • You should see files like openclaw.json (your agent's configuration) and a workspace/ directory (your agent's working files).
Stop and restart your agent

Knowing how to stop and start containers is essential for any Docker workflow. Stopping a container shuts down the running process without deleting anything.

  • Practice the Docker lifecycle by running these commands one at a time:
docker compose stop openclaw-gateway
docker compose ps
docker compose start openclaw-gateway
docker compose ps

What's happening here?

  • docker compose stop gracefully shuts down the gateway container. Your data in ~/.openclaw/ is untouched.
  • The first docker compose ps confirms the container has stopped. You should see a status of exited or no container listed.
  • docker compose start brings the container back up using the same configuration.
  • The second docker compose ps confirms the container is running again.
  • After the final docker compose ps, confirm the container shows a status of running.
  • Open http://127.0.0.1:18789/ in your browser to verify the Control UI still loads.
  • Leave the container running for the Secret Mission.

Container not starting back up?

  • Make sure Docker Desktop is still running. Check for the Docker icon in your menu bar.
  • If the container shows restarting in a loop, check the logs with docker compose logs -f openclaw-gateway to see the error.

Help me restart my OpenClaw container

Secret mission

Give Your Agent a Custom Identity and Model

Your agent currently uses a default identity and automatic model selection. In this mission, give it a unique personality and hand-pick which AI model powers its brain.

Before you go

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

The OpenClaw gateway container uses minimal resources when idle (under 200MB RAM). OpenRouter charges per API call, but many models have free tiers and new accounts typically receive free credits.

Cost warning

OpenRouter charges are based on API usage. If you leave your agent running and continue chatting with it, you will accumulate charges.

Monitor your usage at openrouter.ai/credits. If you are not actively using your agent, stop the container to prevent accidental API calls.

Resources you used:

  • Docker container running the OpenClaw gateway.
  • Docker image pulled from GitHub Container Registry (ghcr.io/openclaw/openclaw:latest).
  • OpenClaw configuration directory at ~/.openclaw/.
  • Cloned OpenClaw repository on your Desktop.
  • OpenRouter account and API key.

Keep everything running

No action needed. Choose this if you are still actively building or chatting with your agent.

  • The container uses under 200MB of RAM when idle.
  • Docker Desktop automatically restarts the container after a Mac reboot.
  • Your configuration and data persist in ~/.openclaw/.
  • Keep an eye on your OpenRouter usage at openrouter.ai/credits.

Pause - I'll come back to this later

Stop the running container to free up memory. Your configuration and data stay safe on disk.

  • Open Terminal and navigate to the openclaw repo directory on your Desktop.
  • Stop the gateway container by running:
docker compose stop openclaw-gateway
  • Your configuration persists in ~/.openclaw/ and the Docker image stays on disk.
  • When you are ready to come back, restart your agent by running:
docker compose start openclaw-gateway

Delete - I don't want to use this again

Remove all project resources from your Mac and clean up your OpenRouter account.

  • Open Terminal and navigate to the openclaw repo directory on your Desktop.
  • Remove the containers by running:
docker compose down
  • Remove the Docker image by running:
docker rmi ghcr.io/openclaw/openclaw:latest
  • Remove the cloned repository and all OpenClaw configuration by running:
rm -rf ~/Desktop/openclaw ~/.openclaw

Mission accomplished

That's a Wrap!

You just deployed your own personal AI agent using Docker. That is no small thing.

Here's what you built and learned:

  • Pulled a pre-built Docker image from GitHub Container Registry and ran it using Docker Compose.
  • Configured an AI agent gateway with OpenRouter for access to hundreds of AI models behind a single API key.
  • Managed a running containerized application with docker compose ps, logs, stop, and start, with persistent data stored via bind mounts.
  • Secret Mission: Customized your agent's identity and switched between AI models through OpenRouter.

Ready to quiz yourself?