Skip to main content
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

An ACP agent uses the Agent Client Protocol 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.
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.
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).

​
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.
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:
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:
Then paste into the CODEX_AUTH_JSON field. (On Linux, use xclip -selection clipboard or wl-copy in place of pbcopy.)
Leave the API key and base URL blank in this mode. Save, then start a new conversation.

​
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:
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.

​
FAQ

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.
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.
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).
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.
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.
Agent and credential changes apply to new conversations. Start a new one to pick up the change.
ACP is not enabled for your deployment. Ask your administrator to enable it.
Yes. Choose the Custom preset and enter the launch command for any stdio ACP server, then add whatever credentials it expects as secrets.