通过 OpenAI 兼容 provider 把 OpenHands agent 接到 Router One

安装 CLI，并在 Advanced 模式下打开 LLM 设置

用 uv tool install openhands --python 3.12（要求 Python 3.12 及以上）或官方安装脚本安装 CLI。首次运行会直接进入 LLM 设置；之后按 Ctrl+P 选择 Settings。把 Settings Mode 从 Basic 切到 Advanced：Basic 模式只有 provider 和模型下拉框、没有 Base URL 字段，请求会直接发给供应商。Advanced 模式要求同时填写 Custom Model 和 Base URL，并且原样保存 Custom Model 字符串，不会自动补 provider 前缀。填入 openai/ 加精确目录 ID、带 /v1 的 base URL，以及一把专用的 Router One Key：

# OpenHands CLI → Ctrl+P → Settings → Settings Mode: Advanced
Custom Model:  openai/<exact-model-id-from-/models>
Base URL:      https://api.router.one/v1
API Key:       sk-your-router-one-key
# Saved to ~/.openhands/agent_settings.json as llm.model / llm.base_url / llm.api_key

把 OpenHands 配置到 Router One base URL

headless 运行、CI 任务或没有保存设置的容器，可以导出三个 LLM_* 变量，再用 --override-with-envs 启动 OpenHands。不带这个参数时，CLI 会打印警告并忽略这些变量；带上后，它们只在本次运行覆盖 ~/.openhands/agent_settings.json，不会保存到文件。尚无设置文件时，LLM_API_KEY 和 LLM_MODEL 必填，LLM_BASE_URL 则决定请求发往 Router One 而不是供应商默认地址。agent 和记忆压缩器都会使用覆盖后的模型：

# Headless / CI / container run: the values apply only with --override-with-envs
export LLM_BASE_URL=https://api.router.one/v1
export LLM_API_KEY=sk-your-router-one-key
export LLM_MODEL=openai/<exact-model-id-from-/models>

openhands --override-with-envs --headless -t "List the test commands in this repo"

各模型 ID 实际到达哪个端点

LiteLLM 把开头的 openai/ 当作指令：对这个 base URL 使用 OpenAI 协议。它会去掉第一段，把剩余部分作为 model 字段发送，所以安全写法是 openai/ 加完整目录 ID，目录 ID 本身已带厂商段；OpenHands 文档对代理场景写明的正是 openai/<proxy-prefix>/<model-name> 形式。走哪条路径由模型字符串决定：OpenHands 把包含 gpt-5 的 ID 走 Responses API，其余走 Chat Completions，除非 LiteLLM 模型元数据或能力覆盖另有指定。Router One 对 GPT 系列 ID 原生提供 /v1/responses，所以两条路径都用同一个 /v1 base URL。Responses 路径上 OpenHands 默认发送 store: false、reasoning effort 为 high，并请求加密的推理内容；先在 Trace 里确认第一步 GPT 请求成功，再依赖它。

每一步都带工具定义，压缩器是第二个调用方

OpenHands 每一步都用原生 function calling 发送终端和文件编辑工具的定义，agent 不会发出不带工具的纯文本请求：请选择详情页在上表端点上列出工具调用能力的模型。记忆压缩默认开启，它用同一模型、Key 和 base URL 再建一个 LLM 客户端，单独发送总结请求，在 Trace 里显示为独立的行。隔离环境、命令执行和 agent 循环都在应用侧：Router One 记录每次模型调用的 tokens、费用和状态，不运行 agent。OpenHands 自己显示的费用来自 LiteLLM 价格表以及可选的 input_cost_per_token、output_cost_per_token 字段，只能当估算，以 Trace 为准核账。一个任务可能发出几十次请求，请给 OpenHands 单独建 Key 并设置 maxSpend 上限；这把 Key 会以明文保存在 agent_settings.json 里。

OpenHands 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 OpenHands 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

OpenHands 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 OpenHands 的调用

先在 OpenHands 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题