Paths and troubleshooting

DefenseClaw keeps programs, data and each agent's own configuration in separate places. Change things with defenseclaw commands rather than by editing or deleting files. Problems on every OS are in Troubleshooting.

Filesystem reference

Programs

Do not replace or wrap these. Run the install command again to repair them. The installer adds %USERPROFILE%\.local\bin to your user PATH.

On a managed Windows computer none of these per-user paths are used: the programs are in C:\Program Files\Cisco\DefenseClaw\bin, the administrator's config is C:\ProgramData\Cisco\DefenseClaw\etc\config.yaml, the audit database is C:\ProgramData\Cisco\DefenseClaw\runtime\audit.db, and the logs are in C:\ProgramData\Cisco\DefenseClaw\logs and %WINDIR%\Logs\DefenseClaw. The full list is in Windows installation reference.

Data

In ~/.defenseclaw, %USERPROFILE%\.defenseclaw on Windows, or DEFENSECLAW_HOME when set.

Full tree and key reference: Configuration.

Agent files DefenseClaw changes

Setup adds DefenseClaw's own marked entries to each agent's configuration and leaves your other settings alone. Change them only with defenseclaw setup <connector> and defenseclaw setup remove <connector>. Windows defaults:

The Amp and OpenCode plugin files carry a connector credential: never print or copy them. macOS and Linux paths are on each connector page.

Setup changes the Claude Code settings.json only as a regular file. If it is a symbolic link or junction, setup refuses, names the link and its target, and changes nothing. Replace the link with the file it points to, then run defenseclaw setup claude-code --yes again.

Supported path overrides

Claude Code, Codex, GitHub Copilot CLI, Hermes and OpenCode let you move their configuration folder with CLAUDE_CONFIG_DIR, CODEX_HOME, COPILOT_HOME, HERMES_HOME and OPENCODE_CONFIG_DIR. Set them to absolute native paths before you install DefenseClaw or set up the connector. Setup checks and remembers them and refuses a path through a symbolic link or junction, before it changes anything. For Codex the refusal names the folder and the fix: set CODEX_HOME to the real folder, or unset it to use %USERPROFILE%\.codex, then run defenseclaw setup codex. The same holds for the other four variables. For Codex, defenseclaw setup codex --no-restart keeps the folder the running gateway already uses and says so when CODEX_HOME names another one; run it again without --no-restart to move. Amp, Antigravity, Cursor and Devin have no such variable.

$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 a variable later does not move DefenseClaw's entries. To move an agent's folder, run its setup again. The default data root is the current profile's .defenseclaw; DEFENSECLAW_HOME overrides it. install.ps1 turns a quoted ~\... or a relative DEFENSECLAW_HOME or DEFENSECLAW_CONFIG into an absolute path first (a relative one is taken from the folder you run it in), so use an absolute path for later commands. Use the same value for every command, including defenseclaw upgrade. DEFENSECLAW_FAIL_MODE is not a path setting and no 1.0.4 hook reads it. Set the fail mode with defenseclaw guardrail fail-mode open|closed; setup writes it into the hooks and the OpenCode plugin, and defenseclaw status and defenseclaw doctor report it.

DefenseClaw restricts its private files to the current user, Administrators and SYSTEM on Windows (security model).

Quoting and case

Quote every path that can contain spaces. In PowerShell use the call operator:

& "$env:USERPROFILE\.local\bin\defenseclaw-gateway.exe" status

In cmd, quote the executable: "%USERPROFILE%\.local\bin\defenseclaw-gateway.exe" status. The hook command setup writes into Hermes config.yaml is a quoted absolute path to defenseclaw-hook.exe with forward slashes and plain arguments. Hermes runs it without a shell, so add no &, .ps1 or wrapper. Windows compares variable names and paths without regard to case: do not use two agent folders or variables that differ only by case.

First diagnostics

Run these before changing state:

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

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

version shows whether the CLI and the gateway are the same release. status lists the configured connectors and whether the gateway runs them. For repairable findings, preview first with defenseclaw doctor --fix --dry-run; a token fix can restart the gateway.

Troubleshooting

Post-install and post-upgrade checklist

Use harmless prompts only: no real secrets or customer data.

• defenseclaw version: the CLI and the gateway report the same release.
• defenseclaw migrate --check and defenseclaw config validate pass (after an upgrade).
• defenseclaw-gateway status and defenseclaw doctor pass.
• defenseclaw guardrail status lists each agent you set up with the mode, fail mode and enabled state you chose (the same as before an upgrade). Hermes follows the same gateway outage rule as the other agents (gateway outage table). A running DefenseClaw hook blocks every other failure; for a timed-out or killed hook see Hermes fail mode. On a managed host, the administrator may choose open for a gateway outage; unusable answers still block. Under Secure Client, open is the default.
• Restart each agent where its connector page says to, send a harmless prompt in each one, and look for the event in defenseclaw tui or defenseclaw-gateway audit export --output -. A harmless prompt creates an audit event, not an alert.
• Leave the previous and backups folders alone until the gateway and every agent work.

See also the CLI reference, Upgrade and Windows.