vltmedia/openclaw-agent repository overview

⁠OpenClaw Agent Server

A generic, repo-driven Docker image for running OpenClaw⁠ agents. Point WORKSPACE_REPO at any Git repository with an openclaw/ directory and the container pulls the agent's config, skills, memory, plugins, and workspace files at runtime. One image, any agent.

⁠Quick Start

docker run -d \
  --name my_agent \
  -e WORKSPACE_REPO=https://github.com/your-org/your-agent-repo \
  -e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e GATEWAY_TOKEN=my-secret-token \
  -e OPENCLAW_HOME=/data/openclaw \
  -p 3349:3000 \
  -v openclaw_agent_state:/data/openclaw \
  --tty --interactive \
  your-image-name:latest

Open the Control UI at http://localhost:3349⁠ and enter the gateway token. No onboarding needed — the API key is provisioned automatically from the env var.

⁠How It Works

On every container start:

1. Clones (or pulls) the repo from WORKSPACE_REPO
2. Runs build.sh if present in the repo root (first run and SYNC_MODE=true only)
3. Seeds (first run) or merges (subsequent runs) the openclaw/ directory into the running config
4. Removes the cloned repo to keep the workspace clean
5. Provisions API keys, Discord tokens, and plugin configs from env vars
6. Applies runtime patches (gateway token, CORS origins)
7. Starts the OpenClaw Gateway

All credentials are set from environment variables on every boot, so they survive container recreation (e.g., Coolify redeploys, docker compose up --force-recreate) without needing to re-run onboarding.

⁠Agent Repo Structure

Your WORKSPACE_REPO must contain an openclaw/ directory:

your-agent-repo/
├── build.sh                       # Optional — runs on first boot and SYNC_MODE=true
└── openclaw/
    ├── openclaw.json
    ├── plugins/
    │   └── my-plugin/
    │       ├── index.ts
    │       ├── openclaw.plugin.json
    │       └── skills/
    └── workspace/
        ├── IDENTITY.md
        ├── SOUL.md
        ├── BOOTSTRAP.md
        ├── memory/
        └── skills/
            └── my_skill/
                └── SKILL.md

Any files or directories in workspace/ are copied into the agent's working directory — add datasets, configs, reference docs, or anything else the agent should have access to.

⁠Build Script (build.sh)

If your agent repo has a build.sh in the root directory, the entrypoint runs it before merging — only on first boot and when SYNC_MODE=true. Use it for custom setup like cloning additional repos, compiling assets, or generating config. If build.sh fails (non-zero exit), the entrypoint stops.

⁠Environment Variables

All configuration is done through environment variables. The entrypoint patches everything at runtime, so credentials and config survive container recreation without manual setup.

⁠Required

⁠LLM API Keys

Set at least one. The entrypoint writes the key directly into the agent's auth store — no openclaw onboard needed.

⁠Integrations

⁠Gateway & Access

⁠Git & Repo

⁠Ports

Map it to any host port you like (e.g., -p 3349:3000).

⁠Volumes

⁠Mounting Local Files

Mount a local directory into the agent's workspace so it can read, edit, and create files on your machine:

docker run -d \
  --name my_agent \
  -e WORKSPACE_REPO=https://github.com/your-org/your-agent-repo \
  -e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e OPENCLAW_HOME=/data/openclaw \
  -p 3349:3000 \
  -v openclaw_agent_state:/data/openclaw \
  -v /path/to/your/project:/data/openclaw/.openclaw/workspace/work \
  --tty --interactive \
  your-image-name:latest

The mount must be inside /data/openclaw/.openclaw/workspace/ — this is the agent's workspace path, so anything inside it is accessible without permission prompts. The work subdirectory is the agent's default working directory, putting your files right where it operates. Changes are synced in real time — files the agent creates appear on your local disk, and local edits are immediately visible to the agent.

⁠Authentication

The gateway requires a token to connect. Set GATEWAY_TOKEN in your environment:

-e GATEWAY_TOKEN=my-secret-token

To allow access from additional origins (e.g., remote hosts):

-e ALLOWED_ORIGINS="http://localhost:3349,https://myhost.example.com"

⁠Private Repositories

To clone from a private repo, set GIT_TOKEN:

-e GIT_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Works with GitHub PATs, GitLab tokens (GIT_USER=oauth2), Gitea tokens, etc. If GIT_TOKEN is not set, credentials are skipped (public repos only).

⁠Docker Compose

services:
  my_agent:
    image: your-image-name:latest
    environment:
      WORKSPACE_REPO: https://github.com/your-org/your-agent-repo
      OPENAI_API_KEY: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      # ANTHROPIC_API_KEY: sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
      # DISCORD_BOT_TOKEN: your-discord-bot-token
      GATEWAY_TOKEN: my-secret-token
      OPENCLAW_HOME: /data/openclaw
      # ALLOWED_ORIGINS: "http://localhost:3349,https://myhost.example.com"
      # SYNC_MODE: "true"
    ports:
      - "3349:3000"
    volumes:
      - openclaw_agent_state:/data/openclaw
    tty: true
    stdin_open: true

volumes:
  openclaw_agent_state:

⁠Factory Reset

If you need to start completely fresh, stop the container and delete the volume. Be careful — this is a full factory reset that deletes all session history, memory, runtime config changes, and any skills or plugins added via the UI.

docker stop my_agent && docker rm my_agent
docker volume rm openclaw_agent_state

Since all credentials are set via env vars, you don't need to re-run onboarding after a reset — just start the container again.

⁠Links

• OpenClaw Documentation⁠
• Source & Dockerfile⁠