fix(clawdock): load compose override file

Load `docker-compose.override.yml` when ClawDock builds its explicit Docker Compose file list, preserving standard Compose override behavior while keeping `docker-compose.extra.yml` as the final OpenClaw overlay.

Update Docker docs so manual Compose users include the same override order, and keep the regression test for the generated `_clawdock_compose` arguments.

Fixes #49909.
Thanks @spacegeologist.

Co-authored-by: zhengzuo0-ai <zheng.zuo0@gmail.com>

docs/install/docker.md

@@ -109,7 +109,9 @@ docker compose up -d openclaw-gateway
 <Note>
 Run `docker compose` from the repo root. If you enabled `OPENCLAW_EXTRA_MOUNTS`
 or `OPENCLAW_HOME_VOLUME`, the setup script writes `docker-compose.extra.yml`;
-include it with `-f docker-compose.yml -f docker-compose.extra.yml`.
+include it after any standard override file, for example
+`-f docker-compose.yml -f docker-compose.override.yml -f docker-compose.extra.yml`
+when both override files exist.
 </Note>
 
 <Note>

scripts/clawdock/README.md

@@ -142,12 +142,13 @@ The Docker setup uses three config files on the host. The container never stores
 ### Docker Files
 
 | File                          | Purpose                                                                        |
-| -------------------------- | -------------------------------------------------------------------------- |
+| ----------------------------- | ------------------------------------------------------------------------------ |
 | `Dockerfile`                  | Builds the `openclaw:local` image (Node 22, pnpm, non-root `node` user)        |
 | `docker-compose.yml`          | Defines `openclaw-gateway` and `openclaw-cli` services, bind-mounts, ports     |
+| `docker-compose.override.yml` | Standard Docker Compose overrides — auto-loaded by ClawDock helpers if present |
+| `docker-compose.extra.yml`    | Additional overrides — loaded after the standard override if present           |
 | `scripts/docker/setup.sh`     | First-time setup — builds image, creates `.env` from `.env.example`            |
 | `.env.example`                | Template for `<project>/.env` with all supported vars and docs                 |
-| `docker-compose.extra.yml` | Optional overrides — auto-loaded by ClawDock helpers if present            |
 
 ### Config Files
 

scripts/clawdock/clawdock-helpers.sh

@@ -151,6 +151,9 @@ _clawdock_ensure_dir() {
 _clawdock_compose() {
   _clawdock_ensure_dir || return 1
   local compose_args=(-f "${CLAWDOCK_DIR}/docker-compose.yml")
+  if [[ -f "${CLAWDOCK_DIR}/docker-compose.override.yml" ]]; then
+    compose_args+=(-f "${CLAWDOCK_DIR}/docker-compose.override.yml")
+  fi
   if [[ -f "${CLAWDOCK_DIR}/docker-compose.extra.yml" ]]; then
     compose_args+=(-f "${CLAWDOCK_DIR}/docker-compose.extra.yml")
   fi

test/scripts/clawdock-helpers.test.ts

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+describe("scripts/clawdock/clawdock-helpers.sh", () => {
+  it("loads the standard docker-compose.override.yml before ClawDock extra overrides", async () => {
+    const tempDir = await mkdtemp(path.join(tmpdir(), "openclaw-clawdock-"));
+    try {
+      const projectDir = path.join(tempDir, "project");
+      const binDir = path.join(tempDir, "bin");
+      const argsFile = path.join(tempDir, "docker-args.txt");
+      await mkdir(projectDir);
+      await mkdir(binDir);
+      await writeFile(path.join(projectDir, "docker-compose.yml"), "services: {}\n");
+      await writeFile(path.join(projectDir, "docker-compose.override.yml"), "services: {}\n");
+      await writeFile(path.join(projectDir, "docker-compose.extra.yml"), "services: {}\n");
+      await writeFile(
+        path.join(binDir, "docker"),
+        `#!/usr/bin/env bash
+printf '%s\\n' "$@" > "$CLAWDOCK_DOCKER_ARGS_FILE"
+`,
+        { mode: 0o755 },
+      );
+
+      await execFileAsync(
+        "bash",
+        ["-c", "source scripts/clawdock/clawdock-helpers.sh; _clawdock_compose config"],
+        {
+          cwd: repoRoot,
+          env: {
+            ...process.env,
+            CLAWDOCK_DIR: projectDir,
+            CLAWDOCK_DOCKER_ARGS_FILE: argsFile,
+            HOME: path.join(tempDir, "home"),
+            PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
+          },
+        },
+      );
+
+      await expect(readFile(argsFile, "utf8")).resolves.toBe(
+        [
+          "compose",
+          "-f",
+          path.join(projectDir, "docker-compose.yml"),
+          "-f",
+          path.join(projectDir, "docker-compose.override.yml"),
+          "-f",
+          path.join(projectDir, "docker-compose.extra.yml"),
+          "config",
+          "",
+        ].join("\n"),
+      );
+    } finally {
+      await rm(tempDir, { force: true, recursive: true });
+    }
+  });
+});