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 and CLAUDE_CONFIG_DIR are the supported connector configuration overrides. Set them to absolute, normalized native Windows paths before initial Setup or connector setup. The installer validates and records them; reparse ancestors are refused. Amp has no connector-home override: its certified 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"

set "CODEX_HOME=D:\Agent Profiles\Codex"
set "CLAUDE_CONFIG_DIR=D:\Agent Profiles\Claude"

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 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.

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

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 the intended Codex, Claude Code, and/or Amp rows, mode, fail mode, and enabled state.
• 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 connector's hook, plugin, or OTLP settings.

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.
• Restart Codex and Claude Code, fully exit and relaunch Amp, then repeat the harmless per-connector event check above.
• 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 are healthy.

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