NanoClaw: Advanced

This page is the seventh of eight, and it covers five NanoClaw features for when the basics feel routine. Each one widens what the agent can reach, so read its trade-off before you turn it on, and come back to Fixes if something goes wrong.

These steps match the docs as of 14 November 2026, when the newest release was v2026.10.0. Commands that start with /, such as /add-tavily-tool, run inside Claude Code in the nanoclaw folder. This guide could not confirm whether the installer puts Claude Code on your computer.

Choose the model for each agent

What it is for. Each agent can use its own model and its own level of effort, so a quick lookup job can run on a cheaper model while serious work runs on a stronger one. The release notes for v2.4.0 say that Claude agents with no model set moved to Opus 5.5, which changes what each reply costs.

How to turn it on. Find your agent's id, set a model and effort, then restart it. The docs accept the short names sonnet, opus, and haiku. Effort is one of low, medium, high, xhigh, or max.

ncl groups list
ncl groups config update --id <agent-id> --model sonnet --effort low
ncl groups restart --id <agent-id>

To set a default for every agent that has no model of its own, add a NANOCLAW_DEFAULT_MODEL line with the model you want to .env and restart NanoClaw. This guide could not confirm that the short names work in that setting as they do in --model. The setting NANOCLAW_FAST_MODE=true turns on a faster serving tier, which the docs say costs more.

• You gain: control over cost, because a smaller model on simple jobs stretches your spend limit much further.
• You risk: a weaker model makes more mistakes on long jobs. NanoClaw also does not check the model name you type, so a typo only shows up as an error the next time the agent starts.
• Makes sense when: you have watched a few jobs finish on the default model and know which ones are simple. Check the setting with ncl groups config get --id <agent-id> after every change.

Share one real folder, read-only

What it is for. The agent normally sees only its own workspace. Sharing a folder lets it read your real files, for example to sort a folder of notes or summarize documents, without copying them in first.

How to turn it on. There are two parts, and both are needed. First, the folder list in ~/.config/nanoclaw/mount-allowlist.json must name the folder. The hardening page gives a setup command that writes that file, so make a new folder for the job, then list only that folder, read-only.

mkdir -p ~/agent-share
cd ~/nanoclaw
pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[{"path":"~/agent-share","allowReadWrite":false}],"blockedPatterns":[]}'

This guide could not confirm whether --force keeps any folders you listed before, so treat it as writing the whole list fresh. NanoClaw rereads the list when the file changes, with no restart needed.

Second, attach the folder to one agent with the read-only flag, then restart that agent.

ncl groups config add-mount --id <agent-id> --host ~/agent-share --container agent-share --ro
ncl groups restart --id <agent-id>

Inside the container, the folder appears as /workspace/extra/agent-share. You can also manage the list by running /manage-mounts in Claude Code. To take it away, run ncl groups config remove-mount --id <agent-id> --host ~/agent-share --container agent-share, then restart the agent.

• You gain: the agent can read real files in place, and with --ro and allowReadWrite set to false, it cannot change or delete them.
• You risk: anything in the folder can be read by a mistake or a prompt injection. With egress lockdown off or a chat app connected, it could be sent elsewhere, and read-write sharing would put the originals within reach of a deleting command.
• Makes sense when: the folder holds copies made for one job, egress lockdown is on, and you keep it read-only. It never makes sense for your home folder, Documents, or Desktop.

Add tools with MCP servers

What it is for. An MCP server is a small add-on program that gives the agent a new tool, such as a search service or access to another app. NanoClaw offers ready-made tool add-ons, and it lets you add any MCP server yourself. For how skills and MCP compare across agents, and how to choose safe ones, see Skills and MCP.

How to turn it on. The simplest ready-made one is web search through Tavily, which needs no key at first. Run this in Claude Code:

/add-tavily-tool

To add an MCP server yourself, register it for one agent with ncl, then restart the agent. The docs' example adds GitHub's server:

ncl groups config add-mcp-server \
  --id <group-id> \
  --name github \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-github"]' \
  --env '{}'

The agent can also ask for a new MCP server itself, and that request always waits for an admin to tap Approve on a card. Review everything an agent has, then remove what you do not want.

ncl groups config get --id <group-id>
ncl groups config remove-mcp-server --id <group-id> --name github
ncl groups restart --id <group-id>

If a server needs a key, the docs say to save it in the OneCLI vault rather than in --env, so the container never holds it.

• You gain: the agent can do new kinds of work, such as search on a model without built-in search, or reading from a service you use.
• You risk: every tool is one more door, and a server that reaches your accounts lets a tricked agent act in them. A server you install runs its own code inside the container.
• Makes sense when: the server comes from a source you trust, it needs no account of yours, or it reaches only a test account made for the agent. An agent's own request to add a server is exactly what a prompt injection would ask for, so reject any you did not expect.

Run several agents at once

What it is for. Each agent has its own container, workspace, and memory, so you can keep work separate, such as one agent for household lists and one for research. Agents can also pass work to each other, as in job 6 of the playbook.

How to turn it on. Ask your main agent to create one, in plain words such as "Create an agent called researcher," and give it a role and a stop condition. To make every message between two agents wait for your approval, set a gate from your own terminal. It uses the ids from ncl groups list and your user id.

ncl policies set --from <source-agent-id> --to <target-agent-id> --approver <user-id>

The command ncl roles list --role owner shows the owner's user id. Approval cards go to a direct-message chat, so the gate needs a paired chat app. This guide could not confirm that a terminal-only install has an owner at all. Remove the gate with ncl policies remove --from <source-agent-id> --to <target-agent-id>, and remove an agent with ncl groups delete --id <agent-id>.

• You gain: separate memory for separate jobs, and the option to split one big job across agents.
• You risk: the docs say there is no limit on how long two agents keep messaging each other, or on how many containers run at once. A loop can burn through your model budget and your computer's memory. The first agent setup makes is trusted, so it creates new agents without asking you.
• Makes sense when: each agent has a clear stop condition in its instructions, your spend limit is set, and you watch the first runs. Do not give other agents the same trusted level with --cli-scope global.

Call a local model as a tool

What it is for. A local model runs on your own computer, so the text you send it stays there and costs nothing per use. NanoClaw's supported way to use one keeps your main model in charge and lets it hand smaller jobs to the local one.

How to turn it on. Install Ollama on your computer, then run this in Claude Code:

/add-ollama-tool

The agent then gets the tools ollama_list_models and ollama_generate, which reach the Ollama on your computer. Setting OLLAMA_ADMIN_TOOLS=true would also let the agent download and delete models, so leave it unset.

To replace the main model with a local one instead, the providers page points to OpenCode connected to a local server in the OpenAI format. You set it up with pnpm exec tsx setup/index.ts --step provider-auth opencode. The older /add-ollama-provider add-on is not a supported drop-in on current code, so do not use it.

If a slow local model gets stopped in the middle of a job, the troubleshooting page offers NANOCLAW_ABSOLUTE_CEILING_MS and NANOCLAW_CLAIM_STUCK_MS in .env. The docs say both were added after v2026.10.0, so the release a normal update installs may not read them yet.

• You gain: private material can go to a model that never leaves your computer, and those calls cost nothing.
• You risk: with the tool route, your main model is still a cloud model that sees the conversation. Only the text sent to the local model stays private. A small local model is also weaker and may get things wrong.
• Makes sense when: your computer has plenty of RAM for the model you pick, and the job is a simple one such as summarizing or sorting text you would rather not send to a provider.

Shared advanced topics

• Local models: choosing and running a local model, which the Ollama tool and the OpenCode local route both need.
• Mixing models: NanoClaw sets a model per agent, so a cheap model can take simple jobs while a stronger one does the real work.
• Host access and unattended work: shared folders and scheduled tasks are where NanoClaw reaches your real files and runs with nobody watching.
• An always-on machine: NanoClaw only answers chat apps and runs schedules while its computer is on and online.
• Subscription sign-ins: setup offers a Claude Pro or Max sign-in and a ChatGPT sign-in through Codex, which this guide does not teach.
• Relays: ANTHROPIC_BASE_URL in .env points NanoClaw at any Anthropic-compatible endpoint, which is how a relay would be connected.

Sources

Opened 14 November 2026.

NanoClaw:

• Customize an agent, for ncl groups config update, model names, effort levels, and restarting.
• Agent providers, for NANOCLAW_DEFAULT_MODEL, NANOCLAW_FAST_MODE, OpenCode with a local server, and the /add-ollama-provider limitation.
• Releases, for Claude agents with no model set moving to Opus 5.5 in v2.4.0.
• GitHub issue 3855, any model name is accepted.
• Hardening, for the folder list, read-only sharing, the setup command that writes the list, and /manage-mounts.
• ncl CLI reference, for add-mount, remove-mount, --ro, ncl roles list, and ncl policies remove.
• Container configuration, for extra folders under /workspace/extra/.
• Give agents tools, for /add-tavily-tool, add-mcp-server, keys in the vault, and /add-ollama-tool.
• Agent self-modification, for approval cards on new MCP servers and removing them.
• Build a multi-agent team, for create_agent, ncl policies, the trusted first agent, and the missing limits.
• Troubleshooting, for the two timer settings added after v2026.10.0.
• Installation, for ANTHROPIC_BASE_URL.
• README, for Claude Code being needed for / add-ons.

This guide's own notes:

• Safety versus capability.
• Unofficial routes, including Claude plan sign-in.

Next

Continue to Persona and rules.