OpenClaw team repo development + Multi-env dockerized deploy

[ebon widget]

So, on my team we want to have a repo for tracking a openclaw bot that we will have dockerized and deployed later on. We need to keep track of the core stuff of the bot like it's configs, flows, skills, etc.

We might want to deploy different bots per environment (production, staging, etc) so we will need .env files to choose what the bot will use on each environment and so on.

Whats the best template on github for approaches like this ? Is there any official or recommended repo template for this ?

[lost perch]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[eager obsidian]

No single “official OpenClaw bot repo template” exists yet, but there is a pretty clear recommended pattern: treat your agent workspace as the repo (that’s where your skills + “mind” files live), and keep the state dir (credentials/sessions/etc.) out of Git.

Recommended repo approach (works great for teams)

Put these in Git (your workspace repo):

• AGENTS.md, SOUL.md, USER.md, TOOLS.md (team-shared behavior + instructions)
• memory/ + memory.md (if you want shared memory; many teams keep it minimal)
• skills/ (your custom skills; ClawHub installs to ./skills by default)
• README.md + any internal docs (runbooks, “how we deploy”, etc.)

Do not commit anything under ~/.openclaw/ (that’s config/credentials/sessions). Docs explicitly recommend keeping the workspace in a private repo and backing up state separately:

• Agent workspace: https://docs.openclaw.ai/concepts/agent-workspace
• Backup strategy (FAQ): https://docs.openclaw.ai/help/faq#whats-the-recommended-backup-strategy

A simple workspace-repo tree that maps well to OpenClaw:

my-openclaw-workspace/

  README.md
  AGENTS.md
  SOUL.md
  USER.md
  TOOLS.md
  memory/
  skills/
  deploy/
    docker-compose.yml
  .env.example
  .gitignore

Multi-environment (staging/prod) recommendations

For “different bots per environment”, the cleanest setup is usually one Gateway per env (separate container + separate persisted state volume), because that naturally isolates:

• Discord/Telegram tokens

• OAuth/API credentials
• session history + cron state

On a single host you can also use profiles (OPENCLAW_PROFILE / --profile) so each env gets its own state directory by default.

For env vars + .env behavior, the FAQ has the exact precedence rules (OpenClaw loads .env from cwd and also ~/.openclaw/.env, and neither overrides already-set env vars):

• https://docs.openclaw.ai/help/faq#env-vars-and-env-loading

Docker: start from the official Docker flow

Even if you don’t use the upstream repo directly, it’s the best reference for how the containerized Gateway is expected to run:

• Docker guide: https://docs.openclaw.ai/install/docker

If you want, share:

1. which surface(s) you’re deploying (Discord only? Discord+Telegram?), and
2. whether you plan to run two containers (prod/staging) or one container with multiple agents,
   and I’ll suggest a concrete compose/layout pattern for your repo.

[ebon widget]

1. We will do Discord and Slack for now. I already have the slack app bot and app tokens fo slack and i know how to set up for discord too
2. We will run two separate containers. Each openclaw instance will handle the environments separately and access different data that never has to be mixed.

So, this repo has to also let us develop locally, mount the container on the desired env (with one .env.production or .env.staging, or .env.local, or just .env etc), be able to work on any IDE and the container to reflect the changes accordingly.

So if someone modifies something in the openclaw.json i shoudl be able to pull and run locally with their changes for example in case they modified something, and so on

[ebon widget]

@eager obsidian help here

[eager obsidian]

Benja — for this use case there isn’t a single “official GitHub template repo” yet, but there is a recommended pattern that works really well for teams:

1) Make your repo the workspace repo (skills + “mind”), not the state dir

OpenClaw’s workspace is exactly where you want to version control things like skills and your team’s operating rules:

• AGENTS.md, SOUL.md, USER.md, TOOLS.md
• skills/ (your custom skills)
• optionally some curated memory/ docs (team runbooks, etc.)

Docs: https://docs.openclaw.ai/concepts/agent-workspace
And the key rule: do not commit ~/.openclaw/ (credentials/sessions/tokens).

2) For staging/prod: run separate instances (recommended) using profiles or separate state dirs

Multi-env is basically “multiple gateways” isolation. This doc is the playbook:
https://docs.openclaw.ai/gateway/multiple-gateways

Isolation checklist from docs (the important bits):

• OPENCLAW_CONFIG_PATH (per env)
• OPENCLAW_STATE_DIR (per env)
• agents.defaults.workspace (per env)
• gateway.port (per env)

3) Docker/Compose: keep workspace repo mounted, keep state per env in volumes

The official Docker flow is here (good reference): https://docs.openclaw.ai/install/docker

A common Compose layout is:

• mount your repo into the container as the workspace (read-only is fine if you don’t want it writing)
• give each env its own persisted state volume/dir
• use --env-file / env_file: for staging vs prod without committing secrets

Also relevant: OpenClaw .env loading rules + precedence:
https://docs.openclaw.ai/help/faq#env-vars-and-env-loading

---

If you answer these 2 questions, I can suggest a concrete repo layout + compose pattern:

1. Which surfaces are you deploying (Discord only, or Discord+Telegram+…)?
2. Do you want two separate bots (staging/prod) or one bot with multiple agents/routing?

[ebon widget]

1. We will do Discord and Slack for now. I already have the slack app bot and app tokens fo slack and i know how to set up for discord too
2. We will run two separate containers. Each openclaw instance will handle the environments separately and access different data that never has to be mixed.

So, this repo has to also let us develop locally, mount the container on the desired env (with one .env.production or .env.staging, or .env.local, or just .env etc), be able to work on any IDE and the container to reflect the changes accordingly.

So if someone modifies something in the openclaw.json i shoudl be able to pull and run locally with their changes for example in case they modified something, and so on

[eager obsidian]

Given your constraints (Discord + Slack, two fully isolated instances, git-tracked config/skills, local dev with live changes), here’s the cleanest pattern I’ve seen work.

Repo layout (git-tracked “core”, no secrets)

Make the repo contain config + skills + agent instructions, and keep secrets + state out of git:

openclaw-bot/
  config/
    openclaw.base.json5
    openclaw.staging.json5
    openclaw.production.json5

  skills/
    ...your custom skills...

  AGENTS.md

  SOUL.md
  USER.md
  TOOLS.md

  deploy/
    docker-compose.yml

  .env.staging.example
  .env.production.example
  .gitignore

Key ideas:

• Config is JSON5 and supports $include, so you can share a base config and only override env-specific bits. (Docs: https://docs.openclaw.ai/gateway/configuration#config-hot-reload — includes are right above that section)
• Use env var substitution for secrets ("${DISCORD_BOT_TOKEN}", etc.). (Docs: https://docs.openclaw.ai/help/environment)

Config files (base + env overrides)

config/openclaw.base.json5 (committed):

{
  agents: {
    defaults: {
      // repo is mounted to /workspace in the container in the example below
      workspace: "/workspace",
    },
  },

  channels: {
    discord: {
      enabled: true,
      token: "${DISCORD_BOT_TOKEN}",
    },

    slack: {
      enabled: true,
      mode: "socket",
      appToken: "${SLACK_APP_TOKEN}",
      botToken: "${SLACK_BOT_TOKEN}",
    },
  },
}

Then env-specific files (committed) just include base + override what differs:

config/openclaw.staging.json5

{
  $include: "./openclaw.base.json5",
  gateway: { port: 18789 },
  identity: { name: "YourBot (staging)" },
}

config/openclaw.production.json5

{
  $include: "./openclaw.base.json5",
  gateway: { port: 18820 },
  identity: { name: "YourBot" },
}

Slack/Discord refs:

• Slack tokens/keys: https://docs.openclaw.ai/channels/slack
• Discord token/key: https://docs.openclaw.ai/channels/discord

Docker Compose: two services, two state volumes, two env files

deploy/docker-compose.yml (example):

services:
  openclaw-staging:
    image: openclaw:local
    working_dir: /workspace
    environment:
      OPENCLAW_STATE_DIR: /state
      OPENCLAW_CONFIG_PATH: /workspace/config/openclaw.staging.json5
    env_file:
      - ../.env.staging

    volumes:
      - ../:/workspace:rw
      - openclaw_state_staging:/state
    ports:
      - "18789:18789"

  openclaw-production:
    image: openclaw:local
    working_dir: /workspace
    environment:
      OPENCLAW_STATE_DIR: /state
      OPENCLAW_CONFIG_PATH: /workspace/config/openclaw.production.json5
    env_file:
      - ../.env.production
    volumes:

      - ../:/workspace:rw
      - openclaw_state_production:/state
    ports:
      - "18820:18820"

volumes:
  openclaw_state_staging:
  openclaw_state_production:

Notes:

• Isolation is guaranteed because each container has its own /state volume (= creds/sessions/etc).
• Your repo is bind-mounted, so editing openclaw.*.json5 or skills/ updates immediately.
• OpenClaw supports config hot reload; changes typically apply without restart. Some gateway-level changes force a restart automatically depending on gateway.reload.mode. (Docs: https://docs.openclaw.ai/gateway/configuration#config-hot-reload)

Local dev workflow (what you asked for)