OpenClaw-Setup/openclaw-setup-max/PRD.md

PRD: OpenClaw Local Model Cost Control (Setup Max)

1) Document Purpose

Define requirements for a reusable OpenClaw setup that supports:

• Instant manual switching between paid and free model profiles
• Optional scheduled switching (day/night)
• Optional budget protection for expensive models

Audience:

• Primary: local operator (non-expert friendly)
• Secondary: future maintainer cloning this setup for another machine

2) Problem Statement

Running a paid model 24/7 can create unnecessary spend.
Operators need an easy way to:

• Switch to free local models on demand
• Automate free mode during off-hours
• Prevent accidental long-running use of expensive models

3) Goals

• G1: One-command live switch between paid and free profiles.
• G2: Support day/night automatic profile switching.
• G3: Provide guardrail warning + optional auto-revert from high-cost model usage.
• G4: Make setup operable by a newbie using copy/paste commands.

4) Non-Goals

• Building a new OpenClaw provider plugin.
• Replacing OpenClaw internal routing.
• Managing billing dashboards directly.

5) User Stories

• As an operator, I can run one command to switch to free local models immediately.
• As an operator, I can switch back to paid model for deep tasks.
• As an operator, I can set free mode from 9pm-7am automatically.
• As an operator, I get warned if expensive model remains active too long.
• As a maintainer, I can copy this folder to another Mac and follow docs to bootstrap.

6) Functional Requirements

FR-1 Profile Configuration

• System must define named model profiles in JSON:
  • paid
  • free
• Each profile must include:
  • primary model
  • ordered fallback list

Implementation:

• config/model-profiles.config.json

FR-2 Manual Live Switch

• Must support:
  • model_profile_switch.sh paid
  • model_profile_switch.sh free
• Must:
  • update OpenClaw primary model
  • reset + apply fallback list
  • optionally push /model <primary> to active session key
• Must support flags:
  • --no-live
  • --no-status
  • status

Implementation:

• scripts/model_profile_switch.sh

FR-3 Schedule Guard

• Must read schedule config and apply profile by hour.
• Must support day and night windows.
• Must run idempotently and avoid unnecessary switches.
• Must correct drift if current default model does not match expected scheduled profile.

Implementation:

• config/model-schedule.config.json
• scripts/model_schedule_guard.sh
• scripts/install_model_schedule_guard_launchd.sh

FR-4 Budget Guard

• Must detect if active session model is in high-cost allowlist.
• Must warn after configurable threshold.
• Must auto-revert after configurable threshold.
• Must throttle warnings/reverts to avoid spam loops.

Implementation:

• config/model-budget-guard.config.json
• scripts/model_budget_guard.sh
• scripts/install_model_budget_guard_launchd.sh

FR-5 Install Convenience

• Must provide one script to install both schedule and budget guards.

Implementation:

• scripts/install_local_model_guardrails.sh

FR-6 Documentation

• Must include a step-by-step README for first-time users.
• Must include verification commands and disable/uninstall steps.

Implementation:

• README.md

7) Non-Functional Requirements

• NFR-1 Reliability: scripts should be safe to run repeatedly.
• NFR-2 Observability: each LaunchAgent writes stdout/stderr logs to /tmp.
• NFR-3 Compatibility: target macOS + zsh/bash + OpenClaw CLI.
• NFR-4 Safety: avoid exposing secrets in script output.
• NFR-5 Usability: all common actions available as copy/paste commands.

8) Architecture Overview

Inputs:

• OpenClaw session state (~/.openclaw/agents/main/sessions/sessions.json)
• Profile/schedule/budget JSON configs

Executors:

• Manual CLI script (model_profile_switch.sh)
• Launchd workers (model_schedule_guard.sh, model_budget_guard.sh)

Outputs:

• Updated OpenClaw model + fallbacks in config
• Optional live /model message into active session
• Log files in /tmp

9) Operational Flow

Flow A: Manual Switch

1. Operator runs switch command.
2. Script loads profile from config.
3. Script applies primary + fallbacks.
4. Script pushes live model command to active session (unless --no-live).
5. Script prints status.

Flow B: Scheduled Switch

1. LaunchAgent triggers every 5 minutes.
2. Guard computes desired profile from local hour.
3. Guard checks last applied profile + current default model.
4. If mismatch, applies desired profile.
5. Guard stores state timestamp.

Flow C: Budget Protection

1. LaunchAgent triggers every 2 minutes.
2. Guard inspects active session model.
3. If model is high-cost:
   • warn after threshold
   • auto-revert after threshold
4. Guard updates state file for rate-limiting.

10) Acceptance Criteria

• AC-1: Running bash ./scripts/model_profile_switch.sh free changes default to openrouter/qwen/qwen3-coder:free.
• AC-2: Running bash ./scripts/model_profile_switch.sh paid restores default to openrouter/qwen/qwen3-coder:free.
• AC-3: With schedule enabled (21/7), profile changes correctly by local time window.
• AC-4: If operator manually drifts model during scheduled window, schedule guard re-aligns on next run.
• AC-5: Budget guard warns and reverts when high model remains active beyond thresholds.
• AC-6: New operator can follow README from zero knowledge and complete setup without editing scripts.

11) Risks and Mitigations

• Risk: model names differ across machines.
  • Mitigation: update config/model-profiles.config.json per machine.
• Risk: LaunchAgents not loaded after reboot/login changes.
  • Mitigation: include explicit launchctl print checks and reinstall command.
• Risk: missing CLI dependencies (jq, openclaw).
  • Mitigation: prerequisite checks in README.
• Risk: user confusion between ChatGPT subscription and API billing.
  • Mitigation: clear FAQ note in README.

12) Rollout Plan

1. Validate scripts (bash -n and status commands).
2. Perform manual switch tests (free then paid).
3. Enable schedule (enabled=true) and install schedule LaunchAgent.
4. Install budget LaunchAgent.
5. Monitor logs for one day.
6. Clone/copy to future machine and adjust profile model IDs as needed.

13) Future Enhancements

• Optional quiet-hours policy to disable non-essential notifications.
• Per-channel session key mapping (Telegram/Discord-specific switching).
• Daily spend estimator from model usage telemetry.
• Optional provider locking profile policies.