Skip to content

Commit 331a964

Browse files
author
박성모
committed
feat(models): openclaw models command + bilingual model-management docs
- cmd/models.sh: list / add / remove / pull / suggest. Auto-edits .env OLLAMA_MODELS (atomic write, sec_validate_models). add: idempotent + default `ollama pull`. remove: --purge for ollama rm. suggest: curated 24GB picks (coding/general/Korean/specialized). - Wired into dispatcher (`openclaw models ...`) and menu entry 14. - README KO+EN: new '🤖 모델 관리 / Models' section explaining host Ollama sharing, non-dev one-line workflow, dev edit-or-pull workflow, and the isolated-mode caveat (host Ollama is also blocked). - FAQ entries updated to point to `openclaw models add`. - Korea Sovereign AI section now uses `openclaw models add` instead of manual .env edit. - Bumped VERSION to 0.1.2.
1 parent 1e3df4b commit 331a964

5 files changed

Lines changed: 363 additions & 10 deletions

File tree

README.en.md

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,11 +124,68 @@ You may see system dialogs for Docker Desktop / Xcode CLT — just accept them.
124124
| `./openclaw restore <file>` | Verified safe restore (checksum + traversal check) |
125125
| `./openclaw schedule enable\|disable\|status` | Daily auto-update via launchd |
126126
| `./openclaw network status\|isolated\|online` | Toggle outbound internet (default: isolated) |
127+
| `./openclaw models list\|add\|remove\|pull\|suggest` | Manage local Ollama models (auto-edits `.env`) |
127128
| `./openclaw clean [--light\|--all\|--status]` | Memory & disk cleanup (interactive, non-developer friendly) |
128129
| `./openclaw uninstall [--purge]` | Remove. `--purge` also removes Docker/Ollama |
129130

130131
---
131132

133+
## 🤖 Models — use your existing local Ollama models
134+
135+
> **Key fact**: the OpenClaw container shares your host's Ollama (`host.docker.internal:11434`). **Models you already pulled with `ollama pull` are reused as-is** — nothing to re-download. The list below just illustrates the wiring.
136+
137+
```
138+
Your Mac OpenClaw container
139+
┌──────────────────────────────┐ ┌──────────────────────┐
140+
│ ollama list │ <─── same ───> │ host.docker.internal │
141+
│ • solar-pro │ Ollama │ :11434 │
142+
│ • exaone4.0 │ daemon │ (these are usable │
143+
│ • qwen2.5-coder:7b │ │ inside OpenClaw) │
144+
└──────────────────────────────┘ └──────────────────────┘
145+
```
146+
147+
### Non-developer mode (one-line commands)
148+
149+
```bash
150+
openclaw models # show .env entries + every model on your host
151+
openclaw models suggest # curated picks for 24GB Apple Silicon
152+
openclaw models add llama3.1:8b # append to .env + auto `ollama pull`
153+
openclaw models remove llama3.1:8b # remove from .env (model file kept)
154+
openclaw models remove llama3.1:8b --purge # also `ollama rm`
155+
openclaw models pull llava:7b # pull only — no .env change
156+
```
157+
158+
In the interactive menu, choose **option 14** — "List / add models". You never need to open `.env` by hand.
159+
160+
### Developer mode (edit directly or use the host)
161+
162+
Any of these works:
163+
164+
1. **Edit `.env` and run update** (containers refresh too):
165+
```bash
166+
$EDITOR ~/.openclaw-mgr/.env # OLLAMA_MODELS="qwen2.5-coder:7b,llama3.1:8b"
167+
openclaw update
168+
```
169+
2. **Just `ollama pull` on the host** — OpenClaw picks it up immediately (selectable in the UI):
170+
```bash
171+
ollama pull qwen2.5:14b
172+
```
173+
3. **`openclaw models add ... --no-pull`** — register the name now, fetch on next update.
174+
175+
### ⚠️ Caveat: `isolated` mode blocks the host Ollama too
176+
177+
In the default `isolated` mode the container has **no network at all**, including to your host's Ollama. To use local LLMs:
178+
179+
```bash
180+
openclaw network online --restart # temporarily allow
181+
# … work …
182+
openclaw network isolated --restart # lock back down (recommended default)
183+
```
184+
185+
> 💡 `openclaw update` flips the mode to `online` **automatically** for the duration, then restores it. `openclaw models add` runs `ollama pull` on the host (not inside the container), so it works regardless of the container's network mode — it only needs host internet.
186+
187+
---
188+
132189
## ⚙️ Configuration (`.env`)
133190

134191
Every variable in `.env.example` is commented. Highlights:
@@ -171,9 +228,8 @@ Sister project [**korea-sovereign-ai**](https://github.com/GoGoComputer/korea-so
171228
git clone https://github.com/GoGoComputer/korea-sovereign-ai.git ~/DEV/llmDev/korea-ai
172229
cd ~/DEV/llmDev/korea-ai && ./install.sh --minimal # EXAONE + A.X (~5GB)
173230

174-
# Then in OpenClaw's .env:
175-
# OLLAMA_MODELS="exaone3.5:7.8b,solar-pro:22b"
176-
./openclaw install
231+
# Then register them in OpenClaw with one command (auto-edits .env):
232+
openclaw models add exaone3.5:7.8b solar-pro:22b
177233
```
178234

179235
`./openclaw doctor` auto-detects Korean models and shows them in the report. With 24GB RAM, keep only one model loaded at a time (use `./openclaw clean` to unload others).
@@ -273,7 +329,7 @@ brew services restart ollama
273329
<details>
274330
<summary><b>How do I switch Ollama models?</b></summary>
275331

276-
Edit `OLLAMA_MODELS` in `.env`, then `./openclaw update`. With 24GB RAM, 7–8B models are recommended; 13B+ triggers a confirmation prompt.
332+
Easiest: `openclaw models add <name>` (auto-edits `.env` + pulls). To see what you already have locally and what's configured, run `openclaw models`. For a curated list: `openclaw models suggest`. The manual route still works — edit `OLLAMA_MODELS` in `.env`, then `./openclaw update`. With 24GB RAM, 7–8B models are recommended; 13B+ triggers a confirmation prompt.
277333
</details>
278334

279335
<details>

README.md

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -126,11 +126,68 @@ cd openclaw-workspace/openclaw-mgr
126126
| `./openclaw restore <file>` | 백업 파일에서 안전 복원 (체크섬·미리보기 검증) |
127127
| `./openclaw schedule enable\|disable\|status` | 매일 자동 업데이트 launchd 등록/해제 |
128128
| `./openclaw network status\|isolated\|online` | 외부 인터넷 차단 토글 (기본: isolated) |
129+
| `./openclaw models list\|add\|remove\|pull\|suggest` | 로컬 LLM 모델 관리 (·env 자동 수정) |
129130
| `./openclaw clean [--light\|--all\|--status]` | 메모리·디스크 정리 (비개발자용 대화형) |
130131
| `./openclaw uninstall [--purge]` | OpenClaw 제거. `--purge` 면 Docker/Ollama까지 |
131132

132133
---
133134

135+
## 🤖 모델 관리 — 내 로컬 Ollama 모델 그대로 쓰기
136+
137+
> **핵심**: OpenClaw 의 컨테이너는 호스트의 Ollama (`host.docker.internal:11434`) 를 공유합니다. **이미 `ollama pull` 로 받아둔 모델은 재설치 필요 없으며**, 아래 목록이 그리는 그대로 동작합니다.
138+
139+
```
140+
사용자 PC OpenClaw 컨테이너
141+
┌──────────────────────────────┐ ┌──────────────────────┐
142+
│ ollama list │ <─── 같은 ───> │ host.docker.internal │
143+
│ • solar-pro │ Ollama │ :11434 │
144+
│ • exaone4.0 │ 서비스 │ (이 모델들 그대로 │
145+
│ • qwen2.5-coder:7b │ │ 사용 가능) │
146+
└──────────────────────────────┘ └──────────────────────┘
147+
```
148+
149+
### 비개발자 모드 (한 줄 명령)
150+
151+
```bash
152+
openclaw models # 현재 .env 목록 + 로컬 설치된 모델 모두 보기
153+
openclaw models suggest # 24GB 맥용 추천 모델 목록
154+
openclaw models add llama3.1:8b # .env 에 추가 + 자동 pull
155+
openclaw models remove llama3.1:8b # .env 에서 빼기 (모델 파일은 남김)
156+
openclaw models remove llama3.1:8b --purge # 모델 파일까지 삭제
157+
openclaw models pull llava:7b # .env 건들지 않고 pull 만
158+
```
159+
160+
메뉴에서는 **14번** "모델 목록·추가". `.env` 파일을 직접 열 필요 없습니다.
161+
162+
### 개발자 모드 (직접 편집 또는 호스트 명령)
163+
164+
세 가지 매커니즘 중 아무거나:
165+
166+
1. **`.env` 직접 편집**`openclaw update` (컨테이너도 같이 갱신)
167+
```bash
168+
$EDITOR ~/.openclaw-mgr/.env # OLLAMA_MODELS="qwen2.5-coder:7b,llama3.1:8b"
169+
openclaw update
170+
```
171+
2. **호스트에서 그냥 `ollama pull`** — OpenClaw 는 별도 설정 없이 즉시 사용 가능 (UI 에서 모델 선택)
172+
```bash
173+
ollama pull qwen2.5:14b
174+
```
175+
3. **`openclaw models add ... --no-pull`** — 명단에만 등록하고 다음번 update 때 받기
176+
177+
### ⚠️ isolated 모드 주의
178+
179+
기본값 `isolated` 에서는 **호스트 Ollama 도 차단** 됩니다 (컨테이너→외부 완전 차단). 로컬 LLM 을 쓰려면:
180+
181+
```bash
182+
openclaw network online --restart # 일시 허용
183+
# 작업…
184+
openclaw network isolated --restart # 다시 잠그기 (항상 이 상태 권장)
185+
```
186+
187+
> 💡 참고: `openclaw update` 는 필요한 동안만 **자동으로** online 으로 전환하고 끝나면 원래 모드로 복귀합니다. `openclaw models add``ollama pull` 은 호스트에서 돌아 컨테이너 네트워크 토글한 필요 없습니다 (호스트 인터넷만 필요).
188+
189+
---
190+
134191
## ⚙️ 설정 (`.env`)
135192

136193
`.env.example` 의 모든 변수에 주석이 달려 있습니다. 핵심:
@@ -173,9 +230,8 @@ BACKUP_ENCRYPT="1" # .env GPG 암호화
173230
git clone https://github.com/GoGoComputer/korea-sovereign-ai.git ~/DEV/llmDev/korea-ai
174231
cd ~/DEV/llmDev/korea-ai && ./install.sh --minimal # EXAONE + A.X (~5GB)
175232

176-
# 그 다음 OpenClaw 의 .env 에서 한국 모델 사용:
177-
# OLLAMA_MODELS="exaone3.5:7.8b,solar-pro:22b"
178-
./openclaw install
233+
# 그 다음 OpenClaw 에서 한 줄로 등록 (·env 자동 수정):
234+
openclaw models add exaone3.5:7.8b solar-pro:22b
179235
```
180236

181237
`./openclaw doctor` 가 자동으로 한국 모델을 감지해 `한국 소버린 AI: ✓` 로 표시합니다. 메모리는 24GB 에서 동시 1개 모델만 로드하는 걸 권장합니다 (`./openclaw clean` 으로 다른 모델 언로드 가능).
@@ -276,7 +332,7 @@ brew services restart ollama
276332
<details>
277333
<summary><b>다른 Ollama 모델로 바꾸려면?</b></summary>
278334

279-
`.env``OLLAMA_MODELS` 를 수정하고 `./openclaw update` 실행. 24GB RAM 에서는 7~8B 모델 권장. 13B 이상은 자동 경고가 뜹니다.
335+
가장 간단: `openclaw models add <이름>` (·env 자동 수정 + pull). 이미 로컬에 있는 모델은 `openclaw models` 로 모두 확인. 추천 목록은 `openclaw models suggest`. 수동으로 하고 싶으면 `.env``OLLAMA_MODELS` 편집 후 `./openclaw update`. 24GB RAM 에서는 7~8B 추천, 13B 이상은 자동 경고.
280336
</details>
281337

282338
<details>

openclaw-mgr/cmd/menu.sh

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ show_menu() {
6767
─── $(t "보안 / Security" "Security") ───────────────────────────────────────
6868
11) $(t "네트워크 격리 토글 (network)" "Toggle network isolation (network)")
6969
70+
─── $(t "모델 / Models" "Models") ─────────────────────────────────────────────
71+
14) $(t "모델 목록·추가 (models)" "List / add models (models)")
72+
7073
─── $(t "삭제 / Uninstall" "Uninstall") ────────────────────────────────────
7174
12) $(t "OpenClaw 제거 (uninstall)" "Remove OpenClaw (uninstall)")
7275
@@ -152,6 +155,12 @@ while true; do
152155
pause ;;
153156
esac ;;
154157
13) run_cmd self-update || true; pause ;;
158+
14)
159+
run_cmd models list || true
160+
printf ' %s ' "$(t '추가할 모델명 (Enter 로 건너뛰기):' 'Model name to add (Enter to skip):')"
161+
read -r m || true
162+
if [ -n "${m:-}" ]; then run_cmd models add "$m" || true; fi
163+
pause ;;
155164
q|Q|"") clear 2>/dev/null || true; exit 0 ;;
156165
*)
157166
printf ' %s\n' "$(t '알 수 없는 선택입니다.' 'Unknown selection.')"; pause ;;

0 commit comments

Comments
 (0)