OpenHands on Codex Pooler

OpenHands CLI can use Codex Pooler through the narrow OpenAI-compatible /v1 surface. Keep the Pool API key in the environment, point OpenHands at the /v1 base URL, and pass --override-with-envs so the environment values win for the run without persisting Pool settings.

Before you start

• OpenHands CLI installed, or uv available for the one-shot command below.
• A Codex Pooler URL reachable from the client.
• A Pool API key and a model available to that Pool.

Use a Pool API key for model requests. Operator MCP access is optional and uses a separate token.

Configure the connection

Config/state directory

OpenHands CLI stores local state under ~/.openhands/, created on first run. Current OpenHands CLI docs list these files:

Path	Purpose
~/.openhands/agent_settings.json	LLM configuration and agent settings
~/.openhands/cli_config.json	CLI preferences
~/.openhands/mcp.json	MCP server configuration
~/.openhands/conversations/	Conversation history

On Windows, OpenHands CLI runs through WSL in the upstream install docs, so those paths live in the WSL user’s home directory. This Codex Pooler example uses environment overrides instead of saved config because it is explicit, easy to test, and does not mutate the user’s OpenHands state.

Environment overrides

Set CODEX_POOLER_API_KEY to your Pool API key, then configure the shell that will start OpenHands:

export LLM_API_KEY="$CODEX_POOLER_API_KEY"
export LLM_BASE_URL=https://codex-pooler.example.com/v1
export LLM_MODEL=openai/gpt-6-sol

LLM_API_KEY is your Codex Pooler Pool API key. Keep it out of shared logs and screenshots. For local setup, change LLM_BASE_URL to http://localhost:4000/v1.

Choose a model

Use LLM_MODEL=openai/gpt-6-sol for OpenHands. The openai/ prefix makes OpenHands select its OpenAI-compatible provider path. Codex Pooler receives the request on /v1 and routes it through the assigned Pool.

Define only models that your Pool can serve. If your Pool exposes a different model, keep the openai/ prefix and change the model id after the slash.

Verify the connection

Run the published OpenHands CLI with the environment values above. The uvx command is a one-shot setup; it does not replace the upstream installation guide.

uvx --python 3.12 --from openhands openhands \
  --headless \
  --override-with-envs \
  -t 'Check the repository and summarize what you can do.'

Confirm that the command completes with a repository summary. In Codex Pooler’s request logs, match the request time, API key, model, and final status to your test. A reply alone does not confirm that the client used your Pooler instance.

Compatibility notes

Codex Pooler provides narrow OpenAI-compatible /v1 support for selected SDK and agent routes. It doesn’t provide full OpenAI API parity.

OpenHands should use http://localhost:4000/v1 for local setup or https://codex-pooler.example.com/v1 for deployed examples. Do not point OpenHands at the Codex backend compatibility route.

The operator MCP endpoint is separate from /v1 and is not needed for OpenHands model use. Use Pool API keys only for runtime requests.