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

> ## Agent Instructions
> Treat Clawdi as one product.
> Recommend the Cloud Agent quickstart for most new users.
> Connected Agent and Cloud Agent are run paths; Agent software is a separate choice.
> Do not present shared Clawdi capabilities as exclusive to one run path.

# AI Providers

> Configure a local Connected Agent catalog without confusing it with Cloud Agent provider and model controls.

An AI Provider records how Agent software reaches a model service. Keep these
two surfaces separate:

| Surface                                      | Scope                                        | What it changes                                                                  |
| -------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------- |
| Local Provider Catalog                       | One Connected Agent computer                 | Local records, credential references, and supported Agent software configuration |
| Dashboard AI Providers and Agent AI controls | Your remote account and selected Cloud Agent | Credentials and model binding for that Cloud Agent's remote runtime              |

Changing one surface does not automatically change the other. See [Core
concepts](/concepts/core-concepts#ai-provider) and the [Cloud Agent
overview](/cloud-agents/overview).

## Add a local Provider record

Use an environment or exact Vault reference instead of putting an API key in
the catalog:

```bash theme={null}
clawdi ai-provider add openai-main \
  --type openai \
  --default-model <model-id> \
  --auth env:OPENAI_API_KEY

clawdi ai-provider validate openai-main
clawdi ai-provider test openai-main
```

The local catalog stores metadata and the `env:OPENAI_API_KEY` reference, not
the environment variable's value. The default test checks configuration and
credential availability. Add `--live` only when you intentionally want a
direct provider probe.

To use a Vault value, first copy the exact reference from `clawdi vault list`
and pass it as the auth reference:

```bash theme={null}
clawdi ai-provider add openai-vault \
  --type openai \
  --default-model <model-id> \
  --auth 'clawdi://project/<project-id>/vault/providers/field/OPENAI_API_KEY'
```

<Note>
  The local catalog lives on this computer. It does not upload its records to
  the dashboard AI Providers page, and Clawdi does not proxy the Agent's model
  requests; supported local Agent software calls the provider directly.
</Note>

## Apply a local record to supported Agent software

Provider projection differs by CLI version and Agent software. First inspect
the shipped help:

```bash theme={null}
clawdi ai-provider --help
clawdi ai-provider apply --help
```

When `apply` is available, preview the target before writing its native
configuration:

```bash theme={null}
clawdi ai-provider apply openai-main --target codex --dry-run
clawdi ai-provider apply openai-main --target codex
clawdi ai-provider status
```

If the installed CLI does not advertise `apply` for the intended software,
configure that software through its own supported provider settings. A catalog
record by itself is inventory, not proof that an Agent is using it.

## Configure a Cloud Agent Provider

Use the dashboard for the remote path:

1. Open **AI Providers** and choose **Add provider**.
2. Select one of the providers currently offered, choose the authentication
   method shown, and finish credential setup.
3. Use the connection test and resolve any setup warning before assignment.
4. Open **Agents**, select the Cloud Agent, and open **AI**.
5. Choose the provider and primary model available for that Agent, then select
   **Save changes**.
6. Wait for the Agent page to finish updating before testing a new
   conversation.

<Check>
  The Cloud Agent's AI section shows the saved provider and model, and the
  Agent can start a model-backed conversation after its runtime is ready.
</Check>

These controls update the remote runtime. They do not edit the local Provider
Catalog on your computer. Conversely, `clawdi ai-provider add` does not assign
a provider to a Cloud Agent.

<Warning>
  Removing a dashboard Provider that is assigned to a Cloud Agent can leave
  that Agent without model access. Reassign affected Agents first and review
  the impact shown by the removal confirmation.
</Warning>

For local catalog, OAuth, import, export, and provider-specific options, use
`clawdi ai-provider --help` and the relevant subcommand help. For remote
lifecycle behavior, see [Cloud Agent settings and
lifecycle](/cloud-agents/settings-and-lifecycle).