PR #68702: fix(docker): enable host.docker.internal for local providers

• Repository: openclaw/openclaw
• Author: skolez
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68702

Description (problem / solution / changelog)

Summary

• Problem: When OpenClaw runs in a container, the onboarding wizard prompts for a base URL (e.g. for LM Studio or Ollama) and users naturally enter http://127.0.0.1:1234 / http://127.0.0.1:11434. Inside the container that resolves to the container itself, not the host, so every model call silently fails.
• Why it matters: Local-provider users on Docker hit a dead end during onboarding with no in-product hint about why.
• What changed: Mapped host.docker.internal → host-gateway in the bundled docker-compose.yml (so the alias works on Linux, not just Docker Desktop) and added a "Connecting to host services" subsection to docs/install/docker.md documenting the correct base URLs for LM Studio and Ollama.
• What did NOT change (scope boundary): No changes to the LM Studio or Ollama setup wizards, no plugin SDK additions, no auto-detection logic. Issue suggested wizard auto-detection as one option; kept this PR docs+compose-only as the smallest defensible fix. Wizard hint can be a follow-up if maintainers want it.

AI-assisted (Claude). Lightly tested locally — verified extra_hosts syntax against existing repo precedent (extensions/qa-lab/src/docker-harness.ts); did not stand up a full Docker rebuild on Linux to confirm host-gateway resolution end-to-end.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• 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 #68684
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: docker-compose.yml did not declare extra_hosts: ["host.docker.internal:host-gateway"], so on Linux the alias does not resolve (Docker Desktop sets it implicitly; Docker Engine does not). The Docker install docs also did not call out the container-vs-host loopback gotcha for local AI providers, so users entering 127.0.0.1 had no hint why their setup silently failed.
• Missing detection / guardrail: The onboarding wizard for LM Studio/Ollama does not detect container environments and warn about loopback. Out of scope here; deferred to a possible follow-up.

Regression Test Plan (if applicable)

N/A — no runtime/test code is touched. The change is a YAML config addition and a docs section.

User-visible / Behavior Changes

• Inside the bundled OpenClaw Docker Compose stack, http://host.docker.internal:<port> now resolves to the host gateway on Linux (it already worked on Docker Desktop). Users following the docs can now point LM Studio/Ollama setup at the correct URL on any platform.
• Docs gain a new "Connecting to host services (LM Studio, Ollama, etc.)" subsection under docs/install/docker.md.

Diagram (if applicable)

Before (Linux, Docker Engine):
[wizard] -> http://127.0.0.1:11434 -> container loopback (no Ollama) -> silent failure
[wizard] -> http://host.docker.internal:11434 -> name resolution failure

After:
[wizard] -> http://host.docker.internal:11434 -> host gateway -> host Ollama -> 200 OK

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No (only adds a name resolution alias inside the container)
• Command/tool execution surface changed? No
• Data access scope changed? No

extra_hosts: ["host.docker.internal:host-gateway"] only resolves a hostname to the existing host gateway IP; it does not open new ports, expose new services, or grant new privileges. Same alias Docker Desktop already provides implicitly.

Repro + Verification

Environment

• OS: Linux Docker Engine host (issue reporter's environment); also Docker Desktop on macOS/Windows
• Runtime/container: bundled openclaw-gateway container
• Model/provider: LM Studio, Ollama (host-side)
• Integration/channel (if any): N/A
• Relevant config (redacted): default docker-compose.yml

Steps

1. Run ./scripts/docker/setup.sh on a Linux Docker Engine host.
2. During onboarding, configure LM Studio (or Ollama) and enter http://127.0.0.1:1234 (or http://127.0.0.1:11434).
3. Send a message via any channel.

Expected

• After this PR: docs guide users to enter http://host.docker.internal:<port> instead, and that hostname resolves correctly on both Docker Desktop and Linux Docker Engine.

Actual

• Before this PR on Linux: entering host.docker.internal gave name resolution errors; entering 127.0.0.1 reached the container loopback (no provider). Either way, model calls silently failed.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Reproduction and root cause are well-documented in #68684 (filed by @safrano9999). No new automated coverage added — this PR is config + docs only.

Human Verification (required)

• Verified scenarios:
  • Diff review of docker-compose.yml, docs/install/docker.md, and CHANGELOG.md.
  • Confirmed extra_hosts: ["host.docker.internal:host-gateway"] matches the syntax already in use elsewhere in this repo (extensions/qa-lab/src/docker-harness.ts:125, src/agents/sandbox/config-hash.test.ts:17).
  • Confirmed openclaw-cli shares the gateway's network namespace (network_mode: "service:openclaw-gateway"), so adding extra_hosts only on the gateway service is sufficient.
• Edge cases checked:
  • macOS / Windows Docker Desktop: host.docker.internal already resolves implicitly; adding extra_hosts is a harmless no-op.
  • Linux Docker Engine: host-gateway magic value is supported since Docker 20.10 (released 2020-12), which is well below the project's existing Docker baseline.
• What I did not verify:
  • Did not stand up a full Linux Docker Engine rebuild end-to-end to confirm name resolution. The compose syntax change is small and matches established repo precedent, so confidence is high but not first-hand validated.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No (no environment variables added)
• Migration needed? No — existing users who already entered the working URL keep working; the new extra_hosts is additive.

Risks and Mitigations

• Risk: Some unusual Docker setups (e.g. ancient Docker Engine < 20.10 without host-gateway magic value) might fail to start the container with the new extra_hosts.
  • Mitigation: Docker 20.10 was released in Dec 2020; OpenClaw's bundled tooling already assumes a modern Docker. If this becomes an issue, the line can be made conditional via a Compose override.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docker-compose.yml (modified, +6/-0)
• docs/install/docker.md (modified, +26/-0)