Skip to content

Commit 7bf8294

Browse files
GoGoComputerclaude
andcommitted
docs(readme): RAM-based model recommendation table + OPENCLAW_FORCE_DEFAULT_MODEL on first install
New users hitting the setup wizard had to dig through GUIDE-DISCORD-BOT case D to learn that 3B models can't follow direct commands and that they should pin their pick with OPENCLAW_FORCE_DEFAULT_MODEL. Hoisted both into the README at the position right after the wizard stage table — where they'll see it during first install. Added to README.md and README.en.md (bilingual, mirrored): - New subsection "🎯 Which model should you pick in the wizard?" - RAM-tier table (8/16/24/32GB+) with primary pick · fallback · heavy - Callout explaining why gemma4:latest is the 24GB sweet spot (load time + instruction-following parity, not just size) - OPENCLAW_FORCE_DEFAULT_MODEL lock pattern with copy-paste .env line - Three-bullet summary of the auto-optimizer's behavior when env is unset - ToC entries so the subsection is discoverable No code changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent fc2a50e commit 7bf8294

2 files changed

Lines changed: 64 additions & 0 deletions

File tree

README.en.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
- [🎯 Right after install — first use](#-right-after-install--first-use)
2020
- [① Browser web UI](#-browser-web-ui)
2121
- [② Container CLI](#-container-cli)
22+
- [🎯 Which model should you pick in the wizard? — RAM-based recommendations (v0.2.23+)](#-which-model-should-you-pick-in-the-wizard--ram-based-recommendations-v0223)
2223
- [③ Terminal REPL chat](#-terminal-repl-chat)
2324
- [Verify](#verify)
2425
- [🌐 Temporarily opening external network](#-temporarily-opening-external-network)
@@ -190,6 +191,37 @@ Exact order/wording depends on the OpenClaw build, but you'll generally see thes
190191
Full surface (50+ providers, advanced-flow extras): [OpenClaw upstream docs `cli/onboard`](https://docs.openclaw.ai/cli/onboard).
191192
</details>
192193

194+
#### 🎯 Which model should you pick in the wizard? — RAM-based recommendations (v0.2.23+)
195+
196+
When the wizard reaches step 8 (`ollama` → model name), pick one of these based on your laptop's RAM. **Smaller is NOT always better** — 3B-class models reply fast but consistently fail to follow direct commands ("delete X", "fill in Y", "remember Z") because the multi-step reasoning chain "user said delete → I have a delete tool → I should call it" is fragile at that scale. You'll see the bot looping back into conversation instead of actually doing the thing.
197+
198+
| RAM | Primary pick (default) | Lightweight fallback (latency-first) | Heavy work |
199+
|---|---|---|---|
200+
| **8 GB** | `qwen2.5:3b-instruct` (1.8 GB) |||
201+
| **16 GB** | `qwen2.5:7b-instruct` (4.7 GB) | `qwen2.5:3b-instruct` (1.8 GB) ||
202+
| **24 GB** | 🌟 **`gemma4:latest` (8.9 GB)** — vision + audio + thinking + tools | `qwen2.5:3b-instruct` | `gemma4:26b` (17 GB) via explicit call |
203+
| **32 GB+** | `gemma4:latest` or `qwen2.5-coder:14b` (8.4 GB) | `gemma4:latest` | `gemma4:26b`, `llama3.3:70b`, etc. |
204+
205+
> **Why `gemma4:latest` for 24 GB?** Cold load 7.2 s / warm 0.27 s (far under OpenClaw's 120 s idle watchdog). Multimodal — images, audio, thinking, tools all native. Coexists with other apps on a 24 GB machine. Most importantly: **follows direct commands the 3B models drop on the floor.** Discord bot interactions like "delete this", "remember that", "fill in the file" Just Work.
206+
207+
##### Lock your pick permanently — `OPENCLAW_FORCE_DEFAULT_MODEL`
208+
209+
After the wizard, every future `./openclaw setup` run goes through the auto-optimizer ([three-tier policy](docs/GUIDE-DISCORD-BOT.md#default-모델을-영구-lock-하기-v0223)). To make your choice immutable, add one line to `.env`:
210+
211+
```bash
212+
# openclaw-mgr/.env (copy from .env.example if it doesn't exist yet)
213+
OPENCLAW_FORCE_DEFAULT_MODEL="gemma4:latest"
214+
```
215+
216+
With this set, every subsequent `./openclaw setup` · `update` · `restore` will **force** this model back to `models[0]`, regardless of what the wizard did or what OpenClaw's upstream hardcoded defaults try to inject. Change the line and re-run setup when you want to switch.
217+
218+
Default behavior (env var unset):
219+
- ✅ Wizard-picked model has `tools` capability → **kept as-is** (your choice is respected)
220+
- ⚙️ Wizard-picked model has no `tools` (e.g., embedding-only) → **auto-swap to the smallest tools-capable model** (safety net)
221+
- ⚠️ No tools-capable model is registered at all → **warning only**, suggests `ollama pull gemma4:latest`
222+
223+
Full flow and trade-offs in [📜 docs/GUIDE-DISCORD-BOT.md — case D](docs/GUIDE-DISCORD-BOT.md#케이스-d--모델이-너무-무거워-첫-응답-전에-watchdog-트리거-v021--v022-권장-모델-변경).
224+
193225
> ⚠️ **`run --rm`, not `exec`** — the `openclaw-cli` container's entrypoint (`node dist/index.js`) prints help and exits immediately on no-arg invocation (`docker ps -a` shows it as `Exited (1)`). `./openclaw setup` handles this internally; if you ever call it manually, always use `docker compose run --rm openclaw-cli <subcommand>`.
194226
>
195227
> Raw shell inside the container? `docker compose run --rm --entrypoint bash openclaw-cli`.

README.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
- [🎯 install 직후 — 첫 사용](#-install-직후--첫-사용)
2323
- [① 브라우저 웹 UI](#-브라우저-웹-ui)
2424
- [② 컨테이너 CLI](#-컨테이너-cli)
25+
- [🎯 마법사에서 어떤 모델을 골라야 하나 — RAM 별 추천 (v0.2.23+)](#-마법사에서-어떤-모델을-골라야-하나--ram-별-추천-v0223)
2526
- [③ 터미널 REPL 채팅](#-터미널-repl-채팅)
2627
- [정상 동작 확인](#정상-동작-확인)
2728
- [🌐 외부 네트워크 잠깐 켜기](#-외부-네트워크-잠깐-켜기)
@@ -284,6 +285,37 @@ OpenClaw 본체 버전에 따라 단계 순서·문구는 약간 다를 수 있
284285
상세 옵션 (50+ provider, advanced 플로우의 추가 단계 등): [OpenClaw 공식 docs `cli/onboard`](https://docs.openclaw.ai/cli/onboard)
285286
</details>
286287

288+
#### 🎯 마법사에서 어떤 모델을 골라야 하나 — RAM 별 추천 (v0.2.23+)
289+
290+
마법사 8번 단계에서 `ollama` 선택 후 모델 이름 입력할 때, **노트북 RAM 에 맞춰** 다음 중 하나를 권장합니다. 단순히 "작은 모델 = 좋음" 이 아님 — 3B 이하 모델은 빠르지만 **"BOOTSTRAP.md 지워줘" · "IDENTITY.md 채워줘" 같은 직접 명령을 못 따라가는 경우**가 흔해 (Discord 봇 사용시 답답함).
291+
292+
| RAM | 1순위 추천 (default) | 가벼운 대안 (응답 속도 우선) | 무거운 작업 |
293+
|---|---|---|---|
294+
| **8GB** | `qwen2.5:3b-instruct` (1.8GB) |||
295+
| **16GB** | `qwen2.5:7b-instruct` (4.7GB) | `qwen2.5:3b-instruct` (1.8GB) ||
296+
| **24GB** | 🌟 **`gemma4:latest` (8.9GB)** — vision+audio+thinking+tools | `qwen2.5:3b-instruct` | `gemma4:26b` (17GB) 명시 호출 |
297+
| **32GB+** | `gemma4:latest` 또는 `qwen2.5-coder:14b` (8.4GB) | `gemma4:latest` | `gemma4:26b`, `llama3.3:70b`|
298+
299+
> **왜 24GB 추천이 `gemma4:latest`?** Cold load 7.2초 / warm 0.27초 (OpenClaw 의 120초 idle watchdog 한참 아래). 멀티모달 (이미지·오디오·thinking·tools) 모두 지원. 24GB RAM 에서 다른 앱과 공존 가능. 무엇보다 **3B 모델이 못 따라가는 직접 명령을 잘 따라감** — Discord 봇에서 "지워줘"/"기억해줘"/"채워줘" 같은 일상 명령이 자연스럽게 동작.
300+
301+
##### 한 번 고른 모델 영구 lock — `OPENCLAW_FORCE_DEFAULT_MODEL`
302+
303+
마법사가 끝난 후에도 `./openclaw setup` 을 다시 실행하면 자동 최적화 함수가 모델 순서를 건드릴 수 있어요 ([세 단계 정책](docs/GUIDE-DISCORD-BOT.md#default-모델을-영구-lock-하기-v0223)). **고정하고 싶으면** `.env` 에 한 줄 박으세요:
304+
305+
```bash
306+
# openclaw-mgr/.env (없으면 .env.example 복사해서 만들기)
307+
OPENCLAW_FORCE_DEFAULT_MODEL="gemma4:latest"
308+
```
309+
310+
이러면 향후 `./openclaw setup` · `update` · `restore` 어느 단계에서도 이 모델이 **항상 default 모델로 강제**됩니다. 변경하고 싶을 땐 이 줄을 다시 편집하면 됨.
311+
312+
자동 정책 요약 (`.env` 안 박았을 때):
313+
- ✅ 마법사에서 고른 모델이 tools 지원 → **그대로 유지** (사용자 선택 존중)
314+
- ⚙️ 고른 모델이 tools 못 씀 (예: 임베딩 전용) → **가장 작은 tools-capable 로 자동 swap** (안전망)
315+
- ⚠️ 모든 모델이 tools 못 씀 → **warning 만 띄우고 종료**`ollama pull gemma4:latest` 추천
316+
317+
자세한 흐름은 [📜 docs/GUIDE-DISCORD-BOT.md `케이스 D`](docs/GUIDE-DISCORD-BOT.md#케이스-d--모델이-너무-무거워-첫-응답-전에-watchdog-트리거-v021--v022-권장-모델-변경) 참조.
318+
287319
> ⚠️ **`exec` 가 아니라 `run --rm`**`openclaw-cli` 컨테이너의 entrypoint(`node dist/index.js`)는 인자 없이 뜨면 help 출력 후 즉시 종료(`Exited (1)`)됩니다. `./openclaw setup` 이 이 패턴을 내부적으로 처리. 직접 호출할 때도 항상 `run --rm` 을 쓰세요.
288320
>
289321
> 컨테이너 셸이 필요하면: `docker compose run --rm --entrypoint bash openclaw-cli`

0 commit comments

Comments
 (0)