How to customize OpenClaw prompts, tools, and sandbox behavior

OpenClaw behavior is shaped by workspace files plus gateway config. Workspace files control instructions and memory, while config controls what tools are available, whether web search works, and whether tool execution should move into Docker sandboxes.

Who this is for

• You already have a working OpenClaw install.
• You want to change behavior without patching the OpenClaw source code.
• You want a safer execution profile than the default host-only runtime.

What you need before you start

• A configured OpenClaw workspace.
• Docker available if you plan to enable sandboxed execution.
• The OpenClaw source checkout if you want to build the official sandbox image locally.

Step-by-step setup

Step 1: Find the active workspace

Expected result: OpenClaw prints the workspace path, usually ~/.openclaw/workspace.

Step 2: Edit the core workspace files

Use the printed workspace path and update the files that matter most:

The official workspace docs describe these files as the standard control surface:

• AGENTS.md for operating rules and priorities
• SOUL.md for persona, tone, and boundaries
• USER.md for user context
• TOOLS.md for local tool notes and conventions
• HEARTBEAT.md for heartbeat-only checklists

Step 3: Configure web search for the web_search tool

Expected result: OpenClaw stores the provider key in the correct tools.web.search.* config path so web_search can run.

Step 4: Build the default sandbox image if you want the official Docker sandbox

From an OpenClaw source checkout:

Expected result: Docker builds openclaw-sandbox:bookworm-slim.

Step 5: Enable a minimal sandbox profile

This mirrors the minimal enable example from the official sandbox docs and keeps only non-main sessions in sandboxes.

Step 6: Validate the config and inspect the effective sandbox policy

Expected result: the config validates and sandbox explain shows the final mode, scope, workspace access, and any tool restrictions.

Verify it worked

1. openclaw config validate succeeds.
2. openclaw sandbox explain shows the exact effective sandbox policy you intended.
3. web_search has a configured provider if you enabled it with openclaw configure --section web.

Common problems and fixes

The sandbox is enabled, but package installs still fail

The sandbox docs call out three common blockers: docker.network: "none", readOnlyRoot: true, and a non-root container user for package installs.

A skill needs Node or more tools inside the sandbox

Build the more functional common image from a source checkout:

Then point the sandbox image at openclaw-sandbox-common:bookworm-slim.

I changed config, but I do not know which value is actually winning

Use the explicit inspect command:

FAQ

Which files are injected into the agent context automatically?

The context docs list the standard workspace files: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md when present.

Does TOOLS.md control tool availability?

No. The workspace docs say TOOLS.md is guidance only. Actual tool access is controlled by OpenClaw config and tool policy.

Does sandboxing isolate the whole gateway?

No. The sandbox docs explicitly state that the gateway process stays on the host while tool execution moves into isolated containers.

Official sources

• Agent Workspace
• Context
• Web Tools
• Sandboxing
• config CLI
• sandbox CLI