fix(install): 첫 사용 가이드 함정 4개 동시 수정

1) compose.security.yml: ports 에 !override 적용 — 베이스 0.0.0.0
   바인딩과 머지되어 같은 호스트 포트를 두 번 바인드 시도하던
   "address already in use" 수정.
2) compose.security.yml: gateway command override 로
   --allow-unconfigured 명시 — 첫 부팅 시 "Missing config. Run
   openclaw setup" 으로 1분마다 크래시 루프 빠지던 문제 방지
   (--bind auto 로 시드된 컨피그와 일치).
3) cmd/start.sh: 옛 .env (OPENCLAW_DIR=$HOME/openclaw) 자동 마이그
   레이션 — 0.2.x 이전 .env 잔존 시 "OpenClaw 가 설치돼 있지 않
   습니다" 오진 방지.
4) cmd/install.sh + GUIDE-FIRST-USE.md: "open http://..." 안내문
   분리 — 통째로 Safari 주소창에 붙여 Google 검색으로 빠지는 함정에
   명시적 경고와 "브라우저엔 URL만" 분리 표기.
   TROUBLESHOOTING 표에 Empty reply / 옛 .env / 포트 충돌 행 추가.

Author: 박성모

docs/GUIDE-FIRST-USE.md

@@ -75,15 +75,24 @@ OpenClaw 와 대화하는 방법은 3가지. **처음이면 방식 B (컨테이
 
 ### 방식 A — 브라우저 UI
 
+**터미널에서 한 줄로**:
 ```bash
 open http://127.0.0.1:18789
 ```
 
+**또는 Safari/Chrome 주소창에 직접 입력** (`open ` 은 빼고 URL 만):
+```
+http://127.0.0.1:18789
+```
+
+> ⚠ **자주 하는 실수** — `open http://127.0.0.1:18789` **전체 문장**을 그대로 Safari 주소창에 붙여넣으면 Google 검색으로 빠집니다 ("open http%3A%2F%2F..."). `open` 은 macOS 터미널 명령어 — 터미널 창에서만 통합니다. 브라우저 주소창에는 `http://127.0.0.1:18789` 만 입력하세요.
+
 | 응답 | 의미 | 다음 |
 |---|---|---|
 | 채팅 화면이 뜸 | ✓ 사용 가능 — 입력창에 질문 입력 | 아래 "첫 프롬프트 예시" |
-| `Cannot connect` / 빈 페이지 | gateway 가 아직 안 뜸 | 30초 더 대기 → 안 되면 `./openclaw logs gateway` |
-| `404` / JSON 만 보임 | 사용 중인 OpenClaw 버전이 UI 미내장 (헤드리스) | 방식 B 로 전환 |
+| `Safari can't connect` / `Cannot connect` | 18789 포트가 안 열림 | 7단계 "`Empty reply` / `Can't connect`" 행 참고 |
+| `Empty reply from server` | gateway 컨테이너는 떴지만 부팅 중 | 30~60초 대기 후 새로고침. 1분 넘으면 `./openclaw logs gateway` |
+| `404` / JSON 만 보임 | OpenClaw 버전이 UI 미내장 (헤드리스) | 방식 B 로 전환 |
 
 > 💡 OpenClaw 본체 버전에 따라 UI 가 내장되어 있을 수도, API 만 있을 수도 있습니다. UI 가 없으면 방식 B 를 쓰세요.
 
@@ -246,7 +255,11 @@ dockerstop                   # 6.5단계에서 등록한 alias — Docker Deskto
 
 | 증상 | 즉석 점검 | 해결 |
 |---|---|---|
-| `open http://127.0.0.1:18789` → 빈 페이지 | `./openclaw doctor` 의 gateway 항목 | gateway 가 아직 부팅 중 — 30초 후 새로고침 / `./openclaw logs gateway` |
+| Safari 주소창에 `open http://...` 가 그대로 들어감 → Google 검색으로 빠짐 | 주소창 내용 확인 | `open ` 제거하고 `http://127.0.0.1:18789` 만 입력 (`open` 은 터미널 명령어) |
+| `Safari can't connect to 127.0.0.1` / `curl: (7) Failed to connect` | `docker ps \| grep gateway` 에 `Restarting` 보임 | gateway 가 크래시 루프 — `./openclaw logs gateway` 로 사유 확인. `Missing config. Run \`openclaw setup\`` 가 보이면 이 워크스페이스를 최신으로 (`./openclaw self-update`) 후 `./openclaw stop && ./openclaw start` 다시 |
+| `Empty reply from server` (포트는 열렸는데 응답 없음) | 30~60초 더 대기 | gateway 가 첫 부팅 중. 1분이 넘는데도 그대로면 `./openclaw logs gateway` 에 `starting...` 만 반복 — 본체 버그일 수 있으니 `./openclaw network online --restart && ./openclaw update` |
+| `./openclaw start` → `OpenClaw 가 설치돼 있지 않습니다` (그런데 `~/DEV/openclaw` 가 있음) | `grep OPENCLAW_DIR openclaw-mgr/.env` | `.env` 가 옛날 스키마. 한 줄로 고치기:  `sed -i '' 's\|^OPENCLAW_DIR=.*\|OPENCLAW_DIR="$HOME/DEV/openclaw"\|' openclaw-mgr/.env` |
+| `failed to bind host port 127.0.0.1:18789/tcp: address already in use` | `lsof -nP -iTCP:18789` (아무것도 안 보이면 Docker 내부) | `./openclaw stop && docker rm -f openclaw-openclaw-gateway-1 openclaw-openclaw-cli-1 && ./openclaw start` (좀비 포워더 정리) |
 | `docker compose exec` → `service "openclaw-cli" is not running` | `docker ps \| grep openclaw` | `./openclaw start` 후 재시도 |
 | CLI 안에서 `claude` → `command not found` | 컨테이너 이미지 버전 체크 | `./openclaw update` (online 모드) |
 | 모델 응답이 없음 / 매우 느림 | `ollama list` · `ollama ps` | (a) Ollama 데몬 OFF → `open -a Ollama` (b) 모델 미설치 → `ollama pull <모델>` (c) 24GB 에서 14B 초과 → 더 작은 모델로 |

openclaw-mgr/cmd/install.sh

@@ -482,7 +482,16 @@ printf '  %s./openclaw logs%s            컨테이너 로그 보기\n' "$C_BOLD"
 printf '  %s./openclaw schedule enable%s 매일 자동 업데이트 활성화\n' "$C_BOLD" "$C_RESET"
 printf '\n%s💬 첫 대화는 어떻게 하나요?%s\n' "$C_BOLD" "$C_RESET"
 printf '  → docs/GUIDE-FIRST-USE.md  (5분 안에 첫 프롬프트까지)\n'
-printf '  빠른 시작:  %sopen http://127.0.0.1:18789%s   또는   %sdocker compose exec openclaw-cli bash%s → %sclaude%s\n' "$C_BOLD" "$C_RESET" "$C_BOLD" "$C_RESET" "$C_BOLD" "$C_RESET"
+printf '\n  %s빠른 시작 두 가지 — 둘 중 하나를 고르세요%s\n' "$C_BOLD" "$C_RESET"
+printf '\n  ① 브라우저로 열기 (그래픽 UI):\n'
+printf '       터미널에서:  %sopen http://127.0.0.1:18789%s\n' "$C_BOLD" "$C_RESET"
+printf '       또는 Safari/Chrome 주소창에 직접:  %shttp://127.0.0.1:18789%s\n' "$C_BOLD" "$C_RESET"
+printf '       ⚠ 주소창에 "open " 까지 같이 붙여넣지 마세요. "open" 은 터미널 명령어입니다.\n'
+printf '\n  ② 컨테이너 안 CLI (가장 안정적):\n'
+printf '       %scd ~/DEV/openclaw && docker compose exec openclaw-cli bash%s\n' "$C_BOLD" "$C_RESET"
+printf '       컨테이너 셸이 뜨면:  %sclaude%s\n' "$C_BOLD" "$C_RESET"
+printf '\n  ※ ①번이 "Safari can\047t connect" / "Empty reply" 가 뜨면\n'
+printf '       %s./openclaw doctor%s 로 게이트웨이 상태부터 확인하세요.\n' "$C_BOLD" "$C_RESET"
 printf '\n%s📁 생성된 디렉토리%s\n' "$C_BOLD" "$C_RESET"
 printf '  %-34s %s\n' "OpenClaw 본체:" "$OPENCLAW_DIR"
 printf '  %-34s %s\n' "에이전트 파일 (Finder 에서 확인):" "$OPENCLAW_WORKSPACE_DIR"

openclaw-mgr/cmd/start.sh

@@ -13,6 +13,24 @@ set -euo pipefail
 # shellcheck disable=SC1091
 . "${OPENCLAW_MGR_DIR}/lib/common.sh"
 
+# .env 자동 마이그레이션 — 0.2.x 이전 .env 는 OPENCLAW_DIR=$HOME/openclaw 로
+# 깔려 있어서 신버전 (기본 $HOME/DEV/openclaw) 와 어긋난다. 실제 디렉터리가
+# $HOME/DEV/openclaw 에 있으면 자동 보정.
+if [ "${OPENCLAW_DIR:-}" = "$HOME/openclaw" ] && [ ! -d "$HOME/openclaw" ] \
+   && [ -d "$HOME/DEV/openclaw" ]; then
+  warn ".env 의 OPENCLAW_DIR 가 옛 위치(\$HOME/openclaw) 입니다. \$HOME/DEV/openclaw 로 자동 보정합니다."
+  for ef in "$OPENCLAW_MGR_DIR/.env" "${OPENCLAW_MGR_HOME:-$HOME/.openclaw-mgr}/.env"; do
+    [ -f "$ef" ] || continue
+    cp -- "$ef" "$ef.bak.$(date +%s)" 2>/dev/null || true
+    # macOS sed 호환: -i ''
+    sed -i '' 's|^OPENCLAW_DIR=.*|OPENCLAW_DIR="$HOME/DEV/openclaw"|' "$ef" 2>/dev/null || true
+    grep -q '^OPENCLAW_WORKSPACE_DIR=' "$ef" || echo 'OPENCLAW_WORKSPACE_DIR="$HOME/DEV/openclawAgent"' >> "$ef"
+    grep -q '^OPENCLAW_CONFIG_DIR=' "$ef"   || echo 'OPENCLAW_CONFIG_DIR="$HOME/.openclaw"'           >> "$ef"
+  done
+  OPENCLAW_DIR="$HOME/DEV/openclaw"
+  export OPENCLAW_DIR
+fi
+
 OPENCLAW_DIR="${OPENCLAW_DIR:-$HOME/DEV/openclaw}"
 [ -d "$OPENCLAW_DIR" ] || die "OpenClaw 가 설치돼 있지 않습니다. ./openclaw install 먼저 실행하세요."
 

openclaw-mgr/compose.security.yml

@@ -16,10 +16,28 @@ services:
     mem_limit: ${OPENCLAW_MEM_LIMIT:-8g}
     memswap_limit: ${OPENCLAW_MEM_LIMIT:-8g}
     cpus: ${OPENCLAW_CPUS:-8}
-    # 포트는 항상 127.0.0.1 만 — LAN/공용 Wi-Fi 외부 노출 완전 차단
-    ports:
+    # 포트는 항상 127.0.0.1 만 — LAN/공용 Wi-Fi 외부 노출 완전 차단.
+    # `!override` 는 베이스 compose 의 ports 리스트(0.0.0.0 바인딩) 를
+    # 통째로 교체한다. 이걸 쓰지 않으면 compose v2 가 두 리스트를 머지해서
+    # 같은 호스트 포트를 두 번(0.0.0.0:18789 + 127.0.0.1:18789) 바인드하려다
+    # "address already in use" 로 실패한다.
+    ports: !override
       - "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"
       - "127.0.0.1:${OPENCLAW_BRIDGE_PORT:-18790}:18790"
+    # 첫 실행 직후 인증/설정이 비어 있어도 게이트웨이가 부팅되도록
+    # `--allow-unconfigured` 를 명시. 베이스 docker-compose.yml 의
+    # command 를 통째로 override 한다 (compose v2 는 command 를 merge 하지
+    # 않고 교체하기 때문). 사용자는 나중에 `openclaw setup` / 토큰 입력으로
+    # 정식 설정을 추가할 수 있다.
+    command:
+      - node
+      - dist/index.js
+      - gateway
+      - --bind
+      - "${OPENCLAW_GATEWAY_BIND:-auto}"
+      - --port
+      - "18789"
+      - --allow-unconfigured
 
   openclaw-cli:
     cap_drop: [ALL]