#22344: feat(docker): add pre-built image mode for docker-setup
docs
docker
size: S
Cluster:
Docker Integration and Documentation
## What changed
- Added `OPENCLAW_IMAGE_SOURCE` support in `docker-setup.sh` with interactive prompt for tty (1=local, 2=registry).
- Wired image naming to image source:
- `local` -> `openclaw:local`
- `registry` -> `OPENCLAW_IMAGE` (defaults to `openclaw:latest`)
- Skips `docker build` when `OPENCLAW_IMAGE_SOURCE=registry`; keeps onboarding/composition flow unchanged.
- Persisted new env key in `.env` via `upsert_env`: `OPENCLAW_IMAGE_SOURCE`.
- Updated Docker docs (`docs/install/docker.md`, `docs/zh-CN/install/docker.md`) to document the new option.
- Added regression tests in `src/docker-setup.test.ts` for registry source and `.env` persistence.
## Why this fixes #22316
It enables Docker setup to use a pre-built image from registry instead of forcing a local rebuild, while keeping current local build behavior as the default.
## Tests run
- `pnpm vitest run --config vitest.config.ts src/docker-setup.test.ts`
- `pnpm test src/docker-setup.test.ts`
## Edge cases
- Non-interactive shells default to `local` to avoid blocking prompts in CI.
- `OPENCLAW_IMAGE_SOURCE` only accepts `local` or `registry`; invalid values fail fast with a clear error.
- Custom image tag is supported via `OPENCLAW_IMAGE` when using registry source.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Added `OPENCLAW_IMAGE_SOURCE` environment variable to allow users to choose between building Docker images locally or using pre-built registry images. The implementation includes interactive prompts for TTY sessions and defaults to local builds in non-interactive environments.
- Added `choose_image_source()` function with interactive prompt for image source selection
- Conditional image naming: `registry` source uses `openclaw:latest` by default, `local` uses `openclaw:local`
- Skips docker build step when using registry source
- Persists `OPENCLAW_IMAGE_SOURCE` in `.env` file
- Added comprehensive test coverage for registry source
- Documentation updated in both English and Chinese
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation is clean and well-tested. The logic correctly handles both interactive and non-interactive modes, validates input values, and maintains backwards compatibility by defaulting to local builds. The changes are isolated to Docker setup workflow and include appropriate test coverage.
- No files require special attention
<sub>Last reviewed commit: bdbddc9</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#7986: feature/OPENCLAW_IMAGE
by ozbillwang · 2026-02-03
83.4%
#23313: feat(docker): add optional build-arg OPENCLAW_INSTALL_DOCKER_CLI to...
by zhuxuwei88-bot · 2026-02-22
83.3%
#5866: feat: add optional Docker official repo APT source
by codearranger · 2026-02-01
81.5%
#6698: feat: Add CLI wrapper for Docker integration and update documentation
by barshopen · 2026-02-01
80.8%
#7133: feat: Automated Docker setup with environment-based configuration
by synetalsolutions · 2026-02-02
79.8%
#9999: Docker: fix token mismatch and add dev setup workflow
by benclarkeio · 2026-02-06
78.9%
#15791: Docker: load buildx image and reuse gateway token
by ttulttul · 2026-02-13
78.1%
#4450: fix bug #4366: Error: Config validation failed: plugins.slots.memor...
by tryagain3 · 2026-01-30
77.0%
#9190: feat(docker): Add autonomous container self-restart and runtime pac...
by alexdredmon · 2026-02-05
76.8%
#10174: fix(docker): exclude .env files from Docker build context
by coygeek · 2026-02-06
76.4%