OpenClaw-Setup/openclaw-setup-copilot/README.md

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 ./setup/setup_openclaw_copilot.sh
bash ./scripts/finalize_copilot_setup.sh
openclaw status --deep

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 ./setup/setup_openclaw_copilot.sh

2. Finalize in one command (recommended):

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:

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:

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:

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:

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

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:

openclaw gateway restart
openclaw status --deep
openclaw models status

7. Configure + install Copilot guardrails (recommended):

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:

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

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

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

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

8. Enable recommended hooks:

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

9. Verify hooks:

openclaw hooks list
openclaw hooks list --eligible

Daily Checks

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:

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.