@ks-ai/kclaw-container-bridge

An OpenClaw plugin that bridges the gap between host machine paths and Docker container paths for KClaw instances.

When running an AI coding assistant inside a Docker container, the AI perceives container-internal paths (e.g. /workspace) while users naturally refer to their host machine paths (e.g. /home/user/my-project). This mismatch causes the AI to misinterpret file locations.

This plugin injects a path mapping table into the system prompt before each request, enabling the AI to correctly translate and operate on file paths.

Installation

Option 1: OpenClaw CLI (recommended)

npx openclaw plugins install @ks-ai/kclaw-container-bridge

Or if you have the openclaw CLI installed globally:

openclaw plugins install @ks-ai/kclaw-container-bridge

Option 2: Manual

Copy the plugin folder into your OpenClaw project's extensions/ directory:

/path/to/openclaw/extensions/kclaw-container-bridge/

Ensure the folder contains package.json and openclaw.plugin.json.

Configuration

Add the plugin entry to your openclaw.json:

{
  "plugins": {
    "entries": {
      "kclaw-container-bridge": {
        "enabled": true,
        "config": {
          "mappings": [
            {
              "host": "/home/user/code/my-app",
              "container": "/workspace"
            },
            {
              "host": "/home/user/data",
              "container": "/mnt/data"
            }
          ]
        }
      }
    }
  }
}

Multiple mount points are supported. The plugin always resolves using the most specific (longest) matching prefix.

Environment Variable Fallback

If no mappings are configured in openclaw.json, the plugin falls back to environment variables:

| Variable | Description | |:---|:---| | KCLAW_PATH_MAPPINGS | JSON array of { host, container } objects | | KCLAW_HOST_WORKSPACE | Single host workspace path | | KCLAW_CONTAINER_WORKSPACE | Corresponding container path (default: /workspace) |

Example:

export KCLAW_PATH_MAPPINGS='[{"host":"/home/user/project","container":"/workspace"}]'

How It Works

1. Load configuration — reads mappings from openclaw.json plugin config, falls back to environment variables.
2. Build context — generates a Markdown path mapping table along with operational guidelines for the AI.
3. Inject into prompt — uses the before_prompt_build hook to append the context block to the system prompt before every request.

License

MIT