270 lines
8.1 KiB
Markdown
270 lines
8.1 KiB
Markdown
# 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
|
|
- `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
|
|
copilot auth login
|
|
bash ./scripts/install_copilot_guardrails.sh
|
|
openclaw hooks enable boot-md
|
|
openclaw hooks enable command-logger
|
|
openclaw hooks enable session-memory
|
|
openclaw gateway restart
|
|
openclaw status --deep
|
|
```
|
|
|
|
Order and dependency (important):
|
|
|
|
1. `setup/setup_openclaw_copilot.sh` installs tooling only (`openclaw`, `copilot`, Node).
|
|
2. `copilot auth login` must succeed before Copilot models can be used.
|
|
3. Only after login should you run model routing and guardrails.
|
|
|
|
Why:
|
|
- OpenClaw installation does not require Copilot login.
|
|
- `github-copilot/*` model selection and policy checks do require Copilot auth.
|
|
|
|
|
|
1. Primary Copilot setup:
|
|
|
|
```bash
|
|
bash ./setup/setup_openclaw_copilot.sh
|
|
```
|
|
|
|
2. Authenticate Copilot CLI:
|
|
|
|
```bash
|
|
copilot auth login
|
|
copilot auth status
|
|
```
|
|
|
|
3. Refresh/list OpenClaw models:
|
|
|
|
```bash
|
|
openclaw models refresh
|
|
openclaw models list
|
|
openclaw models status
|
|
```
|
|
|
|
If login is missing/expired, Copilot model discovery and usage will fail.
|
|
|
|
### 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
|
|
|
|
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.
|