Add a connector without losing audit history

Use defenseclaw setup <connector> to add or reconfigure agent wiring while preserving audit history for every connector.

The audit DB is connector-agnostic. Current canonical events persist a connector column, so adding or replacing connector wiring does not erase history. New events land under the connector that produced them; migrated legacy or unclassified rows may have an empty connector value.

Inspect current state

defenseclaw status
defenseclaw alerts --limit 25
defenseclaw-gateway audit export --output - \
  | tail -n 200 \
  | jq -r 'select(.connector) | .connector' | sort | uniq -c

status shows enforcement flags plus a per-connector block for every active connector. alerts lists the most recent decisions as a table. The SQLite export histogram gives you a quick by-connector view of recent canonical events.

Add or reconfigure the connector

defenseclaw setup codex

If another connector is already wired, choose Add to keep both active. Choose Replace only when you want DefenseClaw to tear down the previous connector's agent-side files before wiring the new one.

For an unattended run, --yes takes the add/reconfigure path. Use --replace only when replacement is intentional:

defenseclaw setup codex --yes
defenseclaw setup codex --yes --replace

Use --mode action when this connector should block policy hits immediately:

defenseclaw setup codex --mode action

Verify

defenseclaw doctor
defenseclaw alerts --limit 10
defenseclaw-gateway audit export --connector codex --output - | tail -n 100

doctor confirms connector health. alerts and the connector-filtered SQLite export show new events landing under codex.

What stays, what changes

Stays put	Changes
Audit DB (`~/.defenseclaw/audit.db`)	Active connector roster
Rule packs (`~/.defenseclaw/policies/`)	Hook scripts wired in agent config
Sinks (OTLP / Splunk / webhooks)	`guardrail.connectors.<name>` policy blocks
Historical audit attribution	Backed-up agent files for removed or replaced connectors

Use Add for multi-connector hosts. Use Replace only for a deliberate one-connector workstation. To retire a connector later, run defenseclaw setup remove <connector>. Removing the last configured connector requires --force.

When to change connector wiring

Trying a different agent. Add the second connector and compare behavior from defenseclaw status and defenseclaw alerts.
Promoting an agent. Re-run defenseclaw setup <connector> --mode action when a connector should start blocking.
Demoting an agent. Re-run defenseclaw setup <connector> --mode observe while you tune policy.
Retiring an agent. Run defenseclaw setup remove <connector> after you stop using it; add --force only when removing the last connector is deliberate.

Caveats

The audit DB is portable across connectors but not across DefenseClaw versions in some cases. Use defenseclaw upgrade, which applies release-required migrations before reporting success. Run defenseclaw migrations status afterward to inspect the durable cursor; pending entries retry on the next upgrade, not on unrelated CLI commands.