OpenHands + JoinGonka Gateway：专属 endpoint 上的智能体

该项目目前有几种界面，您在哪里查找模型设置取决于您运行的是哪一个。值在各处都是相同的 — 只有访问路径不同。

Agent Canvas 需要 Node.js 和 uv — 代理的本地服务器在此之上运行（详情请参见安装指南）。指南提到了 Node.js 22.12 或更高版本，但从 1.17 版本开始，包本身要求 Node.js 24 或更高版本 — 请安装 24 以避免不兼容版本的警告。也可以选择容器方式：ghcr.io/openhands/agent-canvas 镜像在 http://localhost:8000/canvas 提供界面，并且仅能看到您挂载的目录。

JoinGonka 密钥。 在 gate.joingonka.ai/register 注册，验证邮箱，并在“API 密钥”部分创建一个带有 jg- 前缀的密钥。一个密钥和一个余额适用于网络中的所有模型。OpenHands 安装程序 @joingonka/setup 的工具列表中没有列出此项，这并不是疏忽：其设置存在于界面和安全的后端存储中，而不是存储在可以在外部编辑的文本配置文件中。

第 1 步。 启动 Agent Canvas 并打开 Settings > LLM。首次运行向导会建议使用 OpenHands 自带的提供商 — 此步骤可以跳过，以后可以轻松回到设置界面。

第 2 步。 点击 Add LLM Profile 并切换到 Advanced 选项卡：Basic 选项卡仅提供内置列表中的提供商和模型。

第 3 步。 填写三个字段：

第 4 步。 保存配置文件。在保存之前，Canvas 会通过后端请求验证配置：如果密钥被拒绝或模型不可用，配置文件将无法保存，您会看到错误信息。

第 5 步。 开始新对话并发送一条简短消息。已经打开的对话将继续使用它们启动时所用的模型。

为什么使用 openai/。 LiteLLM 通过模型前缀确定提供商。openai/ 前缀并不意味着“来自 OpenAI 的模型”，而是指“通过 OpenAI Chat Completions 协议与服务器通信”。只有第一个段会被截掉，因此网关接收到的是实际标识符 — deepseek-ai/DeepSeek-V4-Flash-0731。OpenHands 文档中以 openai/qwen/qwen3.6-35b-a3b 为例展示了相同的方案。如果没有该前缀，LiteLLM 将拒绝工作并返回 LLM Provider NOT provided 消息。

为什么使用 /v1 且不能多写。 LiteLLM 通过官方 OpenAI 客户端访问服务器，该客户端会自动追加 /chat/completions。因此，地址必须以 /v1 结尾：没有后缀，请求将无法连接到 API；带有额外后缀，则会指向不存在的路径。Canvas 的另一个要求是：地址必须能从后端访问，而不仅仅是从浏览器访问。网关是一个公共 HTTPS 地址，它从 Docker 容器中可见，正如从宿主机访问一样；像 host.docker.internal 这样的技巧仅在模型运行在您本地机器上时才需要。

为所有三个模型创建配置文件。 为每个网络模型创建一个配置文件并给它们起一个简短的名称 — 例如 deepseek、glm 和 minimax（文档提到限制为十个配置文件）。您可以在对话中直接切换，而不会丢失上下文：使用输入框中的配置文件选择按钮或输入 /model glm 命令；不带参数的 /model 将显示列表。为了避免在每个配置文件中插入密钥，您可以将其保存在 Provider Connections 块中一次 — 它在本地后端可用。

Docker 中的旧版界面。 字段相同：Settings → LLM 选项卡 → 启用 Advanced → Custom Model、Base URL、API Key → Save Changes。

CLI 通过 uv 一条命令即可安装，首次启动时会自动引导你完成模型配置；之后可用 Ctrl+P → Settings 返回该配置：

uv tool install openhands --python 3.12
openhands

对于脚本来说，环境变量更方便。一个重要细节：默认情况下 CLI 会忽略它们，只有加上 --override-with-envs 标志才会应用——仅对单次运行生效，不保存任何内容：

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

同一套设置无需界面即可运行——适用于 CI 和批处理任务：

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

在 headless 模式下，智能体始终以自动批准方式运作，因此请把它运行在可以放手让它做任何事的地方：独立目录或容器中。--json 标志会把输出转成 JSONL 事件流——便于在管道中解析。我们正是在 2026 年 9 月 21 日以 CLI 1.16.0 这样测试该组合的：CLI 头部会打印 Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731，随后智能体读取文件并给出实质性的回答。

已保存的 CLI 设置位于 ~/.openhands/agent_settings.json：其中的模型通过编辑 llm 块的三个字段来更改——model、api_key 和 base_url。不建议从零创建该文件：首次启动向导还会把智能体的其他设置写入其中，包括历史压缩，没有它，长时间对话会撞上上下文窗口。

如果你要把智能体嵌入自己的代码，OpenHands SDK 接受同样的三个值：

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

网络内所有模型的价格相同，因此选择取决于行为。对于自主智能体而言，两个数字至关重要。上下文窗口：每一步都会重新发送历史记录，窗口越长，智能体在不丢失信息的情况下工作的时间就越长。回复上限：智能体编写完整大文件的步骤必须能够容纳在一次回复中。下表显示了我们运行同一任务（读取文件并查找错误）的结果，该测试通过 OpenHands CLI 1.16.0 和 SDK 1.21.0 进行。

针对长时间运行任务的推荐流程遵循 OpenHands 文档的建议：用一个模型规划，用另一个模型执行。使用 glm 配置开始对话并要求提供计划，无需修改文件；然后发送 /model deepseek 并下达执行命令。切换时历史记录、文件和任务状态都会得到保留。将 minimax 配置作为第三种选择保留：在高峰期前两个模型容量耗尽时切换到它非常方便，而且可以在 Settings > Application 中将其分配用于生成对话标题。

历史记录压缩。 即使拥有数十万 token 的窗口，在长时间任务中依然是有限的。在 OpenHands 中，这由压缩器（condenser）处理：它将旧事件折叠成简短的摘要，根据文档，这能降低长对话中的延迟和 token 消耗。在 Agent Canvas 中，它在 Settings > Condenser 部分进行配置；在我们的 CLI 运行中，它在 80 个事件的阈值下自动启用。

模型限制。 OpenHands 从 LiteLLM 目录中获取上下文窗口和回复上限，而其中不包含 Gonka 网络标识符（我们在 LiteLLM 1.81 上测试过），因此智能体本身没有这些模型的预设值。但这不会干扰运行：网关会根据上表自行应用回复上限。如果您想显式设置限制，SDK 中有 max_input_tokens 和 max_output_tokens 字段，而在 Canvas 中，All 选项卡会显示完整的配置字段。有关默认模型的详细信息，请参阅 DeepSeek V4 Flash 概览。

您可以通过两个方面来确认请求是否真的通过网关。从 OpenHands 端：开启一个新对话并给出一个简短任务，例如“阅读 README 并用一句话总结”：Agent 必须调用工具并给出回复。从网关端：前往后台“使用情况”部分：请求会出现在“按模型”分类中，且“按密钥”部分会更新最后请求时间。如果为空，说明对话是在另一个配置档案中进行的：请检查当前激活的是哪一个。

根据 OpenHands 文档，发生 429 错误时的重试次数和等待间隔可以通过 LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT 和 LLM_RETRY_MAX_WAIT 变量配置。文档和 SDK 中的默认值可能存在差异，建议参考实际表现：在 CLI 1.16.0 的对话状态中，我们观察到 5 次重试，等待间隔在 8 到 64 秒之间。

通过 JoinGonka Gateway，输入端 token 价格为 $0.0069/百万，输出端为 $0.021/百万 — 该价格适用于所有网络模型，并从此页面的实时来源获取。

右侧列出的估算基于 2026 年 9 月的价格；关于 Agent 经济学的运作机制，详见关于 AI Agent 最便宜 API 的文章。

支出上限。 OpenHands 建议设置支出限额 — 网关将其内置于付费模型中：余额为预付制，Agent 的消费不会超过账户内的金额。剩余余额和每日消耗可在后台查看。对于 CI 和后台自动化，请创建单独的密钥，以免与您的主密钥消费混淆；关于带每日限额的子密钥，详见关于 Management Keys 的文章。

信任边界。 通过 npm 启动的 Agent Canvas 以您的用户权限运行，能够访问整个文件系统。对于第三方代码，请使用 Docker 版本：Agent 将只能看到挂载的目录。这是 OpenHands 本身的特性，与模型提供商无关。

对话记录由您掌握。 OpenHands 将对话历史本地存储在 ~/.openhands 中，并在每一步将其发送给模型；网关不会存储对话记录 — 您的提示词和代码在响应后不会保留在网关上。

如果任务涉及图片（如界面截图、架构图），请为其创建一个具备视觉能力的独立配置档案：Gonka 网络模型仅支持文本。对于代码、命令和文件，这不是限制。