OpenHands

OpenHands (formerly OpenDevin) is an open-source, AI-driven software development platform. It supports one-click deployment via Docker, offers both Web UI and CLI interaction modes, and can autonomously complete development tasks such as code writing, debugging, and terminal operations.

Prerequisites

• You have activated a TCB environment and obtained the environment ID cloudBaseEnvID.

• Enable the required model in the AI console.

• Obtain the Base URL and API Key in the AI console.

Configuration Steps

OpenHands supports connecting custom models through Docker environment variables or the config.toml configuration file.

Configuration Field Mapping Table

Field	Explanation
model	The large model ID. Copy the identifier of an enabled large model from the model list in the AI console and enter it here.

| api_key  | The API Key for calling the large model, which is obtained in the [AI console](https://tcb.tencentcloud.com/dev#/ai?tab=text-aiModel).         |

### Method 1: Configuration During Docker Startup

Pass the environment variables through the `-e` parameter:

```bash
docker run -it --rm --pull=always \
    -e LLM_MODEL="hy3-preview" \
    -e LLM_API_KEY="eyJhbGciOiJSUzI1N..." \
    -e LLM_BASE_URL="https://{{cloudBaseEnvID}}.api.tcloudbasegateway.com/v1/ai/cloudbase" \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    -v /var/run/docker.sock:/var/run/docker.sock \
    ghcr.io/openhandsai/openhands:main

After startup, access http://localhost:3000 to use it.

Method 2: The config.toml Configuration File

note

This method is available only in development mode (started via main.py or cli.py). For the Docker method, use the environment variables from Method 1.

1. Open or create the config.toml configuration file.

~/.openhands/config.toml

2. Enter the large model configuration in the [llm] field.

[llm]
model = "hy3-preview"
api_key = "eyJhbGciOiJSUzI1N..."
base_url = "https://{{cloudBaseEnvID}}.api.tcloudbasegateway.com/v1/ai/cloudbase"

3. Start up OpenHands to use the configured custom model.

Common Error Troubleshooting

Error Message	Solution
404 Model Not Found	The Base URL is entered incorrectly. Go to the AI console to copy the correct Base URL.
401 Authentication Failed	The API Key is entered incorrectly or may have been deleted.
429 Token usage exceeded quota	An incorrect large model name is configured, or the large model is not enabled in the AI console.