> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-docs-acp-litellm-configuration.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring ACP Agents

> Set up Claude Code, Codex, and Gemini CLI on OpenHands Enterprise — with a provider subscription, a provider API key, or your own LiteLLM/Bedrock proxy.

OpenHands Enterprise (OHE) can run your conversations with the built-in
**OpenHands** agent or with a third-party **ACP agent** — Claude Code, Codex, or
Gemini CLI. You choose and configure this on the **Settings → Agent** page. This
guide explains what an ACP agent is, walks through the three ways to give it
model access, and answers the questions we hear most often.

## OpenHands agent vs. ACP agent

|                     | OpenHands agent            | ACP agent                                               |
| ------------------- | -------------------------- | ------------------------------------------------------- |
| Who runs the loop   | OpenHands                  | The provider's own CLI (Claude Code, Codex, Gemini CLI) |
| Model configuration | OHE's central LLM settings | Configured per agent on **Settings → Agent**            |
| Tools & prompts     | OpenHands tools and skills | The provider CLI's own tools and behavior               |

An **ACP agent** uses the [Agent Client Protocol](https://agentclientprotocol.com/protocol/overview)
to run a coding-agent CLI as the backend for your conversation. Instead of OHE
calling an LLM directly, it launches the provider's CLI, which manages its own
model calls, tools, and execution. You send messages and see the results in the
same OHE conversation view.

<Note>
  **Where does it run?** The ACP agent CLI runs **inside your sandbox**, next to
  your workspace — the same place your code and terminal live. It is not a
  separate service you have to host. Because it runs in the sandbox, it has
  direct access to the workspace files.
</Note>

<Info>
  **Model routing is per agent.** OHE's central model configuration applies to
  the OpenHands agent. Each ACP agent manages its own model routing through the
  settings on this page — so you point each one at the model access you want
  (subscription, API key, or your proxy).
</Info>

## Before you start

* The **Settings → Agent** page must show an **Agent** dropdown with an **ACP**
  option. If you only see OpenHands settings, ACP is not enabled for your
  deployment — ask your administrator to enable it.
* Changes on this page apply to **new conversations**. A conversation keeps the
  agent and settings it started with.

## The Settings → Agent page

When you set **Agent** to **ACP**, the page shows:

* **Preset** — Claude Code, Codex, Gemini CLI, or **Custom**.
* **Command** — the command that launches the agent. Picking a preset fills this
  in for you; leave it as-is unless you are running a custom server.
* **Model** — pick a suggested model for the provider, or choose **Custom** to
  enter your own model ID.
* **Credentials** — API key, optional base URL, and any provider-specific
  sign-in fields. Everything here is optional and is saved as a **global secret**
  (the same secrets you can manage under **Settings → Secrets**).

Fill in what you need, then click **Save** once — it saves the agent choice and
the credentials together.

## Choose how the agent gets model access

There are three ways to give an ACP agent access to a model. Pick the one that
matches your situation.

<Tabs>
  <Tab title="Provider subscription">
    Use this when your team has a provider subscription — Claude Pro/Max, a
    ChatGPT plan for Codex, or a Google login for Gemini. No LLM API key needed.

    On **Settings → Agent**, choose **Agent = ACP**, pick the **Preset**, pick a
    **Model**, and fill in that provider's sign-in credential:

    | Provider        | Sign-in field                                                                                                                          | How to get it                                                               |
    | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
    | **Claude Code** | `CLAUDE_CODE_OAUTH_TOKEN`                                                                                                              | Run `claude setup-token` in a terminal                                      |
    | **Codex**       | `CODEX_AUTH_JSON`                                                                                                                      | Paste the contents of `~/.codex/auth.json` from a ChatGPT‑logged‑in machine |
    | **Gemini CLI**  | Vertex AI fields (`GOOGLE_APPLICATION_CREDENTIALS_JSON`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `GOOGLE_GENAI_USE_VERTEXAI`) | From your Google Cloud project                                              |

    <Tip>
      For the paste-the-file-contents fields (`CODEX_AUTH_JSON` and Gemini's
      `GOOGLE_APPLICATION_CREDENTIALS_JSON`), copy the file straight to your
      clipboard instead of opening it. On macOS, from a terminal window:

      ```bash theme={null}
      cat ~/.codex/auth.json | pbcopy
      ```

      Then paste into the `CODEX_AUTH_JSON` field. (On Linux, use `xclip
                  -selection clipboard` or `wl-copy` in place of `pbcopy`.)
    </Tip>

    Leave the API key and base URL blank in this mode. **Save**, then start a new
    conversation.
  </Tab>

  <Tab title="Provider API key">
    Use this to point the agent straight at Anthropic, OpenAI, or Google with an
    API key from that provider.

    On **Settings → Agent**, choose **Agent = ACP**, pick the **Preset**, pick a
    **Model**, and set the provider's **API key**. Leave the base URL blank so the
    CLI uses the provider's default endpoint.

    | Provider        | API key field       |
    | --------------- | ------------------- |
    | **Claude Code** | `ANTHROPIC_API_KEY` |
    | **Codex**       | `OPENAI_API_KEY`    |
    | **Gemini CLI**  | `GEMINI_API_KEY`    |

    Leave the subscription/sign-in fields blank in this mode (see
    [Which credential wins](#which-credential-wins)). **Save**, then start a new
    conversation.
  </Tab>

  <Tab title="Your LiteLLM / Bedrock proxy">
    Use this when you already run a LiteLLM proxy (including one that fronts AWS
    Bedrock) and want ACP agents to use your managed models — no external
    provider API keys required. This is the recommended setup for self-hosted
    deployments that already centralize model access.

    On **Settings → Agent**, choose **Agent = ACP**, pick the **Preset**, pick a
    **Model**, then set the provider's **API key** to your LiteLLM key and its
    **base URL** to your proxy URL:

    | Provider        | Set API key to your LiteLLM key | Set base URL to your proxy |
    | --------------- | ------------------------------- | -------------------------- |
    | **Claude Code** | `ANTHROPIC_API_KEY`             | `ANTHROPIC_BASE_URL`       |
    | **Codex**       | `OPENAI_API_KEY`                | `OPENAI_BASE_URL`          |
    | **Gemini CLI**  | `GEMINI_API_KEY` (required)     | `GEMINI_BASE_URL`          |

    Leave the subscription/sign-in fields blank so they don't override the proxy
    (see [Which credential wins](#which-credential-wins)). **Save**, then start a
    new conversation.

    <Note>
      Your proxy URL is your deployment's LiteLLM URL. On OpenHands SaaS this is
      `https://llm-proxy.app.all-hands.dev`; on a self-hosted cluster it's your
      own LiteLLM endpoint. The model you pick must be registered on your proxy —
      see [Why do I get "model not found"](#faq).
    </Note>
  </Tab>
</Tabs>

## Which credential wins

Each provider can authenticate two ways, and its **sign-in credential takes
priority over an API key**. If you set both, the API key and base URL are
ignored — which is the usual reason a proxy or key "does nothing." Set only the
credentials for the mode you want:

| Provider        | Sign-in credential (wins if set)                                                                           | API key + base URL (used only when sign-in is blank) |
| --------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Claude Code** | `CLAUDE_CODE_OAUTH_TOKEN`                                                                                  | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`            |
| **Codex**       | `CODEX_AUTH_JSON`                                                                                          | `OPENAI_API_KEY`, `OPENAI_BASE_URL`                  |
| **Gemini CLI**  | Vertex/OAuth fields (`GOOGLE_APPLICATION_CREDENTIALS_JSON`, `GOOGLE_CLOUD_*`, `GOOGLE_GENAI_USE_VERTEXAI`) | `GEMINI_API_KEY`, `GEMINI_BASE_URL`                  |

<Warning>
  To route through a proxy or a direct API key, leave the sign-in credential for
  that provider **blank**. For Claude Code in particular, a
  `CLAUDE_CODE_OAUTH_TOKEN` causes both `ANTHROPIC_API_KEY` and
  `ANTHROPIC_BASE_URL` to be dropped.
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="Do I need external provider API keys if I already run LiteLLM?">
    No. Point each ACP agent at your proxy using its API key and base URL fields
    (the **Your LiteLLM / Bedrock proxy** tab above). The agent then uses your
    managed models, and no Anthropic/OpenAI/Google key is required.
  </Accordion>

  <Accordion title="Does the ACP agent use OHE's central model configuration?">
    No. OHE's central LLM settings apply to the OpenHands agent. Each ACP agent
    manages its own model routing through the credentials on the
    **Settings → Agent** page. That's why you configure the model access per agent
    here.
  </Accordion>

  <Accordion title="Will my model name and provider format be translated when going through the proxy?">
    No — and that's what makes this reliable. Each CLI resolves its own model and
    calls your proxy directly in that provider's native format; OHE does not sit
    in the middle rewriting the request. The only requirement is on your proxy:
    register each model under the name that CLI uses and accept that provider's
    API format (LiteLLM supports all three, including with Bedrock upstream).
  </Accordion>

  <Accordion title="Why do I get a &#x22;model not found&#x22; error?">
    The model you selected isn't registered on your proxy under the name the CLI
    sent. Register that model on the proxy, or pick a model in OHE that your proxy
    already exposes.
  </Accordion>

  <Accordion title="My proxy or API key seems to be ignored.">
    A sign-in credential is set and taking priority. Clear the provider's sign-in
    field (`CLAUDE_CODE_OAUTH_TOKEN`, `CODEX_AUTH_JSON`, or Gemini's Vertex/OAuth
    fields), re-save the API key and base URL, and start a new conversation. See
    [Which credential wins](#which-credential-wins).
  </Accordion>

  <Accordion title="I changed the settings but my conversation didn't change.">
    Agent and credential changes apply to **new** conversations. Start a new one
    to pick up the change.
  </Accordion>

  <Accordion title="I don't see an ACP option under Settings → Agent.">
    ACP is not enabled for your deployment. Ask your administrator to enable it.
  </Accordion>

  <Accordion title="Can I use an ACP agent that isn't in the list?">
    Yes. Choose the **Custom** preset and enter the launch command for any
    stdio ACP server, then add whatever credentials it expects as secrets.
  </Accordion>
</AccordionGroup>

## Related

* [ACP Agents](/openhands/usage/agent-canvas/acp-agents) — how ACP agents work and how authentication is detected
* [External LLM Gateways](/enterprise/integrations/external-llm-gateways) — route the **OpenHands** agent through an external gateway
* [Agent Client Protocol](https://agentclientprotocol.com/protocol/overview)