> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Providers

<Note>
  Esta página ainda está em inglês. A tradução para português está em andamento.
</Note>

# AI Providers

The **Providers** page lets you choose which LLM backend powers EvoNexus, configure its credentials, and test the connection — all from the dashboard. It lives under **System → Providers** in the sidebar and requires the `config:manage` permission.

EvoNexus uses Anthropic's `claude` CLI by default. To run on any other backend (OpenRouter, OpenAI, Gemini, AWS Bedrock, Google Vertex AI, Codex Auth), it switches to [OpenClaude](https://www.npmjs.com/package/@gitlawb/openclaude) — a drop-in binary that speaks the same CLI protocol but dispatches to the provider of your choice via environment variables.

## Supported Providers

| Provider | Binary | Notes |
| - | - | - |
| **Anthropic** (default) | `claude` | Native Anthropic auth, no extra config |
| **OpenRouter** | `openclaude` | 200+ models via one API — Claude, GPT, Gemini, Llama, etc. |
| **OpenAI** | `openclaude` | GPT-4o, GPT-4.1, o3 via OpenAI API |
| **Google Gemini** | `openclaude` | Gemini 2.5 Pro/Flash via Google AI |
| **Codex Auth** | `openclaude` | Reuses Codex CLI's OAuth session to access OpenAI models |
| **AWS Bedrock** | `openclaude` | Claude via AWS Bedrock |
| **Google Vertex AI** | `openclaude` | Claude via GCP Vertex AI |

## Install OpenClaude (one-time)

If you plan to use any non-Anthropic provider, install OpenClaude globally:

```bash theme={null}
npm install -g @gitlawb/openclaude
```

The Providers page shows a banner at the top indicating whether `claude` and `openclaude` are installed and in `$PATH`. If `openclaude` is missing, the banner shows the install command.

## Activating a Provider

1. Open **System → Providers** in the sidebar
2. Click **Configure** on the provider you want to use
3. Fill in the required fields (API key, base URL, model, region — depending on provider). Secrets are masked in the form and in every API response; placeholders like `sk-...` guide the format
4. Click **Save & Activate**

The active provider is stored in `config/providers.json`. Both the terminal-server and the ADW runner re-read this file on every session spawn, so switching takes effect **immediately** — no restart needed.

A green "Active" badge marks the currently selected provider. Every other provider can still be configured and tested without affecting the active one.

## Testing a Provider

Each provider card has a **Test** button that runs `<binary> --version` with the configured env vars merged into the environment, then reports success or failure inline. This is a sanity check — it verifies that the binary is installed, in `$PATH`, and that the env var injection works. It does **not** validate that your API key actually authenticates against the remote service (use the terminal after activating for that).

## Security: Allowlists and Secret Masking

Both the Python runner (`ADWs/runner.py`) and the JS terminal bridge (`dashboard/terminal-server/src/claude-bridge.js`) enforce two allowlists when reading `config/providers.json`:

* **CLI allowlist** — only `claude` and `openclaude` are accepted as spawn targets. Any other value falls back to `claude`.
* **Env var allowlist** — only the 13 variables listed in [env-variables.md](../reference/env-variables.md#ai-provider-configuration) are injected. Anything else is silently dropped.

The REST API that backs the Providers page masks secrets (`*_KEY`, `*_SECRET`, `*_TOKEN`) as `first6****last4` on every response. When you open the config modal, the form starts empty for those fields — type a new value to replace, or leave empty to keep the current one. Values containing `****` are treated as masked placeholders and skipped on save (so a round-trip through the UI doesn't accidentally overwrite a real secret with the mask string).

The backend also rejects any env var value containing shell metacharacters (`;`, `&`, `|`, backtick, `$`, newlines) — defense in depth against injection if someone points EvoNexus at a compromised `providers.json`.

## Logout Warning

When you switch away from Anthropic to any other provider, OpenClaude inherits your Anthropic Claude Code login state. To avoid confusion, run `/logout` inside Claude Code **once** after activating a non-Anthropic provider if you were previously logged in. The dashboard surfaces this warning on any provider marked `requires_logout`.

## Where It's Stored

* `config/providers.json` — active provider + per-provider CLI + env vars (**gitignored**, contains secrets)
* `config/providers.example.json` — template copied on first boot if no real file exists (checked into git)
* `.env` — unchanged by this feature. AI provider env vars live in `providers.json`, not `.env`

## Configuring at Install Time

The interactive setup wizard (`make setup`) asks which provider to use as step 3. If you pick anything other than Anthropic, it checks whether OpenClaude is installed, offers to install it, then prompts for the provider-specific keys and saves them to `config/providers.json`. You can re-run the wizard or use the dashboard to change providers later.

## Related

* [Environment Variables Reference](../reference/env-variables.md#ai-provider-configuration)
* [Getting Started](../getting-started.md) — step 3 covers provider choice
* [OpenClaude on npm](https://www.npmjs.com/package/@gitlawb/openclaude)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.