OpenHands CLI 配置指南：安装、API Key 与 Base URL

通过环境变量将 OpenHands CLI 接入 BetterToken。在 macOS 搭配 GPT 模型的测试中，OpenHands CLI 1.16.0 通过 /v1/responses 完成了无界面模式下的文本请求和文件读取工具调用。

重点信息

字段	值
API Key	在 LLM_API_KEY 中设置 BetterToken API Key
Base URL	在 LLM_BASE_URL 中设置 https://bettertoken.ai/v1
Model	在 LLM_MODEL 中设置 openai/YOUR_MODEL_ID
覆盖配置	--override-with-envs

准备工作

• uv 和 Python 3.12 或更高版本
• BetterToken API Key：注册并获取
• 从模型广场复制的 Model ID

安装

使用官方安装指南中的包名与命令：

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

手动配置

替换 YOUR_API_KEY 和 YOUR_MODEL_ID。保留 LLM_MODEL 中的 openai/ 前缀：

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

启动 OpenHands 时添加 --override-with-envs，让这些变量覆盖已保存的设置。覆盖仅对本次运行生效，不会将值写入配置。

验证连接

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

确认 JSONL 输出中的最终回复为 OK。如需单独验证文件访问，在项目目录中运行，让 OpenHands 读取一个已知文件，同时核对工具结果和最终回复。

切换模型

将 LLM_MODEL 改为 openai/ 加上另一个完整 Model ID，再次运行时添加 --override-with-envs。

常见错误

现象	排查方式
环境变量设置未生效	在命令中添加 --override-with-envs。
认证失败	检查运行 OpenHands 的终端中的 LLM_API_KEY。
接口地址错误	将 LLM_BASE_URL 设为 https://bettertoken.ai/v1，不要添加 /responses 或 /chat/completions。
找不到模型	保留 openai/ 前缀，并从模型广场准确复制 LLM_MODEL 的其余部分。

相关文档

• 对比支持的工具
• API 错误与限流
• OpenHands CLI 命令参考

技术说明

OpenHands CLI 1.16.0 将被测文本请求和文件读取请求发送至 /v1/responses。Base URL 保留到 /v1，具体请求路径由客户端添加。