OpenHands

OpenHands（原 OpenDevin）是一款开源的 AI 驱动软件开发平台，支持通过 Docker 一键部署，提供 Web UI 和 CLI 两种交互方式，可自主完成代码编写、调试、终端操作等开发任务。

准备工作

• 已开通云开发环境，获取环境ID cloudBase环境ID
• 在 AI 控制台中开启所需模型
• 在 AI 控制台中获取 Base URL 和 API Key

Base URLhttps://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase

配置步骤

OpenHands 支持通过 Docker 环境变量或 config.toml 配置文件接入自定义模型。

配置字段对照表

字段	解释
model	大模型 ID，在 AI 控制台 模型列表复制已启用的大模型标识填入
base_url	大模型 Base URL，在 AI 控制台中获取
api_key	调用大模型 API Key，在 AI 控制台中获取

Docker 启动时配置

通过 -e 参数传递环境变量：

docker run -it --rm --pull=always \
    -e LLM_MODEL="hy3-preview" \
    -e LLM_API_KEY="eyJhbGciOiJSUzI1N..." \
    -e LLM_BASE_URL="https://{{cloudBase环境ID}}.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

启动后访问 http://localhost:3000 即可使用。

config.toml 配置文件

备注

此方式仅在开发模式（通过 main.py 或 cli.py 启动）下可用。Docker 方式请使用"Docker 启动时配置"的环境变量。

1. 打开或创建 config.toml 配置文件

~/.openhands/config.toml

2. 在 [llm] 字段中填入大模型配置

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

3. 启动 OpenHands 即可使用配置的自定义模型

常见错误排查

报错信息	解决方法
404 模型未找到	Base URL 填写不正确，请前往 AI 控制台中复制正确的 Base URL
401 认证失败	API Key 填写错误，或者可能被删除
429 Token usage exceeded quota	配置了错误的大模型名称，或者大模型未在 AI 控制台 中启用