Coding Agent setup

OpenHands CLI setup: API key, Base URL, and models

Install OpenHands CLI with uv, configure a BetterToken API Key and Base URL, and verify a headless request with environment variable overrides.

Connect OpenHands CLI to BetterToken with environment variables. In macOS testing with a GPT model, OpenHands CLI 1.16.0 completed headless text requests and file-reading tool calls through /v1/responses.

Key settings

Field	Value
API Key	BetterToken API Key in `LLM_API_KEY`
Base URL	`https://bettertoken.ai/v1` in `LLM_BASE_URL`
Model	`openai/YOUR_MODEL_ID` in `LLM_MODEL`
Configuration override	`--override-with-envs`

Prerequisites

uv and Python 3.12 or later
A BetterToken API Key: register and get one
A Model ID copied from the model plaza

Install

Use the package name and command from the official installation guide:

uv tool install openhands --python 3.12
openhands --version

Manual setup

Replace YOUR_API_KEY and YOUR_MODEL_ID. Keep the openai/ prefix in LLM_MODEL:

export LLM_MODEL="openai/YOUR_MODEL_ID"
export LLM_API_KEY="YOUR_API_KEY"
export LLM_BASE_URL="https://bettertoken.ai/v1"

Pass --override-with-envs when starting OpenHands so these variables override stored settings. The override applies to that run and does not save the values to your configuration.

Verify the connection

openhands --headless --json --override-with-envs -t "Reply with only: OK"

Check the final answer in the JSONL output for OK. To check file access separately, run from your project and ask OpenHands to read a known file; check both the tool result and final answer.

Switch models

Change LLM_MODEL to openai/ followed by another exact Model ID. Run again with --override-with-envs.

Common errors

Symptom	What to check
Environment settings do not apply	Include `--override-with-envs` in the command.
Authentication fails	Check `LLM_API_KEY` in the terminal running OpenHands.
Wrong endpoint	Use `https://bettertoken.ai/v1` as `LLM_BASE_URL`, without `/responses` or `/chat/completions`.
Model is not found	Keep the `openai/` prefix and copy the rest of `LLM_MODEL` exactly from the model plaza.

Technical details

OpenHands CLI 1.16.0 sent the tested text and file-reading requests to /v1/responses. Keep the Base URL at /v1; the client supplies the request path.