Summary

• Problem: _clawdock_compose() only passes -f docker-compose.yml, ignoring docker-compose.extra.yml that docker-setup.sh generates for persistent home volumes (OPENCLAW_HOME_VOLUME) and custom mounts (OPENCLAW_EXTRA_MOUNTS).
• Why it matters: All clawdock-* commands (start, stop, shell, etc.) silently drop volume mounts, making the helper script useless for setups with persistent home volumes.
• What changed: _clawdock_compose() now checks for docker-compose.extra.yml and includes it via an additional -f flag when present.
• What did NOT change (scope boundary): No changes to docker-setup.sh, docker-compose.yml, or any other helper functions.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: 2026.2.14 clawdock helper script ignores docker-compose.extra.yml when starting #17083

User-visible / Behavior Changes

clawdock-start (and all other clawdock-* commands) now correctly mount volumes defined in docker-compose.extra.yml, matching the behavior of docker-setup.sh.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Any (Docker host)
• Runtime/container: Docker with docker-compose
• Relevant config: OPENCLAW_HOME_VOLUME set, docker-setup.sh previously run

Steps

1. Set OPENCLAW_HOME_VOLUME=openclaw-home
2. Run ./docker-setup.sh (creates docker-compose.extra.yml with volume mount)
3. source scripts/shell-helpers/clawdock-helpers.sh
4. Run clawdock-start
5. Run docker inspect openclaw-openclaw-gateway-1 | grep -A5 Mounts

Expected

Container has the home volume mounted at /home/node.

Actual (before fix)

"Volumes": null — no volume mounted.

Evidence

• Manual inspection of _clawdock_compose() output with and without docker-compose.extra.yml

Human Verification (required)

• Verified scenarios: Confirmed _clawdock_compose generates correct docker compose -f ... -f ... args when extra file exists, and falls back to single -f when it does not.
• Edge cases checked: Missing docker-compose.extra.yml (no-op, backward compatible).
• What I did not verify: Full Docker environment end-to-end (no Docker available in CI).

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert the single commit.
• Files/config to restore: scripts/shell-helpers/clawdock-helpers.sh
• Known bad symptoms: If docker-compose.extra.yml is malformed, docker compose will report a parse error (same as running docker-setup.sh output manually).

Risks and Mitigations

None — the extra file is only included if it exists, and Docker Compose validates it on load.

🤖 Generated with Claude Code

Greptile Summary

Fixes _clawdock_compose() to include docker-compose.extra.yml (when present) via an additional -f flag, matching the behavior of docker-setup.sh. Previously, all clawdock-* helper commands silently dropped volume mounts defined in the extra compose file (generated for OPENCLAW_HOME_VOLUME and OPENCLAW_EXTRA_MOUNTS).

• The fix uses a bash array to conditionally build compose arguments, checking for docker-compose.extra.yml existence before including it.
• All helper commands (clawdock-start, clawdock-stop, clawdock-shell, etc.) route through _clawdock_compose(), so this single change fixes all of them.
• Backward compatible: when the extra file doesn't exist, behavior is identical to before.

Confidence Score: 5/5

• This PR is safe to merge — it's a minimal, backward-compatible bug fix with no risk of regression.
• The change is a 4-line addition to a single shell function. It conditionally includes an extra compose file only when the file exists, which is the correct behavior matching docker-setup.sh. The bash syntax is correct, the logic is straightforward, and there are no edge cases that could cause issues. When the extra file doesn't exist, behavior is unchanged.
• No files require special attention.

_{Last reviewed commit: bb0a9ef}