OpenClaw-Setup/openclaw-setup-copilot/docs/operations/troubleshooting.md

Troubleshooting - OpenClaw + Copilot Enterprise (Target Machine)

This guide is for the work computer setup.

Quick triage

openclaw status --deep
openclaw models status
copilot auth status

1) Copilot auth failure

Symptoms:

• copilot auth status not authenticated
• prompts fail with auth errors

Fix:

copilot auth login
copilot auth status

Make sure browser login uses the enterprise-linked GitHub account.

2) No Copilot model entitlement

Symptoms:

• auth is valid but model usage denied

Cause:

• org/enterprise policy does not permit Copilot CLI

Fix:

• ask enterprise admin to enable Copilot CLI entitlement for your seat

3) Unknown model in OpenClaw

Fix:

openclaw models refresh
openclaw models list

If models refresh is missing in your version, skip it and use openclaw models list.

4) OpenClaw config patch not available

Symptoms:

• guide references openclaw config patch, command not found

Fix:

• use openclaw config set --json <path> <value> commands instead
• use openclaw models set and openclaw models fallbacks commands for routing

5) Still seeing non-Copilot providers

Fix provider toggles:

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
openclaw gateway restart

6) Telegram/channel slow responses

Fixes:

• start a fresh session with /new
• keep default model on a fast Copilot model
• verify gateway health and provider auth

openclaw status --deep
openclaw models status

Telegram account confusion:

• You do not need a second Telegram user account.
• Keep your current personal Telegram account.
• Create/connect only the bot token from @BotFather.

7) Cost and quota management

• Use fast/cheap Copilot model as default
• Use /new for unrelated tasks
• Use compaction if available in your OpenClaw build

8) Wrong model mix (common quality/latency issue)

Symptoms:

• Replies are slow even when gateway is healthy
• Refactor suggestions are weak/inconsistent
• Quota burns too fast for routine tasks

Cause:

• Heavy reasoning model set as default for all prompts
• No fallback diversity (all fast or all heavy)

Fix:

1. Set a fast default model for day-to-day requests.
2. Keep fallbacks free-tier or low-cost only.
3. Remove premium fallback models from default routing.

Then verify:

openclaw models list
openclaw models status

9) High-model guardrail not prompting or not switching back

Checks:

launchctl print gui/$(id -u)/ai.openclaw.model-budget-guard
tail -n 100 /tmp/openclaw-model-budget-guard.log /tmp/openclaw-model-budget-guard.err.log
cat config/model-budget-guard.config.json
cat ~/Library/Application\ Support/openclaw-copilot-guard/model-budget-guard.config.json

Common fixes:

• Wrong model IDs in highModels
  • Use exact IDs from openclaw models list.
• lowModel not available
  • Set to a model your seat can access.
• Guard not installed/loaded
  • Re-run bash ./scripts/install_copilot_guardrails.sh.
• Repo config changed but staged runtime is stale
  • Re-run bash ./scripts/install_copilot_guardrails.sh to re-stage current files.
• Session key mismatch
  • Keep sessionKey as agent:main:main unless you intentionally use another session.

10) Copilot policy guard keeps fixing config unexpectedly

Cause:

• config/copilot-policy-guard.config.json has autoFix=true and policy values that differ from your manual changes.

Fix:

1. Edit config/copilot-policy-guard.config.json.
2. Set your intended providerPolicy, desiredPrimaryModel, and fallback rules.
3. If you want alert-only mode, set autoFix to false.

Verify logs:

tail -n 100 /tmp/openclaw-copilot-policy-guard.log /tmp/openclaw-copilot-policy-guard.err.log
cat ~/Library/Application\ Support/openclaw-copilot-guard/copilot-policy-guard.config.json

11) Manual model switch keeps changing back

Cause:

• Schedule guard is enabled and re-applies the expected profile by time window.
  • 08:00-18:00 -> paid profile
  • 18:00-08:00 -> free profile

Checks:

launchctl print gui/$(id -u)/ai.openclaw.copilot-model-schedule-guard
tail -n 100 /tmp/openclaw-copilot-model-schedule-guard.log /tmp/openclaw-copilot-model-schedule-guard.err.log
cat config/model-schedule.config.json
cat config/model-profiles.config.json
cat ~/Library/Application\ Support/openclaw-copilot-guard/model-schedule.config.json
cat ~/Library/Application\ Support/openclaw-copilot-guard/model-profiles.config.json

Fixes:

• If behavior is correct, do nothing (schedule is enforcing policy).
• To temporarily hold a manual switch, disable schedule in config/model-schedule.config.json and re-run:
  • bash ./scripts/install_copilot_guardrails.sh
• 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:
  • bash ./scripts/finalize_copilot_setup.sh This populates config/model-profiles.config.json and restages launchd runtime configs.

12) Copilot auth watchdog alerting repeatedly

Checks:

copilot auth status
openclaw models status --check
cat config/copilot-auth-watchdog.config.json
cat ~/Library/Application\ Support/openclaw-copilot-guard/copilot-auth-watchdog.config.json

Fixes:

• Re-authenticate with copilot auth login.
• Increase minAlertIntervalMinutes in config/copilot-auth-watchdog.config.json.
• If needed, temporarily disable watchdog by setting enabled to false.

13) Recommended hooks not active

Enable and verify:

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