# 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.

```bash
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:

```bash
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.