ZeroClaw config.toml: Tested v0.8.5 Examples and Migration

Version checked — 7 October 2026: The minimal config below was run with the official ZeroClaw v0.8.5 macOS arm64 binary and a real Ollama model. This release uses schema version 3. The old [provider], [security], [channels] and [tools] examples previously shown here are not current copy-and-paste configs. See migration guidance before reusing them.

Start with one model provider, one agent and one risk profile. Add messaging channels only after the CLI produces a reply. Install the same release before following these examples.

Where config.toml lives

The default file is ~/.zeroclaw/config.toml on macOS and Linux, or %USERPROFILE%\.zeroclaw\config.toml on Windows. Run zeroclaw status to see the actual location; --config-dir and environment overrides can change it. The old ~/.config/zeroclaw/ path on this page was incorrect for this release.

To keep a test separate from your normal agent, choose a new config directory:

mkdir -p zeroclaw-test

Save the example as zeroclaw-test/config.toml, then pass --config-dir ./zeroclaw-test on every command in the test. The binary creates its agent data and workspace under its install/config layout. Avoid pointing a new test at an existing config or workspace.

Minimal local config: tested

Install Ollama from its official source. In one terminal start its server if it is not already running, then download the small model from another terminal:

ollama serve

ollama pull qwen2.5:0.5b
ollama list

The model name must appear in the list. This small model is for a smoke test; it is not a recommendation for demanding agent work.

Download the exact minimal v0.8.5 config, or paste this entire file:

schema_version = 3

[providers.models.ollama.local]
model = "qwen2.5:0.5b"
uri = "http://127.0.0.1:11434"
temperature = 0.0
num_ctx = 4096
num_predict = 128
native_tools = false

[agents.assistant]
model_provider = "ollama.local"
risk_profile = "reader"

[agents.assistant.workspace]
unrestricted_filesystem = false

[risk_profiles.reader]
level = "readonly"
workspace_only = true
allowed_tools = ["time"]

local, assistant and reader are aliases you choose. The agent references ollama.local, not just ollama; its risk_profile must match [risk_profiles.reader]. The workspace block keeps unrestricted filesystem access off and lets ZeroClaw derive the agent's workspace path. readonly is spelled without an underscore.

With no MCP servers configured, this smoke test exposes only the time tool. An empty allowed_tools array does not mean deny all: it leaves the registry unrestricted at that layer. In v0.8.5, runtime-discovered MCP tools whose names contain __ are automatically admitted at the risk-profile allowlist layer, even when this list is nonempty. Review that policy when adding MCP servers. native_tools = false uses the non-native tool path for this small model; the test prompt does not request any tool use.

Validate and run it

zeroclaw --version
zeroclaw --config-dir ./zeroclaw-test config migrate --json
zeroclaw --config-dir ./zeroclaw-test status
zeroclaw --config-dir ./zeroclaw-test agent -a assistant -m "Reply with the single word Ready. Do not use tools."

Expected version:

zeroclaw 0.8.5

For the already-current sample file, observed parser/migration output:

{
  "error": null,
  "migrated": false,
  "schema_version": 3,
  "valid": true
}

Observed model reply:

Ready.

The test ran on macOS arm64 with Ollama 0.35.0 and qwen2.5:0.5b. We used a fresh temporary config directory and the same downloadable file, with ZEROCLAW_providers__models__ollama__local__uri=http://127.0.0.1:11435 to reach an isolated test server. A normal Ollama server uses the sample's port 11434. The reply can vary, but a successful run must exit without a provider/config error and return model text. This test covers a real model turn, not Telegram, every tool, or Windows execution.

What each current section controls

Read the schema from your installed binary, rather than copying a key from a different release:

zeroclaw --config-dir ./zeroclaw-test config schema > zeroclaw-v0.8.5-schema.json
zeroclaw --config-dir ./zeroclaw-test config get agents.assistant.model_provider

The expected provider reference for the minimal file is ollama.local. config migrate --json is a strict parser/migration check, not a guarantee that every unknown field will be rejected or that a provider works. The agent run supplies the runtime check.

Change the model or endpoint

Keep the provider alias and change model to a model you have actually downloaded. Ollama's native endpoint is the server root, for example http://127.0.0.1:11434, rather than the old /v1 URL shown here.

Provider settings use uri, not base_url. For a container reaching Ollama on the host, use a host-reachable address such as http://host.docker.internal:11434 on Docker Desktop; Linux container networking needs its own host mapping. Check the tagged provider guide before changing network layout.

Hosted-model example: credential required

The following is a complete alternative config. It was checked through the v0.8.5 parser, but no hosted API request was made. Save it in a separate directory instead of appending a second [agents.assistant] block to the local example.

schema_version = 3

[providers.models.openrouter.hosted]
model = "anthropic/claude-sonnet-4"
temperature = 0.2

[agents.assistant]
model_provider = "openrouter.hosted"
risk_profile = "reader"

[agents.assistant.workspace]
unrestricted_filesystem = false

[risk_profiles.reader]
level = "readonly"
workspace_only = true
allowed_tools = ["time"]

Check the model's current availability with your provider. Add your own key through the masked secret prompt, using that config directory:

zeroclaw --config-dir ./zeroclaw-hosted config set providers.models.openrouter.hosted.api_key
zeroclaw --config-dir ./zeroclaw-hosted agent -a assistant -m "Hello"

Quickstart is an alternative way to configure a hosted provider. v0.8.5 also supports schema-based environment overrides such as ZEROCLAW_providers__models__openrouter__hosted__api_key; the old api_key_env field is not the current provider-entry format. Do not put real keys into a downloadable example or screenshot.

Add memory and channels separately

Memory backend selection belongs to the agent, for example [agents.assistant.memory] with backend = "sqlite". The backend is fixed once that agent has on-disk data; do not treat changing its name as a migration of existing memories. Global [memory] settings still exist for shared tuning, but the old path, auto_recall and max_results block on this page was not a tested v0.8.5 example.

Telegram uses an instance such as [channels.telegram.home], a bot_token secret, an agent binding such as channels = ["telegram.home"], and peer groups for authorization. There is no current allowed_users field on that channel entry. Configure it using the official v0.8.5 Telegram guide. The older Telegram walkthroughs on this site remain marked unverified; copying their onboarding screenshots is not a migration procedure.

The web gateway is configured under [gateway], not the old [channels.web] block. Pairing and channel-peer authorization are different controls. Verify each independently before exposing a gateway or bot.

Migrate old sections

Stop your daemon before replacing its config. Back up the original file, then work on a copy in a separate directory. For an actual older ZeroClaw config, the supported migration command is:

zeroclaw --config-dir ./zeroclaw-migration config migrate --json
zeroclaw --config-dir ./zeroclaw-migration config migrate --json
zeroclaw --config-dir ./zeroclaw-migration status

Place the copied old config.toml in zeroclaw-migration first. The first run migrates supported older schemas on disk and reports a backup path. The second run checks the now-current file and should report schema_version: 3, valid: true, and error: null. Inspect the resulting aliases and run a real message before adopting the file. Do not set schema_version = 3 on an old file just to silence migration.

The previous examples on this page were illustrative sections, not a known valid older ZeroClaw config. An automatic migration is not guaranteed to preserve their intent. Rebuild them from the current minimal example using this mapping:

Some global [security] and [memory] fields still exist. That does not make the old keys above valid in those locations. Compare every moved setting with config schema, especially permissions, secrets and channel access. Restore your backup if the migrated agent does not behave as expected.

Troubleshooting

• No agent alias: add -a assistant; match the name under [agents.assistant].
• Provider or risk profile does not resolve: match the dotted provider reference and risk-profile alias exactly.
• Connection refused: start Ollama and check the provider uri and server port.
• Model not found: run ollama list and pull the exact configured tag.
• Unexpected defaults: inspect status, run config migrate --json, and compare the file with the binary's schema. Diagnostics alone do not prove an obsolete field was applied.

Sources and next steps

• Official v0.8.5 provider configuration
• Official v0.8.5 autonomy and risk profiles
• Install the matching release
• Fix common install/config errors