Paths and troubleshooting

The packaged Windows lifecycle separates product files, user data, installer maintenance state, and each agent's own configuration. Keep those boundaries intact when diagnosing a problem.

Filesystem reference

The installer records the exact connector homes and uses them for later repair, upgrade, and cleanup. Connector configuration backups are ownership records, not a user-facing rollback directory.

Supported path overrides

CODEX_HOME, CLAUDE_CONFIG_DIR, COPILOT_HOME, OPENCODE_CONFIG_DIR, OMNIGENT_CONFIG_HOME, and HERMES_HOME are the connector configuration overrides honored by their respective implementations. Set them to absolute, normalized native Windows paths before initial Setup or connector setup. The installer validates and records them; reparse ancestors are refused. Antigravity, Cursor, and Devin publish no equivalent public configuration-home override. The retired Gemini CLI cleanup path can still read its previously authenticated GEMINI_CLI_HOME custody record; it is not a supported new setup override. Antigravity's distinct global hook path is fixed at %USERPROFILE%\.gemini\config\hooks.json; Setup keeps any predecessor custom path only as internal custody needed for exact migration and restoration. Legacy cleanup records Gemini's vendor root and derived .gemini directory independently from Antigravity's nested home so one connector cannot restore or delete the other's document. Cursor and Devin likewise record their exact native paths internally. Amp has no connector-home override: its supported system plugin path is fixed beneath the current %USERPROFILE% at .config\amp\plugins\defenseclaw.ts.

$env:CODEX_HOME = "D:\Agent Profiles\Codex"
$env:CLAUDE_CONFIG_DIR = "D:\Agent Profiles\Claude"
$env:COPILOT_HOME = "D:\Agent Profiles\Copilot"
$env:OPENCODE_CONFIG_DIR = "D:\Agent Profiles\OpenCode"
$env:OMNIGENT_CONFIG_HOME = "D:\Agent Profiles\OmniGent"
$env:HERMES_HOME = "D:\Agent Profiles\Hermes"

set "CODEX_HOME=D:\Agent Profiles\Codex"
set "CLAUDE_CONFIG_DIR=D:\Agent Profiles\Claude"
set "COPILOT_HOME=D:\Agent Profiles\Copilot"
set "OPENCODE_CONFIG_DIR=D:\Agent Profiles\OpenCode"
set "OMNIGENT_CONFIG_HOME=D:\Agent Profiles\OmniGent"
set "HERMES_HOME=D:\Agent Profiles\Hermes"

Changing an environment value after installation does not authorize lifecycle commands to abandon the recorded home. Re-run supported connector setup or repair deliberately; do not move the directory and edit installer state.

The Devin connector has no public configuration-home or executable override in packaged Windows Setup. Setup resolves %APPDATA%\devin and the fixed %LOCALAPPDATA%\devin\cli\bin\devin.exe path from the signed-in user's Known Folders, validates both, and persists them. Repair, upgrade, reconciliation, and uninstall use only that custody; they do not follow ambient profile drift or scan another user's configuration.

The generic runtime recognizes DEFENSECLAW_HOME, but the native packaged Setup, launchers, logon helper, repair, and upgrade lifecycle deliberately pin the data root to the current profile's .defenseclaw. Relocating a packaged installation with DEFENSECLAW_HOME, DEFENSECLAW_CONFIG, or an executable override is not supported.

DEFENSECLAW_FAIL_MODE and DEFENSECLAW_STRICT_AVAILABILITY are runtime behavior overrides, not path controls. Prefer the persisted defenseclaw guardrail fail-mode command for normal operation. OpenCode does not consume those ambient process overrides: Setup bakes its persisted fail mode into the managed plugin, and status/Doctor report drift.

Private Windows DACLs restrict connector assets to the current user, Administrators, and SYSTEM. They reduce access by other standard users but are not tamper-proof against the owning user or administrators. Doctor's digest check and Setup reconciliation are the supported drift/recovery controls.

Quoting, long paths, and case

Quote every path that can contain spaces. In PowerShell, use the call operator for an executable path:

& "$env:LOCALAPPDATA\DefenseClaw\InstallerCache\DefenseClawSetup-x64.exe" /verify

In cmd, quote the executable itself:

"%LOCALAPPDATA%\DefenseClaw\InstallerCache\DefenseClawSetup-x64.exe" /verify

Those examples are interactive shell syntax. The command stored in Hermes config.yaml is deliberately different: it is a directly double-quoted absolute defenseclaw-hook.exe path followed by literal argv, with forward slashes in the Windows path. It must not contain PowerShell's &, a .ps1, or any other shell wrapper because Hermes uses shlex.split and subprocess.run(..., shell=False).

DefenseClaw product executables are long-path-aware, and installer journal and process-identity tests cover paths beyond the legacy MAX_PATH limit. That does not certify arbitrary third-party agents, plugins, network filesystems, or shell wrappers. Protected connector and transaction paths reject reparse redirection; remote Windows filesystems are not a supported transaction target.

Windows comparisons are case-insensitive where required for environment keys and owned path identity. Do not rely on two connector homes, files, or environment variables that differ only by letter case.

First diagnostics

Run these before changing state:

Get-Command defenseclaw
Get-Command defenseclaw-gateway
defenseclaw version
defenseclaw-gateway status
defenseclaw status
defenseclaw guardrail status
defenseclaw config validate
defenseclaw doctor

where defenseclaw
where defenseclaw-gateway
defenseclaw version
defenseclaw-gateway status
defenseclaw status
defenseclaw guardrail status
defenseclaw config validate
defenseclaw doctor

version detects a stale launcher/gateway mismatch. status reports the configured connector roster and authenticated runtime state. doctor checks the installed agent contract, native registration, credentials, endpoints, and connectivity without printing credential values.

For repairable findings, preview before mutation:

defenseclaw doctor --fix --dry-run

Only use --fix --yes after reviewing the exact proposed fix. The token-drift fix can restart the gateway. Doctor does not tear down inactive connector residue automatically.

Troubleshooting

Post-install checklist

Complete this without real secrets or destructive tools:

• Open a new native PowerShell or cmd window and confirm defenseclaw and defenseclaw-gateway resolve from the product bin directory.
• Run defenseclaw version; require the CLI and gateway generation to agree.
• Run defenseclaw-gateway status, defenseclaw status, and defenseclaw guardrail status; require every intended supported connector row, mode, enabled state, and truthful failure posture. Hermes failures must be reported open even if generic policy provenance is closed.
• Run defenseclaw config validate and defenseclaw doctor; resolve every connector registration or authentication failure.
• Restart each configured Codex or Claude Code agent; fully exit and relaunch Amp. In an empty disposable directory, submit a non-sensitive prompt such as “Reply with the word ready.” For amp -x, include --plugin-ready-timeout 30. An authenticated Amp live turn additionally requires AMP_API_KEY; do not paste it into the command or diagnostics. Do not use customer data, credentials, or a destructive tool call.
• Open defenseclaw tui or use defenseclaw alerts and confirm new activity is attributed only to the agent you exercised.
• If multiple connectors are installed, repeat the harmless prompt once in each; one connector's success does not prove another's hooks or telemetry. Hermes manual block visibility must use a harmless matched tool request and confirm only a valid synchronous JSON block, never a timeout/nonzero test.

Post-upgrade checklist

• Run defenseclaw version, defenseclaw migrations status, and defenseclaw config validate.
• Require defenseclaw-gateway status and defenseclaw doctor to pass with the exact upgraded generation.
• Compare defenseclaw guardrail status with the pre-upgrade connector roster, modes, fail modes, enabled state, and optional watchdog state.
• Confirm the command path still resolves to the installed product directory, not a stale checkout or copied binary.
• Confirm each configured connector has loaded its configuration, restarting the official client where documented, then repeat the harmless per-connector event check above. For Devin, use the admitted native CLI in the same Windows user session; WSL or a shell substitute is not valid evidence.
• Verify optional destinations with defenseclaw observability plan and the destination-specific test command. A destination failure does not erase the mandatory local audit, but it must be treated as degraded delivery.
• Keep private receipts and backups untouched until the upgraded gateway and every configured connector is healthy.

For broader context, see CLI reference, configuration, upgrade, and TUI.