303 lines
8.1 KiB
Markdown
303 lines
8.1 KiB
Markdown
# OpenClaw Setup Max (Paid + Free Model Switching)
|
|
|
|
This workspace runs OpenClaw with:
|
|
- A paid high-quality model profile (`openrouter/qwen/qwen3-coder:free`)
|
|
- A free OpenRouter profile
|
|
- One-command live switching
|
|
- Optional automatic day/night switching (example: free from 9pm-7am)
|
|
- Optional budget guard that warns and auto-reverts from expensive models
|
|
|
|
This guide is written for first-time users.
|
|
|
|
## 0) Workspace Layout
|
|
|
|
Keep only the operator files at root:
|
|
- `AGENTS.md`
|
|
- `README.md`
|
|
- `PRD.md`
|
|
|
|
Everything else is grouped by function:
|
|
- `setup/`: machine bootstrap scripts
|
|
- `scripts/`: daily operations + guard installers
|
|
- `config/`: editable profile/schedule/guard JSON
|
|
- `docs/context/`: persona + runtime context docs
|
|
- `docs/operations/`: switching + troubleshooting runbooks
|
|
- `memory/`: daily notes/log memory
|
|
|
|
## 1) What You Get
|
|
|
|
- `paid` profile:
|
|
- Primary: `openrouter/qwen/qwen3-coder:free`
|
|
- Fallbacks: `openrouter/qwen/qwen3-coder-next`, `openrouter/qwen/qwen3-14b`
|
|
- `free` profile:
|
|
- Primary: `openrouter/qwen/qwen3-coder:free`
|
|
- Fallbacks: `openrouter/qwen/qwen3-14b`
|
|
|
|
Profiles are defined in `config/model-profiles.config.json`.
|
|
|
|
## 2) Key Files
|
|
|
|
- `config/model-profiles.config.json`: model profile definitions (`paid`, `free`)
|
|
- `config/model-schedule.config.json`: schedule settings (`dayProfile`, `nightProfile`, hours)
|
|
- `config/model-budget-guard.config.json`: high-cost warning and auto-revert settings
|
|
- `scripts/model_profile_switch.sh`: manual live switch command
|
|
- `scripts/model_hygiene_workflow.sh`: apply profile + prune legacy model/provider/auth config
|
|
- `scripts/model_schedule_guard.sh`: scheduled switch worker
|
|
- `scripts/model_budget_guard.sh`: budget guard worker
|
|
- `scripts/install_model_schedule_guard_launchd.sh`: installs schedule LaunchAgent
|
|
- `scripts/install_model_budget_guard_launchd.sh`: installs budget LaunchAgent
|
|
- `scripts/install_local_model_guardrails.sh`: installs both LaunchAgents
|
|
|
|
## 3) Prerequisites
|
|
|
|
Run these checks:
|
|
|
|
```bash
|
|
openclaw --version
|
|
ollama list
|
|
jq --version
|
|
```
|
|
|
|
OpenClaw and Ollama must already be set up.
|
|
If you need initial setup, run `setup/setup_openclaw_ollama.sh` first.
|
|
|
|
Script behavior:
|
|
- `setup/setup_openclaw_ollama.sh` now checks/installs:
|
|
- `ollama`
|
|
- `node`/`npm` (Node >= 22)
|
|
- `openclaw`
|
|
- `jq`
|
|
- `python3`
|
|
- It will prompt before:
|
|
- Installing Ollama (if missing)
|
|
- Pulling local Ollama models (large downloads)
|
|
|
|
Useful flags:
|
|
|
|
```bash
|
|
# Non-interactive yes to prompts
|
|
AUTO_YES=true bash ./setup/setup_openclaw_ollama.sh
|
|
|
|
# Skip model pulls during setup
|
|
PULL_LOCAL_MODELS=false bash ./setup/setup_openclaw_ollama.sh
|
|
```
|
|
|
|
## 4) Quick Start (Most Common)
|
|
|
|
Run the hygiene workflow (recommended after any model changes):
|
|
|
|
```bash
|
|
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
|
|
bash ./scripts/model_hygiene_workflow.sh paid
|
|
```
|
|
|
|
Switch to free mode now:
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh free
|
|
```
|
|
|
|
Switch back to paid mode:
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh paid
|
|
```
|
|
|
|
Check current model state:
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh status
|
|
```
|
|
|
|
Run a web research task from terminal:
|
|
|
|
```bash
|
|
./scripts/research.sh latest swiftui observation patterns
|
|
```
|
|
|
|
Optional flags:
|
|
- `--sources <count>` minimum source count (default `3`)
|
|
- `--thinking <level>` sets OpenClaw thinking level
|
|
- `--deliver` sends the final response back to the current channel
|
|
|
|
## 5) How Live Switching Works
|
|
|
|
When you run:
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh free
|
|
```
|
|
|
|
the script does three things:
|
|
|
|
1. Sets OpenClaw default model to that profile primary.
|
|
2. Rebuilds fallback chain from that profile.
|
|
3. Pushes `/model <primary>` to active `agent:main:main` session for immediate effect.
|
|
|
|
If you want config-only change (no live session message), use:
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh free --no-live
|
|
```
|
|
|
|
## 6) Enable Schedule (Example: Free 9pm-7am)
|
|
|
|
1. Edit config:
|
|
|
|
```bash
|
|
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
|
|
open config/model-schedule.config.json
|
|
```
|
|
|
|
2. Set:
|
|
|
|
```json
|
|
{
|
|
"enabled": true,
|
|
"dayProfile": "paid",
|
|
"nightProfile": "free",
|
|
"dayStartHour": 7,
|
|
"nightStartHour": 21
|
|
}
|
|
```
|
|
|
|
3. Install schedule worker:
|
|
|
|
```bash
|
|
bash ./scripts/install_model_schedule_guard_launchd.sh
|
|
```
|
|
|
|
Important:
|
|
- Installer syncs configs/scripts into a launchd-safe runtime folder:
|
|
- `~/Library/Application Support/openclaw-local-model-guard`
|
|
- After any config/script edits in this repo, re-run the installer to push updates.
|
|
|
|
4. Verify:
|
|
|
|
```bash
|
|
launchctl print gui/$(id -u)/ai.openclaw.local.model-schedule-guard
|
|
tail -n 50 /tmp/openclaw-model-schedule-guard.log /tmp/openclaw-model-schedule-guard.err.log
|
|
```
|
|
|
|
Notes:
|
|
- Schedule checks every 5 minutes by default.
|
|
- It self-corrects drift (if someone manually switches to the wrong profile during schedule window).
|
|
- If schedule is enabled, manual switches can be overridden on the next schedule run.
|
|
|
|
## 7) Do I Need To Run These Scripts All The Time?
|
|
|
|
No.
|
|
|
|
After install, schedule and budget guards run automatically through launchd.
|
|
You do not need to manually run guard scripts every day.
|
|
|
|
You only re-run install scripts when:
|
|
- You changed configs/scripts in this repo and want launchd runtime files refreshed.
|
|
- You stopped/disabled a guard and want to re-enable it.
|
|
- You want to change LaunchAgent interval/config and apply it again.
|
|
|
|
Quick health check:
|
|
|
|
```bash
|
|
launchctl print gui/$(id -u)/ai.openclaw.local.model-schedule-guard | rg 'last exit code|run interval|state'
|
|
launchctl print gui/$(id -u)/ai.openclaw.local.model-budget-guard | rg 'last exit code|run interval|state'
|
|
```
|
|
|
|
## 8) Enable Budget Guard (Recommended)
|
|
|
|
Install budget worker:
|
|
|
|
```bash
|
|
bash ./scripts/install_model_budget_guard_launchd.sh
|
|
```
|
|
|
|
Or install both schedule + budget at once:
|
|
|
|
```bash
|
|
bash ./scripts/install_local_model_guardrails.sh
|
|
```
|
|
|
|
Budget behavior from `config/model-budget-guard.config.json`:
|
|
- Warn after 2 minutes on high-cost model
|
|
- Auto-revert to `ollama/qwen3:14b` after 45 minutes
|
|
- Prevent repeated spam with minimum warning interval
|
|
|
|
## 9) View Current LaunchAgents
|
|
|
|
```bash
|
|
launchctl print gui/$(id -u)/ai.openclaw.local.model-schedule-guard
|
|
launchctl print gui/$(id -u)/ai.openclaw.local.model-budget-guard
|
|
```
|
|
|
|
Logs:
|
|
|
|
```bash
|
|
tail -f /tmp/openclaw-model-schedule-guard.log /tmp/openclaw-model-schedule-guard.err.log
|
|
tail -f /tmp/openclaw-model-budget-guard.log /tmp/openclaw-model-budget-guard.err.log
|
|
```
|
|
|
|
## 10) Manual Switching Tips
|
|
|
|
Preferred command (includes live session model push):
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh free
|
|
```
|
|
|
|
If you want fastest return and no live session push:
|
|
|
|
```bash
|
|
bash ./scripts/model_profile_switch.sh free --no-live
|
|
```
|
|
|
|
If command appears to take longer than expected, it is usually waiting on the live push step.
|
|
`Ctrl+C` is safe after config overwrite lines if needed, then verify with:
|
|
|
|
```bash
|
|
openclaw models status
|
|
```
|
|
|
|
## 11) Disable Automation
|
|
|
|
Stop/unload schedule + budget workers:
|
|
|
|
```bash
|
|
launchctl bootout gui/$(id -u)/ai.openclaw.local.model-schedule-guard 2>/dev/null || true
|
|
launchctl bootout gui/$(id -u)/ai.openclaw.local.model-budget-guard 2>/dev/null || true
|
|
```
|
|
|
|
Optional: set schedule config back to disabled:
|
|
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
## 12) Newbie Checklist
|
|
|
|
1. Confirm OpenClaw/Ollama/jq installed.
|
|
2. Run `bash ./scripts/model_profile_switch.sh status`.
|
|
3. Switch to free: `bash ./scripts/model_profile_switch.sh free`.
|
|
4. Confirm with `openclaw models status`.
|
|
5. If desired, enable schedule in `config/model-schedule.config.json`.
|
|
6. Install LaunchAgents.
|
|
7. Watch logs once to confirm jobs run cleanly.
|
|
|
|
## 13) FAQ
|
|
|
|
### Do I need to run schedule scripts every day?
|
|
No. Once installed, launchd runs them automatically.
|
|
|
|
### Why did my manual switch go back to paid/free?
|
|
Schedule is enforcing the configured time window and can override manual switches.
|
|
|
|
### Does ChatGPT Pro include API usage for OpenClaw?
|
|
No. ChatGPT subscription billing and API billing are separate.
|
|
|
|
### Can I switch instantly?
|
|
Yes. `bash ./scripts/model_profile_switch.sh free` (or `paid`) applies immediately.
|
|
|
|
### Can I keep paid model only during work hours?
|
|
Yes. Set day profile to `paid`, night profile to `free`, and install schedule worker.
|