Skip to main content

ZeroClaw Configuration and Security

1. The core config mental model​

The provider docs describe one canonical pattern:

[providers.models.<type>.<alias>]

That tells you two things immediately:

  • providers are grouped by family type,
  • each concrete instance gets an operator-chosen alias.

ZeroClaw then wires everything together by reference. An agent points at a provider by dotted alias, and separately references a risk profile.

That is why the docs say the smallest working setup has four section headers: one provider entry, an agent that references it, and a risk profile the agent uses.

2. What config is trying to optimize for​

The config model is trying to balance three needs:

  • strong structure so the runtime can validate aggressively,
  • operator flexibility so you can name and swap instances cleanly,
  • safe secret handling so credentials are not forced into plain TOML.

This is a more serious configuration story than "drop one API key into an env var." That is good for real systems, but it also means you should spend time understanding aliases and references early.

3. Provider configuration​

The official docs highlight a few key ideas.

Alias-based provider entries​

You do not configure "OpenAI globally." You configure one or more concrete entries such as:

[providers.models.openai.coding]
model = "gpt-5-codex"
wire_api = "responses"
requires_openai_auth = true

That makes it easy to keep multiple provider instances side by side:

  • local Ollama,
  • production Anthropic,
  • a backup OpenAI-compatible endpoint,
  • different regions or auth modes.

Fallbacks​

ZeroClaw supports two independent fallback concepts:

  • fallback models on the same provider
  • fallback provider aliases

That is an operationally strong design. It lets the runtime degrade gracefully when a model or provider path fails.

Environment and container overrides​

The provider docs also describe schema-mirrored environment overrides, which are especially useful in containers or deployment environments where you do not want to mutate on-disk config.

4. Credentials and secrets​

The docs call out four main ways to supply credentials:

  1. inline api_key in config,
  2. 1Password references via op://...,
  3. ZeroClaw's local encrypted secrets store,
  4. environment overrides at process start.

The recommended operational stance is clear:

  • use the secrets store or secret references for normal use,
  • avoid checked-in inline keys,
  • use env overrides for deployment/runtime substitution.

5. Channels are configured separately​

Channels use their own alias-based config tree:

[channels.<type>.<alias>]

This separation is important. Providers define how the agent thinks; channels define where it can be reached.

The channel docs also point to recurring fields such as:

  • enabled
  • mention_only
  • proxy_url
  • excluded_tools
  • draft_update_interval_ms
  • approval_timeout_secs

So even before you learn one specific channel integration, you can already see the common operator shape.

6. Security posture​

The official security overview starts from a simple premise:

an agent that can execute commands, open URLs, and write files is a privileged process

Everything else follows from that.

The docs point to four key concepts:

  • security model
  • autonomy levels
  • sandboxing
  • tool receipts

Autonomy​

The README describes the default posture as supervised:

  • medium-risk operations require approval,
  • high-risk operations are blocked,
  • more permissive modes exist for trusted environments.

Sandboxing​

The docs call out OS-level sandboxes such as:

  • Landlock
  • Bubblewrap
  • Seatbelt
  • Docker

That matters because ZeroClaw's safety model is not purely prompt-based. It is backed by system-level controls.

Tool receipts​

Receipts are one of the more distinctive ideas in the project. The README describes them as cryptographic receipts for tool actions. That gives you a stronger audit story than ordinary "the agent probably did this" logging.

7. Day-two operations​

Once the agent works, the operator workflow typically shifts to:

zeroclaw service install
zeroclaw service start
zeroclaw daemon
zeroclaw auth status
zeroclaw config schema

The exact generated reference matters for subcommands and flags, but conceptually these cover:

  • install service mode,
  • start long-lived execution,
  • inspect auth state,
  • inspect config schema.

8. Practical advice​

For real use, the safest habit is:

  1. keep config structure explicit and alias-based,
  2. keep secrets out of plaintext,
  3. start in supervised mode,
  4. add channels one at a time,
  5. treat provider fallback as a reliability feature, not as an afterthought.

That mindset fits the project much better than trying to run it like a one-file hobby bot.