Skip to content
BSWEN
Blog

How to Migrate OpenClaw Environment Variables from Legacy Names

Cowrie
Cowrie
Dev @ Bswen

I upgraded OpenClaw last week and my CLI agent stopped working. It kept starting with default settings instead of my configured values. No error messages. No warnings. Just silent failure.

After hours of debugging, I discovered the culprit: OpenClaw had renamed all environment variable prefixes from CLAWDBOT_* and MOLTBOT_* to OPENCLAW_*. My old variables were being silently ignored.

The Problem

I ran openclaw start after the upgrade and immediately noticed something was wrong:

Terminal Output
$ openclaw start
[INFO] Starting OpenClaw CLI agent...
[INFO] Loading configuration...
[WARN] No API key found, using default empty value
[INFO] Agent started with default settings

But my .env file clearly had the API key set:

.env (before fix)
CLAWDBOT_API_KEY=sk-proj-xxxxx
CLAWDBOT_MEMORY_PATH=/data/memory
MOLTBOT_SKILLS_DIR=/skills

The agent couldn’t see any of these values. It was as if my configuration had vanished.

The Root Cause

A Reddit thread titled “If you haven’t updated openclaw yet, don’t. Read this first.” explained everything:

  • OpenClaw unified all environment variable prefixes to OPENCLAW_*
  • CLAWDBOT_* variables are no longer recognized
  • MOLTBOT_* variables are no longer recognized
  • There’s no backward compatibility layer
  • No warning is shown when legacy variables are ignored

The agent silently starts with defaults when it doesn’t find the new variable names. This is a breaking change with zero deprecation warnings.

Why This Is Dangerous

The silent failure mode is the worst part. Consider what happens:

Configuration Impact Diagram
┌─────────────────────────────────────────────────────────────┐
│                    Your Configuration                        │
├─────────────────────────────────────────────────────────────┤
│  CLAWDBOT_API_KEY = "sk-prod-key"                           │
│  CLAWDBOT_ENDPOINT = "https://api.production.com"          │
│  CLAWDBOT_MEMORY_PATH = "/data/memory"                      │
└─────────────────────────────────────────────────────────────┘
                           │
                           │ OpenClaw upgrade
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              What OpenClaw Actually Sees                     │
├─────────────────────────────────────────────────────────────┤
│  OPENCLAW_API_KEY = ""          (not found, default empty)  │
│  OPENCLAW_ENDPOINT = ""         (not found, default empty)  │
│  OPENCLAW_MEMORY_PATH = ""      (not found, default empty)  │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   Consequences                               │
├─────────────────────────────────────────────────────────────┤
│  ✗ API calls fail with authentication errors                │
│  ✗ Memory and skills not loaded                              │
│  ✗ Agent behaves like fresh installation                     │
│  ✗ Production deployment silently broken                     │
└─────────────────────────────────────────────────────────────┘

This is especially dangerous in production environments where the agent might appear to run normally while actually using incorrect configuration.

Finding All Legacy Variables

The first step is discovering where you’ve defined these variables. They’re probably scattered across multiple files:

find-legacy-vars.sh
# Search for CLAWDBOT_ variables
grep -r "CLAWDBOT_" ~/.env ~/.*rc ~/.*profile 2>/dev/null
grep -r "CLAWDBOT_" .env docker-compose*.yml 2>/dev/null


# Search for MOLTBOT_ variables
grep -r "MOLTBOT_" ~/.env ~/.*rc ~/.*profile 2>/dev/null
grep -r "MOLTBOT_" .env docker-compose*.yml 2>/dev/null


# Check systemd service files
grep -r "CLAWDBOT_\|MOLTBOT_" /etc/systemd/system/ 2>/dev/null

I found variables in five different locations:

My Search Results
/home/user/.env:CLAWDBOT_API_KEY=sk-xxxxx
/home/user/.bashrc:export CLAWDBOT_API_KEY=sk-xxxxx
/home/user/projects/openclaw/.env:CLAWDBOT_MEMORY_PATH=/data/memory
/home/user/projects/openclaw/docker-compose.yml:  - CLAWDBOT_API_KEY=sk-xxxxx
/etc/systemd/system/openclaw.service:Environment="CLAWDBOT_API_KEY=sk-xxxxx"

Each location requires a separate fix.

The Migration Process

Step 1: Update .env Files

migrate-env.sh
# Rename CLAWDBOT_ to OPENCLAW_
sed -i 's/CLAWDBOT_/OPENCLAW_/g' .env


# Rename MOLTBOT_ to OPENCLAW_
sed -i 's/MOLTBOT_/OPENCLAW_/g' .env


# For macOS (requires backup extension)
sed -i '' 's/CLAWDBOT_/OPENCLAW_/g' .env
sed -i '' 's/MOLTBOT_/OPENCLAW_/g' .env

My .env file after migration:

.env (after fix)
OPENCLAW_API_KEY=sk-proj-xxxxx
OPENCLAW_MEMORY_PATH=/data/memory
OPENCLAW_SKILLS_DIR=/skills

Step 2: Update Shell Configuration Files

migrate-shell.sh
# Update .bashrc
sed -i 's/CLAWDBOT_/OPENCLAW_/g' ~/.bashrc
sed -i 's/MOLTBOT_/OPENCLAW_/g' ~/.bashrc


# Update .zshrc
sed -i 's/CLAWDBOT_/OPENCLAW_/g' ~/.zshrc
sed -i 's/MOLTBOT_/OPENCLAW_/g' ~/.zshrc


# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

Don’t forget to reload your shell after making these changes.

Step 3: Update Docker Compose Files

The Docker compose syntax is slightly different. Here’s the before and after:

docker-compose.yml (before)
services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - CLAWDBOT_API_KEY=your-key
      - CLAWDBOT_MEMORY_PATH=/data/memory
      - MOLTBOT_SKILLS_DIR=/skills
docker-compose.yml (after)
services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_API_KEY=your-key
      - OPENCLAW_MEMORY_PATH=/data/memory
      - OPENCLAW_SKILLS_DIR=/skills

Step 4: Update Systemd Service Files

If you’re running OpenClaw as a systemd service:

migrate-systemd.sh
# Edit the service file
sudo systemctl edit openclaw


# Replace CLAWDBOT_ with OPENCLAW_
# Replace MOLTBOT_ with OPENCLAW_


# Reload systemd
sudo systemctl daemon-reload


# Restart the service
sudo systemctl restart openclaw

Verification

After migration, verify that everything is working:

verify-migration.sh
# Check that no legacy variables remain
grep -r "CLAWDBOT_\|MOLTBOT_" .env . 2>/dev/null | grep -v "node_modules"


# Verify OPENCLAW_ variables are set
env | grep OPENCLAW_


# Test agent starts correctly
openclaw --version
openclaw config show

The openclaw config show command should display your configured values instead of defaults.

Common Mistakes to Avoid

I made several mistakes during my migration:

Mistake 1: Partial migration - I updated .env but forgot .bashrc. The agent still couldn’t find the API key.

Mistake 2: Not reloading shell - After editing .bashrc, I didn’t run source ~/.bashrc. The changes weren’t active.

Mistake 3: Forgetting Docker - My Docker containers were still using old environment variables until I recreated them.

Mistake 4: Missing CI/CD - My GitHub Actions workflow also had hardcoded CLAWDBOT_ secrets that needed updating.

The Bigger Picture

This experience highlighted a common pattern in open-source projects: breaking changes without proper migration paths. As user yixn_io noted on Reddit:

“The env var rename is the one that catches everyone. Variables are baked into multiple locations: .env files, systemd units, Docker compose files. New version silently ignores old variable names.”

A better approach would have been:

  1. Deprecation warnings - Log a warning when legacy variables are detected
  2. Migration script - Provide an automated tool to update configuration files
  3. Documentation - Clear upgrade notes in the changelog
  4. Backward compatibility - Support both old and new names temporarily

What I Learned

Before upgrading any self-hosted tool:

  1. Check the changelog - Look for breaking changes, especially configuration changes
  2. Document your configuration - Know where all your environment variables are defined
  3. Test in staging - Never upgrade production directly
  4. Have a rollback plan - Keep the previous version available

For OpenClaw specifically, the migration checklist is:

  • Search all .env files for legacy variable names
  • Update .bashrc, .zshrc, .profile files
  • Check Docker compose and Kubernetes manifest files
  • Review systemd service unit files
  • Update CI/CD pipeline configurations
  • Verify environment variables are recognized
  • Test agent starts with correct configuration
  • Document the change for team members

This type of breaking change is common in rapidly evolving open-source projects. Similar issues have occurred with:

  • Docker - The transition from DOCKER_* to DOCKER_HOST, DOCKER_TLS_VERIFY etc.
  • Kubernetes - API version deprecations requiring manifest updates
  • Terraform - Provider attribute renames between versions

The solution is always the same: search comprehensively, update systematically, verify thoroughly.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

The OpenClaw environment variable migration is straightforward once you understand the problem. The challenge is discovery - finding all the places where you’ve defined these variables. Take the time to search thoroughly, update everything at once, and verify before considering the migration complete.

Comments

Tags: