From 558bbf47f69176bfe63949e5991ef2f4b69156bb Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Thu, 19 Feb 2026 12:47:36 -0600 Subject: [PATCH] feat: add one-command copilot finalize flow --- openclaw-setup-copilot/AGENTS.md | 18 +--- openclaw-setup-copilot/README.md | 42 ++++---- .../docs/operations/AI_SETUP_HANDOFF.md | 13 +-- .../docs/operations/WORK_SETUP_CHECKLIST.md | 48 ++++++--- .../docs/operations/troubleshooting.md | 3 +- .../scripts/finalize_copilot_setup.sh | 100 ++++++++++++++++++ .../setup/setup_openclaw_copilot.sh | 44 ++++---- 7 files changed, 189 insertions(+), 79 deletions(-) create mode 100755 openclaw-setup-copilot/scripts/finalize_copilot_setup.sh diff --git a/openclaw-setup-copilot/AGENTS.md b/openclaw-setup-copilot/AGENTS.md index 590830b..4acd81c 100644 --- a/openclaw-setup-copilot/AGENTS.md +++ b/openclaw-setup-copilot/AGENTS.md @@ -20,6 +20,7 @@ When you copy this folder to the target work machine: - Do not run install commands here. - Do not run `scripts/install_copilot_guardrails.sh` here. +- Do not run `scripts/finalize_copilot_setup.sh` here. - Do not run provider/model mutation commands here. - Use this copy only for editing docs/scripts before transfer. @@ -31,13 +32,8 @@ When you copy this folder to the target work machine: Required setup order: 1. `bash ./setup/setup_openclaw_copilot.sh` -2. `copilot auth login` -3. `bash ./scripts/install_copilot_guardrails.sh` -4. `openclaw hooks enable boot-md` -5. `openclaw hooks enable command-logger` -6. `openclaw hooks enable session-memory` -7. `openclaw gateway restart` -8. `openclaw status --deep` +2. `bash ./scripts/finalize_copilot_setup.sh` +3. `openclaw status --deep` Required verification: - `openclaw models status` shows `github-copilot/*` routing. @@ -58,12 +54,8 @@ Create a reliable OpenClaw setup that uses GitHub Copilot CLI Enterprise as the ## Setup Flow (target computer only) 1. Run `setup/setup_openclaw_copilot.sh` for Copilot-first baseline. -2. Authenticate Copilot CLI with enterprise account. -3. Refresh OpenClaw model catalog. -4. Lock OpenClaw model routing to Copilot models. -5. Install guardrails with `scripts/install_copilot_guardrails.sh`. -6. Enable recommended hooks (`boot-md`, `command-logger`, `session-memory`). -7. Start gateway and verify Telegram/channel health. +2. Run `scripts/finalize_copilot_setup.sh` to complete auth + profiles + guardrails in one command. +3. Verify gateway/model health. ## Copilot CLI Install and Auth diff --git a/openclaw-setup-copilot/README.md b/openclaw-setup-copilot/README.md index 174c2a5..50c0a14 100644 --- a/openclaw-setup-copilot/README.md +++ b/openclaw-setup-copilot/README.md @@ -38,6 +38,7 @@ Everything else is organized by purpose: - `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 @@ -68,24 +69,20 @@ 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 +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. `copilot auth login` must succeed before Copilot models can be used. -3. Only after login should you run model routing and guardrails. +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: @@ -94,22 +91,29 @@ Why: bash ./setup/setup_openclaw_copilot.sh ``` -2. Authenticate Copilot CLI: +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 +- Auto-picks paid/free profiles from available Copilot models +- Installs all guardrails +- Enables recommended hooks +- Restarts gateway + +3. Verify: ```bash -copilot auth login copilot auth status -``` - -3. Refresh/list OpenClaw models: - -```bash -openclaw models refresh -openclaw models list openclaw models status +openclaw status --deep ``` -If login is missing/expired, Copilot model discovery and usage will fail. +If login is missing/expired, finalize will prompt for login and retry setup. ### How To Choose Copilot Models (and Why It Matters) @@ -229,7 +233,7 @@ Expected schedule config shape: Important behavior difference vs Max: - Copilot `config/model-profiles.config.json` starts with empty model IDs in this template copy. -- `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`. +- `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: diff --git a/openclaw-setup-copilot/docs/operations/AI_SETUP_HANDOFF.md b/openclaw-setup-copilot/docs/operations/AI_SETUP_HANDOFF.md index 54dc0b4..cec864a 100644 --- a/openclaw-setup-copilot/docs/operations/AI_SETUP_HANDOFF.md +++ b/openclaw-setup-copilot/docs/operations/AI_SETUP_HANDOFF.md @@ -20,14 +20,9 @@ Constraints: Run in this order: 1) bash ./setup/setup_openclaw_copilot.sh -2) copilot auth login - - pause and wait for user to complete browser login -3) bash ./scripts/install_copilot_guardrails.sh -4) openclaw hooks enable boot-md -5) openclaw hooks enable command-logger -6) openclaw hooks enable session-memory -7) openclaw gateway restart -8) openclaw status --deep +2) bash ./scripts/finalize_copilot_setup.sh + - if prompted, pause and wait for user to complete browser login +3) openclaw status --deep After setup, verify and report: - copilot auth status is healthy @@ -55,7 +50,7 @@ If any check fails, fix it and rerun verification. ## Manual User Actions Expected -- Complete enterprise login in browser when `copilot auth login` opens auth flow. +- Complete enterprise login in browser when `finalize_copilot_setup.sh` opens `copilot auth login`. - Approve enterprise/SSO/MFA prompts as required. ## One-Line Start (for human) diff --git a/openclaw-setup-copilot/docs/operations/WORK_SETUP_CHECKLIST.md b/openclaw-setup-copilot/docs/operations/WORK_SETUP_CHECKLIST.md index 4ded4ad..bd8705c 100644 --- a/openclaw-setup-copilot/docs/operations/WORK_SETUP_CHECKLIST.md +++ b/openclaw-setup-copilot/docs/operations/WORK_SETUP_CHECKLIST.md @@ -37,16 +37,32 @@ which copilot copilot --version ``` -## 3) Authenticate Copilot CLI (Enterprise account) +## 3) Finalize setup in one command (recommended) + +```bash +bash ./scripts/finalize_copilot_setup.sh +``` + +Expected: +- Authenticated with enterprise-linked account +- Copilot models discovered +- Guardrails installed + running +- Hooks enabled (`boot-md`, `command-logger`, `session-memory`) +- Gateway restarted + +If this step succeeds, you can skip to step 10. + +## 4) Manual fallback path (advanced, only if step 3 fails) + +If finalize fails due auth/browser flow, run: ```bash copilot auth login copilot auth status ``` -Expected: authenticated with your enterprise-linked GitHub account. - -## 4) Start/verify OpenClaw gateway +Then continue below. +## 5) Start/verify OpenClaw gateway ```bash openclaw gateway restart @@ -55,7 +71,7 @@ openclaw status --deep Expected: gateway reachable. -## 5) Discover available models +## 6) Discover available models ```bash openclaw models refresh || true @@ -79,7 +95,7 @@ Why this matters: - Lower quota burn by not overusing heavyweight models - Better uptime through fallback failover -## 6) Set Copilot primary + fallbacks +## 7) Set Copilot primary + fallbacks Replace models below with names from your `openclaw models list` output if needed. @@ -102,7 +118,7 @@ Expected: - Fallback chain includes only free-tier or low-cost models - Only `github-copilot/*` appears if strict enterprise policy is required -## 7) Optional strict provider lock (Copilot-only) +## 8) Optional strict provider lock (Copilot-only) Run if your enterprise policy requires only Copilot provider traffic: @@ -121,7 +137,9 @@ openclaw models list openclaw models status ``` -## 8) Configure + install Copilot guardrails (recommended) +## 9) Configure + install Copilot guardrails (recommended) + +If step 3 already succeeded, this is already done. This one command auto-detects your available Copilot models, picks low-cost defaults, applies policy, and installs launchd guards: @@ -151,7 +169,9 @@ Why this matters: - Work-hours/off-hours profile schedule is auto-enforced - Protects enterprise quota and keeps routine latency low -## 9) Enable recommended hooks +## 10) Enable recommended hooks + +If step 3 already succeeded, hooks were already enabled. ```bash openclaw hooks enable boot-md @@ -160,7 +180,7 @@ openclaw hooks enable session-memory openclaw hooks list ``` -## 10) Persona/startup docs sanity +## 11) Persona/startup docs sanity Confirm these files exist in workspace root: @@ -168,7 +188,7 @@ Confirm these files exist in workspace root: ls -la AGENTS.md docs/context/BOOT.md docs/context/SOUL.md docs/context/IDENTITY.md docs/context/USER.md docs/context/TOOLS.md docs/operations/troubleshooting.md ``` -## 11) Telegram/channel check (if used) +## 12) Telegram/channel check (if used) Telegram account rule: - No new personal Telegram account is required. @@ -181,7 +201,7 @@ openclaw status --deep Expected: channel `OK` and gateway reachable. -## 12) First chat checks +## 13) First chat checks In your chat surface: @@ -190,7 +210,7 @@ In your chat surface: Expected: response is fast and uses a `github-copilot/*` model. -## 13) Daily operations +## 14) Daily operations ```bash openclaw status --deep @@ -198,7 +218,7 @@ openclaw models status copilot auth status ``` -## 14) Fast failure recovery +## 15) Fast failure recovery ```bash openclaw gateway restart diff --git a/openclaw-setup-copilot/docs/operations/troubleshooting.md b/openclaw-setup-copilot/docs/operations/troubleshooting.md index da31b17..2dfa273 100644 --- a/openclaw-setup-copilot/docs/operations/troubleshooting.md +++ b/openclaw-setup-copilot/docs/operations/troubleshooting.md @@ -179,8 +179,7 @@ Fixes: - For a quick manual switch without live push: - `bash ./scripts/model_profile_switch.sh free --no-live` - If `profiles.paid.primary` / `profiles.free.primary` are empty, run: - - `copilot auth login` - - `bash ./scripts/install_copilot_guardrails.sh` + - `bash ./scripts/finalize_copilot_setup.sh` This populates `config/model-profiles.config.json` and restages launchd runtime configs. ## 12) Copilot auth watchdog alerting repeatedly diff --git a/openclaw-setup-copilot/scripts/finalize_copilot_setup.sh b/openclaw-setup-copilot/scripts/finalize_copilot_setup.sh new file mode 100755 index 0000000..276cd47 --- /dev/null +++ b/openclaw-setup-copilot/scripts/finalize_copilot_setup.sh @@ -0,0 +1,100 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" + +log_info() { echo "[finalize] $*"; } +log_warn() { echo "[finalize] WARN: $*" >&2; } +log_err() { echo "[finalize] ERROR: $*" >&2; } + +require_cmd() { + local cmd="$1" + if ! command -v "$cmd" >/dev/null 2>&1; then + log_err "Missing required command: $cmd" + exit 1 + fi +} + +copilot_authed() { + copilot auth status >/dev/null 2>&1 +} + +refresh_models() { + openclaw models refresh >/dev/null 2>&1 || true +} + +copilot_model_count() { + openclaw models list 2>/dev/null \ + | awk 'NR>1 && /^github-copilot\// {count++} END {print count+0}' +} + +require_cmd openclaw +require_cmd copilot +require_cmd jq + +if ! copilot_authed; then + log_warn "Copilot auth is not active." + if [[ -t 0 ]]; then + log_info "Launching interactive login: copilot auth login" + copilot auth login + else + log_err "Non-interactive shell cannot complete browser login." + log_err "Run: copilot auth login" + exit 1 + fi +fi + +if ! copilot_authed; then + log_err "Copilot auth still not active after login." + log_err "Run 'copilot auth status' and resolve auth issues, then retry." + exit 1 +fi + +log_info "Refreshing model catalog..." +refresh_models + +count="$(copilot_model_count)" +if [[ "$count" -eq 0 ]]; then + log_warn "No github-copilot models detected yet. Restarting gateway and retrying once." + openclaw gateway restart >/dev/null 2>&1 || true + sleep 1 + refresh_models + count="$(copilot_model_count)" +fi + +if [[ "$count" -eq 0 ]]; then + log_err "No github-copilot models available to configure." + log_err "Check entitlement/auth, then rerun this script." + openclaw models list || true + exit 1 +fi + +log_info "Detected $count Copilot model(s). Installing guardrails + model profiles..." +bash "$SCRIPT_DIR/install_copilot_guardrails.sh" + +log_info "Enabling recommended hooks..." +openclaw hooks enable boot-md >/dev/null 2>&1 || true +openclaw hooks enable command-logger >/dev/null 2>&1 || true +openclaw hooks enable session-memory >/dev/null 2>&1 || true + +log_info "Restarting gateway..." +openclaw gateway restart >/dev/null 2>&1 || true + +log_info "Final status checks:" +copilot auth status || true +openclaw models status || true + +for label in \ + ai.openclaw.model-budget-guard \ + ai.openclaw.copilot-policy-guard \ + ai.openclaw.copilot-auth-watchdog \ + ai.openclaw.copilot-model-schedule-guard; do + if launchctl print "gui/$(id -u)/$label" >/dev/null 2>&1; then + echo "[finalize] launchd OK: $label" + else + echo "[finalize] launchd WARN: $label not loaded" + fi +done + +log_info "Done. Copilot setup is fully configured." diff --git a/openclaw-setup-copilot/setup/setup_openclaw_copilot.sh b/openclaw-setup-copilot/setup/setup_openclaw_copilot.sh index b95915b..582062b 100755 --- a/openclaw-setup-copilot/setup/setup_openclaw_copilot.sh +++ b/openclaw-setup-copilot/setup/setup_openclaw_copilot.sh @@ -2,6 +2,8 @@ set -euo pipefail +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + GREEN='\033[0;32m' YELLOW='\033[1;33m' RED='\033[0;31m' @@ -76,32 +78,30 @@ else log_info "Copilot CLI already installed ($(copilot --version 2>/dev/null || echo present))." fi +FINALIZE_SCRIPT="$SCRIPT_DIR/../scripts/finalize_copilot_setup.sh" +if [[ -x "$FINALIZE_SCRIPT" ]]; then + if copilot auth status >/dev/null 2>&1; then + log_info "Copilot auth already active. Running finalize flow now..." + if ! bash "$FINALIZE_SCRIPT"; then + log_warn "Finalize flow failed. Re-run manually after checking auth/models:" + echo " bash ./scripts/finalize_copilot_setup.sh" + fi + else + log_warn "Final setup step still needed after login:" + echo " bash ./scripts/finalize_copilot_setup.sh" + fi +fi + echo "" log_info "Setup complete (Copilot-first)." echo "" echo "Next steps (target machine):" -echo "1. Authenticate Copilot CLI with enterprise account:" +echo "1. Run one-command finalize (recommended):" +echo " bash ./scripts/finalize_copilot_setup.sh" +echo "2. If finalize cannot open browser login, authenticate first:" echo " copilot auth login" echo " copilot auth status" -echo "2. Start/verify OpenClaw gateway:" -echo " openclaw gateway restart" +echo " bash ./scripts/finalize_copilot_setup.sh" +echo "3. Verify:" echo " openclaw status --deep" -echo "3. Discover and set Copilot models:" -echo " openclaw models refresh || true" -echo " openclaw models list" -echo " openclaw models set github-copilot/" -echo "4. Configure fallbacks:" -echo " openclaw models fallbacks clear" -echo " openclaw models fallbacks add github-copilot/" -echo " openclaw models fallbacks add github-copilot/" -echo "5. Optional strict provider lock:" -echo " openclaw config set --json providers.github-copilot.enabled true" -echo " openclaw config set --json providers.openai.enabled false" -echo " openclaw config set --json providers.anthropic.enabled false" -echo " openclaw config set --json providers.openrouter.enabled false" -echo "6. Install Copilot guardrails (recommended):" -echo " bash ./scripts/install_copilot_guardrails.sh" -echo "7. Ensure recommended hooks are enabled:" -echo " openclaw hooks enable boot-md" -echo " openclaw hooks enable command-logger" -echo " openclaw hooks enable session-memory" +echo " openclaw models status"