Managed Providers

Managed providers are cloud-hosted LLM services that netclaw connects to over HTTPS. Each requires an API key or OAuth token — OpenRouter, Anthropic, and OpenAI are supported.

Provider config lives in two files. Non-secret fields (type, endpoint, auth method) go in ~/.netclaw/config/netclaw.json. Credentials go in ~/.netclaw/config/secrets.json, which is encrypted at rest — write plaintext values and netclaw encrypts them on first read. Environment variables override both.

If you’re setting up netclaw for the first time, netclaw init handles provider selection interactively. This page covers manual configuration and the details behind each provider type.

For self-hosted inference (Ollama, llama.cpp, vLLM), see Self-Hosted Providers.

Provider Summary

Type	Display Name	Default Endpoint	Auth	Key Source
openrouter	OpenRouter	https://openrouter.ai/api/v1	API key	openrouter.ai/keys
anthropic	Anthropic	https://api.anthropic.com	API key	console.anthropic.com
openai	OpenAI	https://api.openai.com	OAuth PKCE or API key	platform.openai.com

Configuration Schema

Each provider is a named entry under the Providers section. The key is a name you choose — you can have multiple entries of the same type (e.g., two Anthropic providers with different keys).

Field	Type	Default	Description
Type	string	"ollama"	Provider SDK: openrouter, anthropic, or openai for managed providers. Always set this explicitly.
Endpoint	string	""	Base URL. Leave empty to use the provider’s default
ApiKey	string?	null	API key. Store in secrets.json, never netclaw.json
AuthMethod	enum	None	None, ApiKey, OAuthDevice, or OAuthPkce

Config File Examples

netclaw.json — non-secret fields

{
  "Providers": {
    "openrouter": {
      "Type": "openrouter",
      "Endpoint": "https://openrouter.ai/api/v1"
    },
    "my-anthropic": {
      "Type": "anthropic"
    },
    "my-openai": {
      "Type": "openai",
      "AuthMethod": "OAuthPkce"
    }
  }
}

secrets.json — encrypted credentials

{
  "Providers": {
    "openrouter": { "ApiKey": "sk-or-v1-..." },
    "my-anthropic": { "ApiKey": "sk-ant-..." }
  }
}

OpenAI with OAuth doesn’t need an entry in secrets.json — tokens are managed automatically after the OAuth flow.

You can also manage credentials with netclaw secrets set instead of editing secrets.json directly.

After adding a provider, assign it to a model role — Main, Fallback, or Compaction — with netclaw model set.

OpenRouter

One API key, hundreds of models. OpenRouter proxies requests to Anthropic, OpenAI, Meta, Mistral, and others, so you don’t need a separate account with each vendor.

netclaw provider add openrouter openrouter --api-key sk-or-v1-...

Or configure manually in netclaw.json:

{
  "Providers": {
    "openrouter": {
      "Type": "openrouter"
    }
  }
}

The endpoint defaults to https://openrouter.ai/api/v1 — only override it if you’re using a proxy.

Get your key at openrouter.ai/keys. Browse available models in the OpenRouter model catalog.

Anthropic

Connects directly to Claude models via the Anthropic API.

netclaw provider add my-anthropic anthropic --api-key sk-ant-...

The endpoint defaults to https://api.anthropic.com. Netclaw sends the x-api-key header and anthropic-version: 2023-06-01 on probe requests.

Get your key at console.anthropic.com/settings/keys. See the Anthropic API docs for model versions and usage limits.

OpenAI

OpenAI supports two auth methods: OAuth PKCE (Proof Key for Code Exchange, uses your ChatGPT subscription) and API key (uses platform.openai.com credits).

ChatGPT Subscription (OAuth)

If you already pay for ChatGPT Plus or Pro, this is the way to go — no API keys to manage. Setup happens inside the TUI, which opens a browser window for the OAuth flow:

netclaw provider   # opens Provider Manager

Select + Add new provider, choose OpenAI, then pick ChatGPT Subscription (recommended).

You can also start the OAuth device flow from the CLI without the TUI:

netclaw provider add my-openai openai --auth oauth-device

OAuth requires a browser — if you’re on a headless server over SSH, use the API key method instead.

OAuth tokens expire periodically. When they do, open netclaw provider, select the unhealthy provider, and re-authenticate.

Because OAuth tokens can’t call OpenAI’s /v1/models endpoint, netclaw uses a curated model list:

Category	Models
Frontier	gpt-5.4, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
Reasoning	o3, o3-mini, o4-mini
Codex	gpt-5.3-codex, gpt-5.2-codex, gpt-5-codex

This list is updated with each netclaw release.

API Key

netclaw provider add my-openai openai --api-key sk-proj-...

Get your key at platform.openai.com/api-keys. With API key auth, netclaw discovers available models automatically via /v1/models.

Provider Manager TUI

netclaw provider probes each configured provider on startup and shows whether it’s reachable and authenticated:

Indicator	Meaning
✓	Healthy — models discovered
⚠	Unreachable or auth failure
…	Probe in progress

Select a provider to manage it:

Key	Action
K	Update API key
R	Remove provider
V	Re-validate connection

Environment Variable Overrides

Skip config files entirely by setting environment variables with the NETCLAW_ prefix. Double underscores (__) separate path segments, following the .NET configuration convention:

# Override a provider's API key
export NETCLAW_Providers__openrouter__ApiKey="sk-or-v1-..."

# Point a model role at a provider
export NETCLAW_Models__Main__Provider="openrouter"
export NETCLAW_Models__Main__ModelId="anthropic/claude-sonnet-4"

Environment variables take highest priority, overriding both netclaw.json and secrets.json. On Linux, variable names are case-sensitive — NETCLAW_Providers__openrouter__ApiKey won’t match NETCLAW_PROVIDERS__OPENROUTER__APIKEY.

Probe and Health Checks

When the TUI or daemon starts, netclaw probes each provider by hitting its model-listing endpoint. Each probe has a 10-second HTTP timeout.

Common probe errors:

HTTP Status	Message
401	Invalid credentials — double-check your provider key
403	Access denied — credentials may lack model-listing permissions
404	Models API not found — service may be down
429	Rate limited — wait a moment and try again
5xx	Provider returned an error — may be experiencing issues
Connection failure	Network issue — check endpoint and connectivity

To test your configuration right now, run netclaw doctor for a full config and connectivity diagnostic, or open netclaw provider to see live health status.

Caveats

• Changing providers requires a daemon restart.
• Missing credentials are a startup error, not a warning — the daemon won’t start if a configured provider has no API key and no NETCLAW_Providers__<name>__ApiKey env var.
• Each model role uses exactly one provider. There’s no automatic failover or per-channel provider selection. Change the active provider with netclaw model set.

Related Pages

• netclaw provider — CLI reference for all provider commands
• netclaw model — assign providers to Main, Fallback, and Compaction roles
• Secrets Management — how credentials are encrypted and stored
• Self-Hosted Providers — Ollama and openai-compatible setup
• Models — model role configuration

Resources

• OpenRouter API docs — request format, rate limits, model routing
• Anthropic API docs — authentication, model versions, usage limits
• OpenAI API docs — endpoints, authentication, model capabilities
• .NET environment variable configuration — the double-underscore nesting convention
• RFC 7636 — OAuth PKCE — the code exchange flow OpenAI uses