OpenClaw-Setup/openclaw-setup-max

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:

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:

# 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:

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:

# 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):

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 ./scripts/model_profile_switch.sh free

Switch back to paid mode:

bash ./scripts/model_profile_switch.sh paid

Check current model state:

bash ./scripts/model_profile_switch.sh status

Run a web research task from terminal:

./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 ./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 ./scripts/model_profile_switch.sh free --no-live

6) Enable Schedule (Example: Free 10pm-7am)

1. Edit config:

cd /Volumes/Data/openclaw-setups/openclaw-setup-max
open config/model-schedule.config.json

2. Set:

{
  "enabled": true,
  "dayProfile": "paid",
  "nightProfile": "free",
  "dayStartHour": 7,
  "nightStartHour": 22
}

3. Install schedule worker:

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:

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:

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 ./scripts/install_model_budget_guard_launchd.sh

Or install both schedule + budget at once:

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

launchctl print gui/$(id -u)/ai.openclaw.local.model-schedule-guard
launchctl print gui/$(id -u)/ai.openclaw.local.model-budget-guard

Logs:

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 ./scripts/model_profile_switch.sh free

If you want fastest return and no live session push:

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:

openclaw models status

11) Disable Automation

Stop/unload schedule + budget workers:

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:

{
  "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.