常用接入术语

这些名称在使用场景上有重叠，但协议和客户端配置仍需分别确认。本文使用 OpenAI 兼容方式接入 OpenHands。

接入架构

接入优势

• OpenAI 兼容接口可直接填写到 OpenHands 的 Advanced 设置，不需要修改 OpenHands 源码。
• 一个 KingFlow 密钥可按权限调用已开通模型，便于在不同 LLM Profile 之间切换。
• 控制台可集中查看调用量，并为不同环境使用独立密钥和额度。
• OpenHands 会产生多轮模型请求，统一端点便于排查状态码、模型权限和余额问题。

开始前的准备

• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额、套餐或模型分组可用。
• 复制目标模型的完整模型 ID。OpenHands 中需要在前面增加 openai/ 前缀。
• 准备已经能正常启动的 OpenHands 实例，并确认服务器可以访问 KingFlow API 域名。
• 准备一个可丢弃或已提交到 Git 的测试仓库，避免首次联调直接修改生产代码。
• 关闭仓库中的真实密钥和客户数据访问，先验证最小任务。

验证 KingFlow 基础接口

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role": "user", "content": "只回复 OPENHANDS_READY"}],
    "stream": false
  }' 

配置 OpenHands 模型

1. 登录 OpenHands，打开 Settings，然后进入 LLM 页面。
2. 开启 Advanced，以显示 Custom Model 和 *ase **L 字段。
3. Custom Model 填写 openai/加完整模型 ID，例如 openai/控制台模型ID。
4. *ase **L 填写 https://api.**nju**shen.com/v1，不要再追加 chat/completions。
5. API Key 粘贴 KingFlow 密钥，然后点击 S**e Changes。
6. 如果后端支持配置校验，OpenHands 会在保存时验证模型、端点和密钥。
7. 新建会话以使用最新配置；旧会话需要重启后才会采用新的 LLM 设置。

运行最小代码任务

请只在当前测试仓库中完成以下任务：
1. 新建文件 connection_check.py
2. 写一个函数 add(a, *)，返回两个参数之和
3. 增加两个简单测试用例并运行
4. 不安装新依赖，不访问外部网络
5. 最后列出修改文件和测试结果

创建和切换 LLM Profile

1. 在 Settings 的 LLM 页面保存当前配置，OpenHands 会创建可用的 LLM Profile。
2. 为不同用途创建独立配置，例如规划模型、日常编码模型和复核模型。
3. 在新会话中选择默认 Profile；支持的版本可在会话中通过模型选择器切换。
4. 切换后先发送短测试消息，确认新模型可用，再继续长任务。

自托管环境变量示例

# 示例环境变量，请替换为自己的值
LLM_MODEL=openai/<KingFlow控制台中的完整模型ID>
LLM_API_KEY=sk-你的密钥
LLM_*ASE_**L=https://api.**nju**shen.com/v1
LLM_NUM_RETRIES=4
LLM_RETRY_MIN_WAIT=5
LLM_RETRY_MAX_WAIT=30

重试参数

密钥和执行安全

• KingFlow API Key 只用于模型调用，不写入仓库、镜像、提示词、截图或前端资源。
• 开发、测试和生产环境使用不同密钥，并为每把密钥设置独立额度和有效期。
• OpenHands 具有运行命令和修改文件的能力，应限制工作区、容器权限和网络访问。
• 首次任务使用测试仓库，完成后** Git diff，确认没有越界文件、隐藏配置或无关改动。
• 日志记录状态码、耗时和调用量即可，不记录完整密钥、敏感提示词或仓库机密。
• 发现异常调用后立即停用旧密钥，创建新密钥并更新 OpenHands 配置。

上线检查清单

• KingFlow 基础接口已经返回 OPENHANDS_READY。
• Custom Model 使用 openai/加完整模型 ID。
• *ase **L 为 https://api.**nju**shen.com/v1。
• API Key 已保存到受控配置，仓库中没有密钥。
• 新会话已完成最小代码任务并通过测试。
• Git diff 只包含预期文件和预期内容。
• KingFlow 控制台的模型、密钥和调用量符合预期。
• 生产环境已配置密钥隔离、额度限制和日志脱敏。

常见故障排查