Connect OpenHands SDK

Configure the OpenHands Software Agent SDK's LLM for a custom Chat Completions endpoint.

AELDER · SERVICE BASE URL

https://aelder.dev/v1

LOCAL CONFIGURATION

Let my agent set this up

Copy this task to an agent already running on your computer. Enter your API key locally when asked.

Help me connect OpenHands SDK to AELDER using this guide: https://aelder.dev/docs/openhands/
Service Base URL: https://aelder.dev/v1
First inspect my installed version, active profile and configuration. Explain any mismatch with the guide before changing anything.
Use the documented local configuration or CLI method. Do not automate the GUI, install software or change permissions without asking.
Preserve existing accounts, providers, models, defaults, permissions and unrelated settings. Propose the smallest change, show a redacted diff, and back up any files before editing.
Have me enter my API key locally using the tool's secret storage or an environment variable. Never ask me to paste a key into chat, print it, or include it in a command, diff, log or commit.
Use the exact model ID I choose from my account's model list. Do not invent model IDs or assume every model supports every API format or tool feature.
Validate syntax and configuration loading before making any generation request. If there is no dry-run, say so.
Explain any proposed paid test, the model and what it sends, and ask for approval before running it. Do not send project files or private conversation history as a test.
Finish with the settings changed, checks performed and steps to restore the backup.

The OpenHands Software Agent SDK exposes native LLM settings for a custom base URL and API key. This guide covers an existing Python SDK application, not an unverified OpenHands web UI or CLI settings flow.

Use a current installed SDK version that supports api_mode. The SDK routes model calls through its built-in LiteLLM integration; no separate proxy process is needed for this configuration.

1. Prepare local values

Set SERVICE_BASE_URL to the Base URL above, including /v1, and SERVICE_MODEL_ID to the exact ID from the authenticated models endpoint. Supply SERVICE_API_KEY with your local secrets tooling or environment.

In Bash or Zsh, this hidden prompt keeps the literal key out of shell history:

printf 'Service API key: '
IFS= read -r -s SERVICE_API_KEY
printf '\n'
export SERVICE_API_KEY

Keep the key out of source control and agent chats. Start the SDK process with these values available.

2. Create an explicit LLM

import os
from openhands.sdk import LLM, Message, TextContent

llm = LLM(
    model="openai/" + os.environ["SERVICE_MODEL_ID"],
    api_key=os.environ["SERVICE_API_KEY"],
    base_url=os.environ["SERVICE_BASE_URL"],
    api_mode="chat",
    num_retries=0,
)

The first openai/ is a LiteLLM routing prefix. The remaining string must be the exact service ID, including any slashes. Do not remove part of the catalog ID. api_mode="chat" explicitly selects Chat Completions rather than relying on automatic protocol selection.

The base URL ends at /v1; do not append /chat/completions. Pass this llm as Agent(llm=llm, ...) in your existing SDK application, preserving its tools, workspace and other settings. Change the ID and recreate the LLM and agent to switch models.

3. Check text before a coding task

Imports and constructing llm check the local setup. This direct call sends a billable request without starting a tool-enabled agent:

response = llm.completion(messages=[
    Message(role="user", content=[TextContent(text="Reply with OK.")])
])
print(response.message)

Confirm the model and usage in your service dashboard. An OpenHands conversation can make multiple requests and use the tools and workspace granted by your application. Test a small task in a disposable workspace before a larger coding run.

Native configuration support does not establish tool calling, reasoning controls, prompt caching, vision or streaming behavior for the selected model. OpenHands may infer capabilities and token metadata from its own model registry. Set overrides only from verified model information; do not copy another model’s limits or prices to suppress an error.

For 401 errors, check the process environment and key. For unknown models, inspect the ID after LiteLLM’s first routing prefix is removed. For protocol errors, confirm api_mode="chat" and that the base URL includes exactly one /v1.

Sources: the official SDK example and LLM configuration implementation. The native SDK settings were reviewed; a live service run has not been verified.

Need the key? Open your AELDER dashboard. For direct API calls, see the API reference.