Skip to main content
Your assistant never receives real credentials. NanoClaw stores them in a credential gateway on the host, and the gateway adds them to each outbound request at the network boundary. An agent container only ever holds placeholders for the credentials the gateway manages, so a prompt injection or a misbehaving tool cannot read those keys from the container. Files you mount into the sandbox yourself are a separate matter; see Hardening. Since NanoClaw 2.4.0 the gateway is an installable choice rather than a built-in. This page covers which gateways exist, how setup picks one, and what to do when you update a fork by hand. For how OneCLI itself stores secrets, stubs credentials, and asks for approval, see Credentials.

​
Which gateway you get

Standard setup installs OneCLI without asking. Advanced setup shows a gateway picker built from the installed gateway skills, with OneCLI listed first as the default (setup/auto.ts:183). Setup then installs the chosen gateway and prints a one-line reminder that credentials are only added at the network boundary (setup/auto.ts:328). You can also preselect a gateway before running setup:
The accepted kinds are onecli and iron-proxy. The host reads NANOCLAW_GATEWAY_PROVIDER from the process environment first, then from .env. A kind that no installed gateway registers is an error at startup, not a fallback to open network access.
Setting the variable alone does not install anything. Setup installs the gateway skill and then records the selection in .env; if you set it by hand, run the matching /add-onecli or /add-iron-proxy skill too.

​
Existing installs keep their gateway

Updating does not change your gateway. Setup and /update-nanoclaw first look at the recorded NANOCLAW_GATEWAY_PROVIDER, then at which gateway is already installed, and only fall back to the default for a fresh install. An install that predates 2.4.0 and used the built-in OneCLI integration is detected and gets /add-onecli applied before cutover. To reinstall or repair the gateway you already use, run its skill from the NanoClaw checkout:
  • /add-onecli installs or refreshes OneCLI as the gateway, including its approval bridge and the agent guidance it adds to every container.
  • /add-iron-proxy installs or refreshes Iron Proxy and Iron Control, and can set up Codex to run through it.
Do not switch gateways to get through an update. Changing gateways means re-registering your provider credentials in the new one.

​
Updating a hand-merged fork to 2.4.0

Breaking in 2.4.0. The host refuses to start without a registered gateway. If you merge upstream into a fork by hand, install your gateway before you restart. The supported /update-nanoclaw path does this for you.
  1. Record the pre-merge revision and back up .env and data/ before you touch the live checkout.
  2. Stop this copy’s host and its agent containers, then merge.
  3. Run /add-onecli for an existing OneCLI install, or the skill for the gateway you had selected. Keep its existing connection settings and credentials.
  4. Confirm .env records the matching NANOCLAW_GATEWAY_PROVIDER.
  5. Build, restart, and check the host log for successful gateway initialization. A startup error such as No gateway provider is registered in this build means the gateway payload is missing. A hand merge also trips the startup upgrade tripwire, which runs before gateway selection; Upgrading explains how to clear it.
  6. Send a message through an existing agent and confirm a credentialed request and an approval-gated action still work.
Forks with their own gateway wiring must implement the current contract. The upstream gateway seam document has the full detect, verify, and rollback procedure, and Updating to NanoClaw 2.4 covers the other 2.4.0 changes. See also Upgrading.

​
For skill authors: how a gateway skill is built

A gateway is a skill directory .claude/skills/<name>/ that contains a gateway.json manifest:
setup/gateways/catalog.ts discovers gateways by that file and requires exactly one default. Unlike channel and provider skills, a gateway skill keeps its implementation on main under the skill’s own payload/ directory: an install with no gateway cannot start, so the payload has to be in the checkout setup runs from. When the skill is applied, the payload lands in ordinary paths:
  • src/gateway-providers/<kind>.ts — the host-side provider implementation
  • container/skills/<kind>-gateway/ — the agent-facing skill mounted into containers
  • one appended line in src/gateway-providers/installed.ts — the registration import
Beyond those, a skill can add files of its own (OneCLI also copies its upgrade runbook into docs/) and declare package dependencies that the skill engine installs with pnpm add. At startup the host resolves exactly one provider from NANOCLAW_GATEWAY_PROVIDER, and only the selected gateway’s agent skills are composed into a container’s instructions, so an agent is not told about a gateway it is not behind. The whole container/skills/ directory is still mounted read-only at /app/skills. The contract itself, including session lifecycle, human approval, and the gateway-trust mount class, is in the upstream gateway seam document. For skill mechanics, see Writing skills.
Last modified on September 24, 2026