OpenHands

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.

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.

Run with environment overrides

The uvx command below is a Codex Pooler smoke-friendly way to run the published OpenHands CLI. It is not a replacement for the upstream installation guide.

export LLM_API_KEY=<pool-api-key>
export LLM_BASE_URL=http://localhost:4000/v1
export LLM_MODEL=openai/gpt-5.5

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

LLM_API_KEY is your Codex Pooler Pool API key. It authenticates /v1 model requests and should stay out of shell history, logs, tickets, and screenshots.

Deployed instances

For a deployed Codex Pooler instance, keep the same OpenHands options and change only the base URL:

export LLM_API_KEY=<pool-api-key>
export LLM_BASE_URL=https://codex-pooler.example.com/v1
export LLM_MODEL=openai/gpt-5.5

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

Model naming

Use LLM_MODEL=openai/gpt-5.5 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.

The audited OpenHands app source delegates authoritative LLM limit parsing to openhands-sdk; the local app checkout does not expose source-verifiable gpt-5.5 context or output limit fields. Keep this example to model/base URL environment overrides unless the SDK source is audited too.

Boundaries

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.