# OpenClaw Setup Max (Paid + Free Model Switching)

This workspace runs OpenClaw with:
- A paid high-quality model profile (`openrouter/moonshotai/kimi-k2.5`)
- A free OpenRouter profile
- One-command live switching
- Optional automatic day/night switching (example: free from 10pm-7am)
- Optional budget guard that warns and auto-reverts from expensive models

This guide covers both first-time setup and in-place upgrades.

## 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/moonshotai/kimi-k2.5`
  - 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
- `config/models.env`: single-source model + schedule variables
- `scripts/sync_models_from_env.sh`: sync JSON configs from `config/models.env`
- `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
- `scripts/update_openclaw.sh`: in-place OpenClaw upgrade + migration workflow
- `docs/operations/UPGRADING.md`: upgrade runbook for existing installs
- `docs/operations/troubleshooting.md`: known issue recovery commands

## 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`
- If `~/.openclaw` is symlinked to an external volume (`/Volumes/...`), setup patches gateway LaunchAgent logs to `/tmp/openclaw-gateway.launchd*.log` to avoid launchd `EX_CONFIG` failures.
- 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
```

## 3A) Update Existing Install (In-place)

Use this for upgrades on an already-working machine:

```bash
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/update_openclaw.sh
```

What it handles:
- Backup of `~/.openclaw/openclaw.json` + main `sessions.json`
- Config migration (`openclaw doctor --fix --non-interactive`)
- CLI update with timeout + npm fallback
- Timestamped step logging in terminal output
- Explicit gateway stop/start
- Gateway LaunchAgent self-heal (install if missing)
- External-drive launchd log-path patch (`/tmp/openclaw-gateway.launchd*.log`)
- Reinstall + immediate kickstart of budget/schedule guards
- Final model/profile/gateway verification output

Useful options:

```bash
# Switch update channel
bash ./scripts/update_openclaw.sh --channel beta

# Pin one update run to a version/tag
bash ./scripts/update_openclaw.sh --tag 2026.2.24

# Increase built-in updater timeout (seconds)
UPDATE_MAX_SECONDS=900 bash ./scripts/update_openclaw.sh

# Save a timestamped run log file
bash ./scripts/update_openclaw.sh 2>&1 | tee "/tmp/openclaw-update-$(date +%Y%m%d-%H%M%S).log"
```

Detailed runbook:
- `docs/operations/UPGRADING.md`

## 4) Quick Start (Most Common)

Use env-driven sync + hygiene workflow (recommended after any model changes):

```bash
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/sync_models_from_env.sh
bash ./scripts/model_hygiene_workflow.sh paid
```

Edit `config/models.env` whenever you want to change paid/free models or schedule windows.

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 10pm-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": 22
}
```

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 `openrouter/qwen/qwen3-coder:free` 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
tail -f /tmp/openclaw-gateway.launchd.log /tmp/openclaw-gateway.launchd.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.