TopDogLabs/OpenClaw-Setup
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
405433bb7f
OpenClaw-Setup/openclaw-setup-max/README.md

7.8 KiB
Raw Blame History

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 local profile (Ollama-only)
  • 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/moonshotai/kimi-k2.5
    • Fallbacks: ollama/qwen3:14b, ollama/llama3.2:3b
  • free profile:
    • Primary: ollama/qwen3:14b
    • Fallbacks: ollama/devstral:24b, ollama/llama3.2:3b

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

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:

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

Switch to free mode now:

cd /Volumes/Data/openclaw-setups/openclaw-setup-max
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 9pm-7am)

  1. Edit config:
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
open config/model-schedule.config.json
  1. Set:
{
  "enabled": true,
  "dayProfile": "paid",
  "nightProfile": "free",
  "dayStartHour": 7,
  "nightStartHour": 21
}
  1. 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.
  1. 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 ollama/qwen3:14b 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

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.