Skip to content

Commit e609a47

Browse files
GoGoComputerclaude
andcommitted
docs+install: be honest — isolated mode also blocks the web UI
Docker's 'internal: true' network does not just block outbound; it also disables host->container port publishing (no docker-proxy is spawned). Empirically confirmed: HostConfig.PortBindings: requested 127.0.0.1:18789->18789/tcp NetworkSettings.Ports: {} {} (empty arrays) docker ps shows '18789-18790/tcp' instead of '127.0.0.1:18789->...' So the previous README claim "isolated 모드: 웹UI 접속 ✓" was wrong — after './openclaw install' lands users in isolated mode the browser gets "Safari Can't Connect" on 127.0.0.1:18789. This commit makes the docs honest and the install-completion message useful, without changing the underlying isolation behavior: - README (KO + EN) network-mode table: isolated.WebUI now ✗ with a callout explaining Docker's caveat - '🔒 isolated 에서 막히는 것' / 'What isolated blocks': add inbound port publishing + browser web UI explicitly - New subsection '🔒 isolated 에서도 되는 것' / 'What still works': './openclaw chat' and 'docker compose exec openclaw-cli bash' are unaffected by port publishing - '첫 사용' section ①: prepend './openclaw network online --restart' with a callout; closing with the matching '--isolated --restart' - New FAQ entry: 'web UI shows Safari Can't Connect even though containers are healthy' — diagnose with docker ps Ports column, fix with online toggle, alternatives that don't need toggling - install.sh completion banner: three entry points instead of two ('chat' added), ① now starts with 'network online --restart', ② noted as network-mode-independent, ③ chat noted likewise, and the 'if Safari can't connect' hint now points at the network toggle rather than 'doctor' (which would have shown all ✓ anyway) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 7f29d0f commit e609a47

3 files changed

Lines changed: 95 additions & 15 deletions

File tree

‎README.en.md‎

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,12 +117,18 @@ Pick whichever entry point fits.
117117
### ① Browser web UI
118118
119119
```bash
120+
# Right after install, the network is in 'isolated' — the web UI is unreachable.
121+
# Open it first:
122+
./openclaw network online --restart
123+
120124
open http://127.0.0.1:18789
121125
```
122126
123127
The most visual / approachable path. Safari or Chrome — either works. Do **not** include `open` in the address bar; `open` is a terminal command, not a URL.
124128

125-
> If you see **"Safari can't connect" / "Empty reply"**, run `./openclaw doctor` first. Containers might be up but healthz might still be initializing — confirm with `docker compose ps` and look for `(healthy)`.
129+
> ⚠️ **Web UI is unreachable under `isolated` mode** — Docker's `internal: true` network also disables host → container port publishing (no docker-proxy). That's why `127.0.0.1:18789` shows "Safari Can't Connect" / "Empty reply" right after install. Fix: `./openclaw network online --restart`, then lock back down with `./openclaw network isolated --restart` when done.
130+
131+
> Still "Safari can't connect"? Run `./openclaw doctor` and check `docker ps`. Ports should show `127.0.0.1:18789->18789/tcp`. If you see just `18789/tcp` (no `host:port->` prefix), you're still in `isolated`.
126132
127133
### ② Container CLI
128134

@@ -453,20 +459,30 @@ Docker and Ollama accumulate caches and unused images over time. One command to
453459
./openclaw network isolated --restart # close again ← keep this as the steady state
454460
```
455461

456-
| Mode | Outbound (container→internet) | Web UI (127.0.0.1) | host Ollama | When to use |
462+
| Mode | Outbound (container→internet) | Web UI (127.0.0.1:18789) | host Ollama | When to use |
457463
|---|---|---|---|---|
458-
| **`isolated`** 🔒 (default) | Fully blocked | ✓ | Blocked | Always — safe even if AI goes rogue |
459-
| **`online`** 🌐 | Allowed | ✓ | ✓ | Only briefly for install/update/model pulls |
464+
| **`isolated`** 🔒 (default) | Fully blocked | **Not reachable** ✗ | Blocked | Terminal-only workflow — maximum security |
465+
| **`online`** 🌐 | Allowed | ✓ | ✓ | **Web UI / install / update / model pulls** |
466+
467+
> ⚠️ **Docker caveat**: when a container is connected only to an `internal: true` network, Docker also disables port publishing (no docker-proxy). So under `isolated` there's no path from the host to `127.0.0.1:18789` either. **If you want the web UI, flip to `online` first**: `./openclaw network online --restart`. Lock back down with `./openclaw network isolated --restart` once done.
460468
461469
### What `isolated` (default) **blocks**
462470
- All outbound DNS and IP traffic from inside the container.
471+
- **Host → container inbound (web UI ports)** — Docker also disables port publishing.
463472
- Therefore the following are blocked (flip to `online` if needed):
473+
- **Browser web UI** (`http://127.0.0.1:18789`) — inbound also dropped
464474
- `pip install <pkg>`, `npm install`, `apt-get update`
465475
- `git clone https://github.com/...` and other GitHub/GitLab pulls
466476
- Hugging Face / pypi / docker registry downloads
467-
- **host Ollama** (`host.docker.internal:11434`) — also blocked under isolated
477+
- **host Ollama** (`host.docker.internal:11434`)
468478
- **Any data exfiltration attempt** (malicious prompt-injection "upload my files to X" is physically impossible)
469479

480+
### What still **works** under `isolated`
481+
- `./openclaw chat` — talks to host Ollama directly (bypasses the container)
482+
- `docker compose exec openclaw-cli bash` → `claude` — CLI inside the container (independent of port publishing)
483+
- Workspace file read/write
484+
- Models and code already inside the container
485+
470486
### When this matters
471487
- **High-stakes security**: when an AI agent browses the web, downloads code, or installs packages, the entire fetch path is removed — nothing malicious can be pulled in.
472488
- **Defense against exfil**: even if a prompt instructs "send my file to attacker.com", there's no network path out.
@@ -545,6 +561,29 @@ Easiest: `openclaw models add <name>` (auto-edits `.env` + pulls). To see what y
545561
Just rerun `./openclaw install`. Already-completed steps are marked `[skip]` and only the rest runs. State file: `~/.openclaw-mgr/state`.
546562
</details>
547563

564+
<details>
565+
<summary><b>Web UI (<code>http://127.0.0.1:18789</code>) shows "Safari Can't Connect" even though containers are healthy</b></summary>
566+
567+
If `./openclaw doctor` is all ✓ and `docker ps` shows the gateway as `(healthy)` but the browser can't reach it — almost always **isolated mode**. Docker's `internal: true` network also disables host → container port publishing, so `127.0.0.1:18789` is unreachable from the host.
568+
569+
Diagnose:
570+
```bash
571+
docker ps --format '{{.Names}}\t{{.Ports}}' | grep gateway
572+
# Expected (online): 127.0.0.1:18789-18790->18789-18790/tcp
573+
# Broken (isolated): 18789-18790/tcp ← not published
574+
```
575+
576+
Fix — briefly flip to online:
577+
```bash
578+
./openclaw network online --restart
579+
open http://127.0.0.1:18789
580+
# (when done)
581+
./openclaw network isolated --restart
582+
```
583+
584+
Don't need the web UI? Then `isolated` is fine — `./openclaw chat` and `docker compose exec openclaw-cli bash → claude` both work regardless of port publishing.
585+
</details>
586+
548587
<details>
549588
<summary><b>Install keeps printing <code>[skip]</code> for every step and ends with a "sandbox not configured" warning</b></summary>
550589

‎README.md‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -212,12 +212,17 @@ cd openclaw-workspace/openclaw-mgr
212212
### ① 브라우저 웹 UI
213213

214214
```bash
215+
# install 직후엔 네트워크가 isolated — 웹UI 접속이 막혀 있습니다. 먼저 열기:
216+
./openclaw network online --restart
217+
215218
open http://127.0.0.1:18789
216219
```
217220

218221
가장 시각적·직관적. Safari/Chrome 어디든 OK. 주소창에 `open` 까지 같이 붙여넣지 마세요 — `open` 은 터미널 명령어입니다.
219222

220-
> **"Safari can't connect" / "Empty reply"** 가 뜨면 `./openclaw doctor` 로 게이트웨이 상태부터 확인. 컨테이너는 떴지만 healthz 가 아직 응답 전일 수 있어요 (`docker compose ps` 로 `(healthy)` 표시 확인).
223+
> ⚠️ **isolated 모드에선 웹UI 접속 불가** — Docker 의 `internal: true` 네트워크는 호스트→컨테이너 port publishing(docker-proxy)도 같이 비활성화합니다. 그래서 `127.0.0.1:18789` 가 "Safari Can't Connect" / "Empty reply" 로 뜹니다. 해결: `./openclaw network online --restart` 후 접속, 사용 끝나면 `./openclaw network isolated --restart` 로 다시 잠그기.
224+
225+
> **"Safari can't connect" 이 여전히** 뜨면 `./openclaw doctor` 로 게이트웨이 상태 확인. `docker ps` 로 포트가 `127.0.0.1:18789->18789/tcp` 형태로 publish 됐는지 확인 (단순히 `18789/tcp` 만 보이면 isolated 상태).
221226
222227
### ② 컨테이너 CLI
223228

@@ -645,20 +650,30 @@ Docker 와 Ollama 는 시간이 갈수록 디스크와 메모리를 많이 차
645650
./openclaw network isolated --restart # 다시 잠그기 ← 항상 이 상태로 둘 것
646651
```
647652

648-
| 모드 | 아웃바운드(컨테이너→외부) | 웹UI(127.0.0.1) | host Ollama | 언제 쓰나 |
653+
| 모드 | 아웃바운드(컨테이너→외부) | 웹UI(127.0.0.1:18789) | host Ollama | 언제 쓰나 |
649654
|---|---|---|---|---|
650-
| **`isolated`** 🔒 (기본) | 완전 차단 | 접속 ✓ | 연결 안됨 | 평소, 실제 작업 시 — 난리 시에도 안전 |
651-
| **`online`** 🌐 | 허용 | 접속 ✓ | 연결 ✓ | 설치/업데이트/모델 다운로드 잠깐만 |
655+
| **`isolated`** 🔒 (기본) | 완전 차단 | **접속 안됨** ✗ | 연결 안됨 | 터미널 CLI 만 쓸 때 — 최고 보안 |
656+
| **`online`** 🌐 | 허용 | 접속 ✓ | 연결 ✓ | **웹UI 사용 / 설치 / 업데이트 / 모델 다운로드** |
657+
658+
> ⚠️ **Docker 제약**: 컨테이너가 `internal: true` 네트워크에만 연결되면 Docker 가 port publishing(docker-proxy)을 자동으로 비활성화합니다. 그래서 `isolated` 모드에선 `127.0.0.1:18789` 에 호스트가 접근할 통로가 없습니다. **웹UI 가 필요하면 반드시 `./openclaw network online --restart`** 로 잠깐 전환하세요. 작업이 끝나면 다시 `isolated`.
652659
653660
### 🔒 isolated (기본) 에서 **막히는** 것
654661
- **컨테이너 안에서 외부 DNS / 외부 IP 로 나가는 모든 통신**.
662+
- **호스트→컨테이너 인바운드(웹UI 포트 등)** — Docker 가 port publishing 자체를 끔.
655663
- 이 때문에 다음이 안 됩니다 — 허용하려면 `online` 으로 잠깐 전환:
664+
- **브라우저 웹UI (`http://127.0.0.1:18789`)** — 인바운드 차단
656665
- `pip install <패키지>`, `npm install`, `apt-get update`
657666
- `git clone https://github.com/...` 등 GitHub·GitLab 다운로드
658667
- Hugging Face / pypi / docker registry 다운로드
659-
- **호스트의 Ollama** 호출 (`host.docker.internal:11434`) — isolated 에서는 차단됩니다.
668+
- **호스트의 Ollama** 호출 (`host.docker.internal:11434`)
660669
- **외부로의 데이터 유출 시도** (악성 주입·제로데이 이메일 프롬프트 등) 도 자동으로 차단.
661670

671+
### 🔒 isolated 에서도 **되는** 것
672+
- `./openclaw chat` — 호스트 Ollama 직접 사용 (컨테이너 우회)
673+
- `docker compose exec openclaw-cli bash` → `claude` — 컨테이너 안에서 직접 CLI (네트워크 무관하게 STDIN/STDOUT)
674+
- 워크스페이스 파일 읽기·쓰기
675+
- 컨테이너에 이미 설치된 모델·코드 사용
676+
662677
### 어떤 상황에서 유용한가요?
663678
- **궁극 보안**: AI 에이전트가 웹을 돌아다니며 코드/패키지를 다운로드해 실행할 때 악성 패키지/익스플로잇을 **가져오는 경로 자체를 막아 버립니다**.
664679
- **데이터 유출 공격 대비**: 프롬프트 인젝션으로 "내 파일을 X 주소로 보내" 라는 시도가 있어도 네트워크 자체가 없으니 **나갈 수 있는 통로가 물리적으로 없는 상태**.
@@ -738,6 +753,29 @@ brew services restart ollama
738753
`./openclaw install` 을 다시 실행하세요. 이미 끝난 단계는 `[skip]` 로 표시되고 남은 단계만 진행합니다. (상태 파일: `~/.openclaw-mgr/state`)
739754
</details>
740755

756+
<details>
757+
<summary><b>웹UI(<code>http://127.0.0.1:18789</code>) 가 "Safari Can't Connect" 로 뜨는데 컨테이너는 떠 있어요</b></summary>
758+
759+
`./openclaw doctor` 에서 ✓ 가 다 뜨고 `docker ps` 로 컨테이너도 healthy 인데 브라우저는 못 붙는다면 — 거의 100% **isolated 모드** 때문입니다. Docker 의 `internal: true` 네트워크는 호스트→컨테이너 port publishing 도 같이 끄기 때문에 `127.0.0.1:18789` 가 호스트에서 접근 불가가 됩니다.
760+
761+
확인:
762+
```bash
763+
docker ps --format '{{.Names}}\t{{.Ports}}' | grep gateway
764+
# 정상(online): 127.0.0.1:18789-18790->18789-18790/tcp
765+
# 비정상(isolated): 18789-18790/tcp ← publish 안 됨
766+
```
767+
768+
해결 — 잠깐 online 으로 전환:
769+
```bash
770+
./openclaw network online --restart
771+
open http://127.0.0.1:18789
772+
# (작업 끝나면)
773+
./openclaw network isolated --restart
774+
```
775+
776+
웹UI 가 필요 없고 터미널만 쓰면 `isolated` 그대로 가능 — `./openclaw chat` 또는 `docker compose exec openclaw-cli bash → claude` 는 네트워크 publish 와 무관하게 동작합니다.
777+
</details>
778+
741779
<details>
742780
<summary><b>install 이 자꾸 <code>[skip]</code> 만 뜨고 마지막에 "샌드박스 미설정" 경고가 떠요</b></summary>
743781

‎openclaw-mgr/cmd/install.sh‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -551,16 +551,19 @@ printf ' %s./openclaw logs%s 컨테이너 로그 보기\n' "$C_BOLD"
551551
printf ' %s./openclaw schedule enable%s 매일 자동 업데이트 활성화\n' "$C_BOLD" "$C_RESET"
552552
printf '\n%s💬 첫 대화는 어떻게 하나요?%s\n' "$C_BOLD" "$C_RESET"
553553
printf ' → docs/GUIDE-FIRST-USE.md (5분 안에 첫 프롬프트까지)\n'
554-
printf '\n %s빠른 시작 두 가지 — 둘 중 하나를 고르세요%s\n' "$C_BOLD" "$C_RESET"
554+
printf '\n %s빠른 시작 — 셋 중 하나를 고르세요%s\n' "$C_BOLD" "$C_RESET"
555555
printf '\n ① 브라우저로 열기 (그래픽 UI):\n'
556-
printf ' 터미널에서: %sopen http://127.0.0.1:18789%s\n' "$C_BOLD" "$C_RESET"
557-
printf ' 또는 Safari/Chrome 주소창에 직접: %shttp://127.0.0.1:18789%s\n' "$C_BOLD" "$C_RESET"
556+
printf ' %s./openclaw network online --restart%s ← isolated 상태에선 인바운드도 차단됨\n' "$C_BOLD" "$C_RESET"
557+
printf ' %sopen http://127.0.0.1:18789%s 또는 주소창에 직접 http://127.0.0.1:18789\n' "$C_BOLD" "$C_RESET"
558+
printf ' (작업 끝나면) %s./openclaw network isolated --restart%s\n' "$C_BOLD" "$C_RESET"
558559
printf ' ⚠ 주소창에 "open " 까지 같이 붙여넣지 마세요. "open" 은 터미널 명령어입니다.\n'
559-
printf '\n ② 컨테이너 안 CLI (가장 안정적):\n'
560+
printf '\n ② 컨테이너 안 CLI (가장 안정적, 네트워크 모드 무관):\n'
560561
printf ' %scd ~/DEV/openclaw && docker compose exec openclaw-cli bash%s\n' "$C_BOLD" "$C_RESET"
561562
printf ' 컨테이너 셸이 뜨면: %sclaude%s\n' "$C_BOLD" "$C_RESET"
563+
printf '\n ③ 터미널 REPL 채팅 (네트워크 모드 무관, 호스트 Ollama 직접):\n'
564+
printf ' %s./openclaw chat%s # 워크스페이스의 IDENTITY/SOUL/USER 자동 로드\n' "$C_BOLD" "$C_RESET"
562565
printf '\n ※ ①번이 "Safari can\047t connect" / "Empty reply" 가 뜨면\n'
563-
printf ' %s./openclaw doctor%s 로 게이트웨이 상태부터 확인하세요.\n' "$C_BOLD" "$C_RESET"
566+
printf ' isolated 상태일 가능성이 큽니다. %s./openclaw network online --restart%s 후 다시 시도.\n' "$C_BOLD" "$C_RESET"
564567
printf '\n%s📁 생성된 디렉토리%s\n' "$C_BOLD" "$C_RESET"
565568
printf ' %-34s %s\n' "OpenClaw 본체:" "$OPENCLAW_DIR"
566569
printf ' %-34s %s\n' "에이전트 파일 (Finder 에서 확인):" "$OPENCLAW_WORKSPACE_DIR"

0 commit comments

Comments
 (0)