OpenHands

Settings → LLM → Advanced 需要填写三个字段 — Custom Model、Base URL、API Key — 模型 ID 带有 openai/ 前缀，基础 URL 保留 /v1。

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

分步操作

1. 在 /app/keys 创建密钥并复制——它只会显示一次。
2. 打开 Settings → LLM，然后开启 Advanced 开关。三个字段会按以下顺序显示：Custom Model、Base URL、API Key。
3. 输入带前缀的模型 ID——使用 openai/claude-sonnet-5，而不是 claude-sonnet-5。Kunavo 提供的 ID 可通过 GET /v1/models 获取；OpenHands 自己的文档也建议从该处获取自定义 ID。
4. 将 https://api.kunavo.com/v1 粘贴到 Base URL，并将密钥填入 API Key，然后点击 Save Changes。OpenHands 文档说明，保存本地配置文件前会先通过后端验证配置，验证失败时会阻止保存，因此此处出现的错误代表真实拒绝，而非仅仅是显示问题。
5. 检查后端能够访问的地址，而不是浏览器能够访问的地址。base URL 必须能从运行 Agent Server 的机器解析——文档明确指出，如果 Agent Canvas 在 Docker 中运行，127.0.0.1 指的是容器。Kunavo 这样的公共端点最简单；前面有企业代理的情况则不同。
6. 开始一个新对话，并让它执行读取和编辑文件的任务。OpenHands 指出，已保存的 LLM 设置适用于新对话，而旧对话必须先重启；执行涉及工具的任务，比单纯问候更能验证这组配置是否可用。

已于 2026年9月21日 对照 OpenHands 的语言模型（LLM）设置页面 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 OpenHands 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

调试前值得了解的三个边界

OpenHands 的组成部分比单进程 CLI 更多，其中有两个看起来像 LLM 端点，实际上却不是。以下信息来自其自身文档，查阅日期见上文：

1. 沙盒不是模型。 OpenHands 会在 agent-server 沙盒中运行你的工作，并通过网络调用模型；这是两个彼此独立、凭证也各自独立的接口。在此处配置密钥，只能用于模型调用。它与沙盒能够访问什么无关；沙盒网络问题也不会表现为身份验证错误。
2. ACP 代理完全独立于此配置。 Agent Canvas 可以将任务委派给 Claude Code、Codex 或 Gemini CLI，作为 ACP 代理运行；Configure a Model 页面说明这些代理“自行管理模型访问权限”——因此 LLM 配置不会重定向这些子进程。如果你原以为会看到密钥的使用流量，但实际没有，请检查当前运行的是哪个代理。OpenHands 与 Claude Code 对比详细说明了这种区别，包括决定优先使用哪种凭据的规则。
3. 配置文件，以及最多 10 个的限制。 保存配置后会生成一个 LLM 配置文件；最近保存的配置文件会成为新对话的活动配置文件；也可以在对话中途切换配置文件，而不会丢失上下文——这正是同一个密钥可以灵活用于低价和高价模型的机制。文档将每个账户的配置文件数量限制为 10 个。Provider Connection 可以一次保存提供商、API 密钥和可选的 base URL，供多个配置文件使用；同一页面还指出，该面板只在本地 agent-server 后端上可用，在 OpenHands Cloud 后端上会隐藏。