# OpenClaw Work Setup Template

Template workspace for setting up OpenClaw on a work computer with GitHub Copilot CLI Enterprise as the primary model provider, plus an iOS-focused assistant persona.

## Purpose

Use this folder as a repeatable setup baseline on another machine.

- Primary provider: GitHub Copilot Enterprise
- Persona: Senior iOS Engineer (architecture + refactoring focused)

## Important

This repository is intended as a guide/template.
Do not run mutation commands on an already-stable machine unless intended.

## Workspace Layout

Keep only operator docs at root:
- `AGENTS.md`
- `README.md`
- `PRD.md`

Everything else is organized by purpose:
- `setup/`: one-time bootstrap installers
- `scripts/`: guardrails, switching, and launchd installers
- `config/`: editable policy/profile/schedule/auth JSON
- `docs/context/`: runtime persona + user/context files
- `docs/operations/`: handoff/checklist/troubleshooting docs
- `memory/`: session memory files

## Workspace Files

- `AGENTS.md`: operating rules and setup sequence
- `docs/context/BOOT.md`: startup checks
- `docs/context/SOUL.md`: persona behavior
- `docs/context/USER.md`: user context
- `docs/context/TOOLS.md`: command reference
- `docs/operations/troubleshooting.md`: failure recovery runbook
- `setup/setup_openclaw_copilot.sh`: primary Copilot Enterprise setup
- `scripts/finalize_copilot_setup.sh`: one-command auth + model/profile + guardrail finalize
- `config/copilot-policy-guard.config.json`: Copilot routing/provider policy guard config
- `config/copilot-auth-watchdog.config.json`: Copilot auth watchdog config
- `config/model-profiles.config.json`: paid/free profile routing definitions
- `config/model-schedule.config.json`: work-hours/off-hours schedule config
- `scripts/install_copilot_guardrails.sh`: installs all launchd guardrails

## Target Machine Prerequisites

- macOS with Homebrew
- Node.js + npm
- OpenClaw installed
- GitHub Enterprise account with Copilot CLI entitlement

## Telegram Note (If Used)

- You do **not** need a new Telegram user account or phone number.
- One personal Telegram account is enough.
- Create a bot with `@BotFather`; bots are separate from user accounts.
- You chat with the bot from your existing Telegram account.

## Setup (Target Computer)

AI handoff:
- Use `docs/operations/AI_SETUP_HANDOFF.md` when delegating setup to another AI assistant.
- It includes a strict prompt, command order, and verification checks.

Quick path (copy/paste):

```bash
bash ./setup/setup_openclaw_copilot.sh
bash ./scripts/finalize_copilot_setup.sh
openclaw status --deep
```

Optional custom install locations:

```bash
# Move OpenClaw runtime data (~/.openclaw) to another path
OPENCLAW_DATA_TARGET=/Volumes/Data/openclaw-copilot bash ./setup/setup_openclaw_copilot.sh

# Install global npm CLIs into a custom prefix/bin
NPM_GLOBAL_PREFIX="$HOME/.npm-global" bash ./setup/setup_openclaw_copilot.sh

# Use both
OPENCLAW_DATA_TARGET=/Volumes/Data/openclaw-copilot \
NPM_GLOBAL_PREFIX="$HOME/.npm-global" \
bash ./setup/setup_openclaw_copilot.sh
```

Order and dependency (important):

1. `setup/setup_openclaw_copilot.sh` installs tooling only (`openclaw`, `copilot`, Node).
2. `scripts/finalize_copilot_setup.sh` handles login, model discovery, profile selection, guardrails, hooks, and gateway restart.
3. If browser auth cannot complete inside finalize flow, run `copilot auth login`, then rerun finalize.

Why:
- OpenClaw installation does not require Copilot login.
- `github-copilot/*` model selection and policy checks do require Copilot auth.
- Finalize script prevents users from forgetting model/profile/guardrail wiring after login.


1. Primary Copilot setup:

```bash
bash ./setup/setup_openclaw_copilot.sh
```

If using a custom location:

```bash
OPENCLAW_DATA_TARGET=/Volumes/Data/openclaw-copilot bash ./setup/setup_openclaw_copilot.sh
```

2. Finalize in one command (recommended):

```bash
bash ./scripts/finalize_copilot_setup.sh
```

What finalize does:
- Opens `copilot auth login` if needed
- Refreshes model catalog
- Prompts you to choose the paid profile model from non-free candidates
- Auto-picks the free profile model/fallbacks from low-cost candidates
- Installs all guardrails
- Enables recommended hooks
- Restarts gateway

3. Verify:

```bash
copilot auth status
openclaw models status
openclaw status --deep
```

If login is missing/expired, finalize will prompt for login and retry setup.

For unattended/non-interactive automation:

```bash
PROMPT_FOR_PAID_MODEL=false bash ./scripts/finalize_copilot_setup.sh
```

### How To Choose Copilot Models (and Why It Matters)

Choosing the right primary and fallback models is important because it controls:

- Response speed in chat/Telegram
- Quality of coding/refactoring output
- Enterprise quota burn and cost exposure
- Reliability when one model is rate-limited or unavailable

Fallback policy for this template:
- Fallbacks must be free-tier or lowest-cost models only.
- Do not use premium fallbacks (for example Opus-class) as defaults.
- In strict Copilot-only mode, "free" means no extra external provider billing and lowest-burn models in your enterprise seat.

Recommended strategy:

1. Set a fast, general coding model as `primary` for daily work.
2. Add 1-2 low-cost fallbacks only.
3. Keep names exactly as shown in `openclaw models list` to avoid unknown-model failures.

Selection guide:

- Fast default: choose the quickest Sonnet/Codex variant your seat exposes
- Prefer fast/cheap variants over premium models for fallback
- Avoid premium fallbacks as defaults to prevent silent quota drain

4. Set Copilot model routing:

```bash
openclaw models set github-copilot/claude-sonnet-4.6
openclaw models fallbacks clear
openclaw models fallbacks add github-copilot/<free-or-low-cost-fallback-1>
openclaw models fallbacks add github-copilot/<free-or-low-cost-fallback-2>
```

After setting this, always verify:

```bash
openclaw models status
```

You should see a Copilot model as default plus your fallback chain.

5. Optional strict provider lock (if policy requires strict allowlist):

```bash
openclaw config set --json providers.github-copilot.enabled true
openclaw config set --json providers.openai.enabled false
openclaw config set --json providers.anthropic.enabled false
openclaw config set --json providers.openrouter.enabled false
```

6. Restart and verify:

```bash
openclaw gateway restart
openclaw status --deep
openclaw models status
```

7. Configure + install Copilot guardrails (recommended):

```bash
bash ./scripts/install_copilot_guardrails.sh
```

Guard config files:
- `config/model-budget-guard.config.json`
- `config/copilot-policy-guard.config.json`
- `config/copilot-auth-watchdog.config.json`
- `config/model-profiles.config.json`
- `config/model-schedule.config.json`

Runtime staging note (important):
- Installer stages active guard scripts/config into:
  - `~/Library/Application Support/openclaw-copilot-guard`
- Launchd runs guards from that staged folder, not directly from repository path.
- After editing guard scripts/config in this repo, re-run:
  - `bash ./scripts/install_copilot_guardrails.sh`
  to sync staged runtime files.

What it does:
- Model budget guard: warns on high-cost model usage and auto-reverts to low-cost model
- Copilot policy guard: enforces Copilot-only provider/model policy and fixes drift
- Copilot auth watchdog: alerts when Copilot auth expires or becomes unhealthy
- Model schedule guard: uses paid profile during work hours and free profile off-hours

Why this is important:
- Prevents someone from staying on high-tier models all day
- Reduces accidental enterprise quota burn
- Keeps day-to-day latency faster with a low-cost default

Default schedule behavior:
- Work hours (`08:00` to `18:00` local time): `paid` profile
- Off-hours (`18:00` to `08:00` local time): `free` profile

Schedule wiring (important):
- `config/model-schedule.config.json` controls time windows and which script applies profiles.
- `switchScript` should be `./scripts/model_profile_switch.sh`.
- `config/model-profiles.config.json` defines what `paid` and `free` actually mean (primary + fallbacks).

Expected schedule config shape:

```json
{
  "enabled": true,
  "dayProfile": "paid",
  "nightProfile": "free",
  "dayStartHour": 8,
  "nightStartHour": 18,
  "sessionKey": "agent:main:main",
  "switchScript": "./scripts/model_profile_switch.sh",
  "stateFile": "~/.openclaw/model-schedule-state.json"
}
```

Important behavior difference vs Max:
- Copilot `config/model-profiles.config.json` starts with empty model IDs in this template copy.
- `bash ./scripts/finalize_copilot_setup.sh` (or `bash ./scripts/install_copilot_guardrails.sh`) runs `configure_copilot_guardrails_defaults.sh`, detects available `github-copilot/*` models, and writes concrete `paid`/`free` models into `config/model-profiles.config.json`.
- Until that step runs on the target machine (after `copilot auth login`), schedule/profile switching has no concrete model IDs to apply.

Quick verify commands:

```bash
cat config/model-schedule.config.json
cat config/model-profiles.config.json
```

After installing guardrails, verify staged runtime files used by launchd:

```bash
cat ~/Library/Application\ Support/openclaw-copilot-guard/model-schedule.config.json
cat ~/Library/Application\ Support/openclaw-copilot-guard/model-profiles.config.json
```

Manual profile switch:

```bash
bash ./scripts/model_profile_switch.sh paid
bash ./scripts/model_profile_switch.sh free
bash ./scripts/model_profile_switch.sh status
```

If you need a quick switch without sending a live `/model` message:

```bash
bash ./scripts/model_profile_switch.sh free --no-live
```

8. Enable recommended hooks:

```bash
openclaw hooks enable boot-md
openclaw hooks enable command-logger
openclaw hooks enable session-memory
```

9. Verify hooks:

```bash
openclaw hooks list
openclaw hooks list --eligible
```

## Daily Checks

```bash
openclaw status --deep
openclaw models status
copilot auth status
```

If responses feel slow or weak, re-check model routing first before debugging gateway/network.

Model guard health:

```bash
launchctl print gui/$(id -u)/ai.openclaw.model-budget-guard
launchctl print gui/$(id -u)/ai.openclaw.copilot-policy-guard
launchctl print gui/$(id -u)/ai.openclaw.copilot-auth-watchdog
launchctl print gui/$(id -u)/ai.openclaw.copilot-model-schedule-guard
tail -n 30 /tmp/openclaw-model-budget-guard.log /tmp/openclaw-model-budget-guard.err.log
tail -n 30 /tmp/openclaw-copilot-policy-guard.log /tmp/openclaw-copilot-policy-guard.err.log
tail -n 30 /tmp/openclaw-copilot-auth-watchdog.log /tmp/openclaw-copilot-auth-watchdog.err.log
tail -n 30 /tmp/openclaw-copilot-model-schedule-guard.log /tmp/openclaw-copilot-model-schedule-guard.err.log
```

## Troubleshooting

Start with `docs/operations/troubleshooting.md`.

## Security Notes

- Never print full API keys/tokens in logs or chat.
- Rotate any secret that may have been exposed.