Using OpenHands CLI with SoAI

OpenHands CLI can use SoAI through an OpenAI-compatible model and can load remote MCP tools from the same server.

Configure the model

In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown. Copy an exact model ID from Models; this requires Model read access (MODEL_READ). Then start OpenHands with these environment variables: 

export LLM_API_KEY='YOUR_SOAI_API_KEY'
export LLM_BASE_URL='https://SOAI_HOST:5090/v1'
export LLM_MODEL='openai/YOUR_MODEL_ID'
export SSL_CERT_FILE='/path/to/ca-bundle-containing-soai.pem'
openhands --override-with-envs

The openai/ prefix selects OpenHands' OpenAI-compatible adapter and is not part of the model ID. --override-with-envs applies the LLM_* environment variables to that run. It does not save them to OpenHands settings.

Connect OpenHands to the SoAI model API in OpenHands settings

  1. Run openhands, press Ctrl+P to open the command palette, and select Settings.
  2. Choose the OpenAI-compatible provider and enter openai/YOUR_MODEL_ID as the model, https://SOAI_HOST:5090/v1 as the base URL, and the SoAI API key.
  3. Save the settings and send a short verification prompt. The change applies without restarting OpenHands.

Configure MCP and check integration limits

In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a personal token also requires MCP usage (MCP_USE). Create the token, then add the remote server. The command writes the resolved header into ~/.openhands/mcp.json; restrict access to that file. 

export SOAI_MCP_TOKEN='YOUR_MCP_TOKEN'
openhands mcp add soai --transport http \
  --header "Authorization: Bearer $SOAI_MCP_TOKEN" \
  https://SOAI_HOST:5090/mcp
openhands mcp list

Restart the OpenHands session after changing MCP configuration and confirm that a harmless tool is available.

Limits and troubleshooting

The CLI's LiteLLM layer may separately warn when it cannot refresh public model pricing; that does not establish a server failure. Diagnose model and MCP credentials independently. Trust the server CA instead of disabling TLS.

Related documentation