add-onecli git:20261022.0474572A

Immutable. This exact content never changes and is served at /api/v1/blob/5d52cf27449540b7.

---
name: add-onecli
description: Install or refresh OneCLI as NanoClaw's gateway provider. Use when setup selects OneCLI, an existing OneCLI-backed install is migrated to the gateway seam, or its runtime, approval bridge, setup, and agent guidance must be restored from the in-tree package.
---

# Add OneCLI gateway

This skill owns the full OneCLI integration. NanoClaw core supplies the generic gateway seam and existing skill engine.

## Install the provider payload

Copy the package's native adapter, tests, and agent guidance into their normal NanoClaw paths. NanoClaw core owns the approval workflow.

```nc:copy
payload/src/gateway-providers/onecli-files.ts -> src/gateway-providers/onecli-files.ts
payload/src/gateway-providers/onecli-files.test.ts -> src/gateway-providers/onecli-files.test.ts
payload/src/gateway-providers/onecli-chatgpt-stub.ts -> src/gateway-providers/onecli-chatgpt-stub.ts
payload/src/gateway-providers/onecli-chatgpt-stub.test.ts -> src/gateway-providers/onecli-chatgpt-stub.test.ts
payload/src/gateway-providers/onecli.ts -> src/gateway-providers/onecli.ts
payload/src/gateway-providers/onecli-provider-credentials.ts -> src/gateway-providers/onecli-provider-credentials.ts
payload/src/gateway-providers/onecli-provider-credentials.test.ts -> src/gateway-providers/onecli-provider-credentials.test.ts
payload/src/gateway-providers/onecli.test.ts -> src/gateway-providers/onecli.test.ts
payload/src/gateway-providers/onecli-install.test.ts -> src/gateway-providers/onecli-install.test.ts
payload/container/skills/onecli-gateway/SKILL.md -> container/skills/onecli-gateway/SKILL.md
payload/container/skills/onecli-gateway/instructions.md -> container/skills/onecli-gateway/instructions.md
payload/docs/onecli-upgrades.md -> docs/onecli-upgrades.md
```

## Register once

The provider file makes the only product registration call. It translates OneCLI sessions and native approval events into the generic contract.

```nc:append to:src/gateway-providers/installed.ts
import './onecli.js';
```

## Install the pinned SDK

```nc:dep manager:pnpm
@onecli-sh/sdk@2.2.1
```

## Configure the gateway

The setup script safely reuses a healthy existing installation, installs the pinned local gateway when absent, or uses `NANOCLAW_ONECLI_API_HOST` and `NANOCLAW_ONECLI_API_TOKEN` for a remote gateway.

This integration supports exactly the gateway version pinned in `.claude/skills/add-onecli/versions.json` (`onecli-gateway`, today 1.45.0; not the `versions.json` at the project root). It uses the agent grants API, which OneCLI added in 1.44; older gateways do not have it, and OneCLI 2.x is not supported. Setup reuses an existing gateway without checking its version: follow [Upgrading the OneCLI gateway](payload/docs/onecli-upgrades.md) to check it and to move it to the pin. The CLI (`onecli-cli`, which needs 2.9 or later for `onecli agents grants`) and SDK (`onecli-sdk`) have their own pins.

```nc:run effect:external
pnpm exec tsx .claude/skills/add-onecli/scripts/setup.ts
```

## Provider credentials

Provider skills such as `/add-opencode` store model credentials here through the
gateway seam. An agent group's OneCLI agent holds only the secrets attached to it.
NanoClaw records the id of each model credential its provider setup saves (setup's
Claude key, `/add-codex`, `/add-opencode`, `/add-cursor`) in `data/onecli/provider-credentials.json`,
by provider. On every spawn it attaches the recorded credentials for the provider
the group runs, if the agent does not hold them yet; this also covers a new group,
a group that switched provider, and a login saved after the group existed. For
an install that saved credentials before ids were recorded, the first spawn per
provider also adopts, once, the secrets NanoClaw's setup saves, by name
(`Anthropic`, `Codex`, `OpenCode …`, `Cursor`). After that only recorded ids count: a
re-run of the provider's login records a credential it finds or saves.

Every other secret and every app connection is opt-in: the skill that adds it
attaches it to the groups you choose, and new groups do not get it. To grant one
by hand: `onecli agents grants attach-secret --id <agent-id> --secret-id <secret-id>`
(`onecli agents list --max 0` maps the group id, shown as `identifier`, to
`<agent-id>`). Attaching adds one secret and leaves the agent's other grants alone;
`detach-secret` takes it away. Verify with `onecli agents grants list --id <agent-id>`;
the gateway can take up to a minute to apply a change. Do not put a key in `.env`,
command arguments, or the container environment.

- Only a selected OneCLI adapter uses `ONECLI_URL` and `ONECLI_API_KEY`.
- Moving an API key to another exact host keeps its stored value, so a blank
  answer at the key prompt completes the move after confirmation.
- Existing OneCLI credential names and formats remain compatible.
- Unattended ChatGPT token refresh is not yet verified on the pinned gateway;
  see [ChatGPT OAuth refresh](references/chatgpt-oauth-refresh.md) for the
  manual reauthentication path.

## Validate

```nc:run effect:build
pnpm run build
```

```nc:run effect:test
pnpm exec vitest run src/gateway-providers/onecli-files.test.ts src/gateway-providers/onecli-chatgpt-stub.test.ts src/gateway-providers/onecli-install.test.ts src/gateway-providers/onecli-provider-credentials.test.ts src/gateway-providers/onecli.test.ts src/gateway-providers/gateway-provider-registry.test.ts src/gateway-approval-coordinator.test.ts
```

The setup consumer writes `NANOCLAW_GATEWAY_PROVIDER=onecli` only after every directive above succeeds. Claude authentication is then completed through `scripts/auth.ts`; credentials never enter an agent container.

During an atomic NanoClaw upgrade, `scripts/detect.ts` identifies an older implicit OneCLI installation so the generic updater can preserve that choice before the service restarts.