OC project root directory | Friends of the Crustacean 🦞🤝 | Page 1

wicked talon Apr 27, 2026, 8:52 AM

#

I am using latest OpenClaw 2026.4.23 (a979721). I don't like the fact, that Openclaw is storing it's main configuration in ~/.openclaw.

Question: During setup, can I configure an entirely different program root directory, for example on a dedicated mounted drive? I want NOTHING in .openclaw, no configs, no workspaces, nothing.

The idea is, that I can migrate the entire openclaw instance all at once by just halt the gateway, umount the disk and re-mount on an other server as root directory for another openclaw instance.

tacit houndBOT Apr 27, 2026, 8:52 AM

#

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

wicked talon Apr 27, 2026, 8:54 AM

#

In addition, I don't want to use symlinks, neither soft or hard.

grim lichenBOT Apr 27, 2026, 8:54 AM

#

Yes — for your use case, use OPENCLAW_STATE_DIR, ideally with an explicit OPENCLAW_CONFIG_PATH.

For a mounted root like /mnt/openclaw-instance:

export OCROOT=/mnt/openclaw-instance
export OPENCLAW_STATE_DIR="$OCROOT"
export OPENCLAW_CONFIG_PATH="$OCROOT/openclaw.json"

openclaw setup --workspace "$OCROOT/workspace"
openclaw gateway install --force
openclaw gateway restart
openclaw status

That moves OpenClaw-owned state to the mount:

#

config: $OCROOT/openclaw.json
credentials/auth/sessions/logs/skills/etc: under $OCROOT/
workspace: $OCROOT/workspace

OPENCLAW_CONFIG_PATH is technically optional when OPENCLAW_STATE_DIR is set, but I’d set it explicitly to avoid profile/default-path confusion.

One nuance: OPENCLAW_HOME=/somewhere also exists, but its default state dir becomes /somewhere/.openclaw. If you want the mount itself to be the root with no .openclaw subdir, use OPENCLAW_STATE_DIR=/mnt/openclaw-instance.

For daemon/systemd/launchd installs, make sure those env vars are present in the service environment — don’t rely on ~/.openclaw/.env for this, since that’s exactly the default path you’re avoiding.

Docs: https://docs.openclaw.ai/help/environment, https://docs.openclaw.ai/install/migrating, https://docs.openclaw.ai/concepts/agent-workspace

#

Yep — no symlinks needed.

Use real paths via env vars:

export OCROOT=/mnt/openclaw-instance
export OPENCLAW_STATE_DIR="$OCROOT"
export OPENCLAW_CONFIG_PATH="$OCROOT/openclaw.json"

openclaw setup --workspace "$OCROOT/workspace"
openclaw gateway install --force
openclaw gateway restart

That should keep OpenClaw’s own config/state/workspace out of ~/.openclaw.

Important nuance: the OS service registration may still live in the OS-standard place, e.g. systemd user units under ~/.config/systemd/user or launchd plists on macOS. But OpenClaw’s instance data can live entirely on your mounted drive.

#

After moving to another server: install OpenClaw there, mount the disk at the same path, set the same env vars, then run:

openclaw gateway install --force
openclaw doctor
openclaw gateway restart

Docs: https://docs.openclaw.ai/help/environment

wicked talon Apr 27, 2026, 8:57 AM

#

I not get it, I am used to install a fresh openclaw instance using "sudo npm install -g openclaw@latest" followed by an "openclaw onboard --install-daemon", does above env-setting still apply? I mean shall I set the env variables prior to the npm install and the nvm stuff or the onboard install-daemon will use then the OPENCLAW_STATE_DIR of my choice?

grim lichenBOT Apr 27, 2026, 8:58 AM

#

Yes — set the env vars before openclaw onboard --install-daemon, not before npm install.

npm install -g openclaw@latest just installs the CLI/package. The OpenClaw paths are resolved when you run OpenClaw commands like onboard, setup, gateway install, doctor, etc.

Suggested fresh install flow:

sudo npm install -g openclaw@latest

sudo mkdir -p /mnt/openclaw-instance
sudo chown -R "$USER:$USER" /mnt/openclaw-instance

export OCROOT=/mnt/openclaw-instance
export OPENCLAW_STATE_DIR="$OCROOT"
export OPENCLAW_CONFIG_PATH="$OCROOT/openclaw.json"

#

openclaw onboard --install-daemon --workspace "$OCROOT/workspace"

Important bit: include --workspace "$OCROOT/workspace". OPENCLAW_STATE_DIR moves state/config, but the workspace default is still home-based unless you set it during onboard/config.

The daemon install should capture OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH into the service environment. Afterward verify with:

openclaw status

And if on Linux:

systemctl --user cat openclaw-gateway

#

You should see the chosen state/config paths in the unit/env file.

wicked talon Apr 27, 2026, 9:06 AM

#

Got that, I just rejected my own idea, I not want to mess around with local systemd defaults, I will just continue to tarball my ~/.openclaw directory and workspaces manually prior to transferring them offshore.

grim lichenBOT Apr 27, 2026, 9:06 AM

#

That’s honestly the least surprising route 👍

Safest migration pattern:

openclaw gateway stop

cd ~
tar -czf openclaw-backup.tgz .openclaw
# plus any workspace dirs if you moved them outside ~/.openclaw
tar -czf openclaw-workspaces.tgz path/to/workspace1 path/to/workspace2

On the new machine: install OpenClaw, extract with the same user/ownership, then:

#

openclaw doctor
openclaw gateway restart
openclaw status

Key thing: copy the whole state dir, not just openclaw.json, because auth profiles, sessions, credentials, channel state, and skills live under ~/.openclaw.

Docs: https://docs.openclaw.ai/install/migrating

If this answers it, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow indexes it for the next person. 🦐

#OC project root directory