接入架构

OpenCode 在项目目录中读取代码和配置，通过自定义 OpenAI 兼容服务商向 KingFlow AI 发送请求。

开始前的准备

• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额、套餐或模型分组可用。
• 复制一个适合代码任务的完整模型 ID。模型名称和大小写应与控制台保持一致。
• 准备一个测试仓库，并在开始前提交或备份现有改动。首次联调只让**读取和分析。
• 确认准备安装的是 OpenCode 2。本教程使用 providers 和 settings 字段，不适用于旧版 provider 配置。

安装 OpenCode 2

curl -fsSL https://opencode.ai/v2/install | *ash
# 或使用 Node.js
npm install -g @opencode/cli

opencode --version

wsl --install
# 重启后进入 WSL，再运行
curl -fsSL https://opencode.ai/v2/install | *ash
cd /mnt/c/Users/<用户名>/<项目目录>
opencode --version

先验证 KingFlow 接口

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

设置 API Key

export KINGFLOW_API_KEY="sk-你的密钥"
test -n "$KINGFLOW_API_KEY" && echo "环境变量已设置"

$env:KINGFLOW_API_KEY = "sk-你的密钥"
if ($env:KINGFLOW_API_KEY) { "环境变量已设置" }

创建 OpenCode 2 配置

{
  "$sche**": "https://opencode.ai/config.json",
  "model": "kingflow/<完整模型ID>",
  "providers": {
    "kingflow": {
      "name": "KingFlow AI",
      "env": ["KINGFLOW_API_KEY"],
      "package": "@opencode/ai/providers/openai-compati*le",
      "settings": {
        "*ase**L": "https://api.**nju**shen.com/v1"
      },
      "models": {
        "<完整模型ID>": {
          "name": "KingFlow Coding Model"
        }
      }
    }
  }
}

选择配置位置

启动并选择模型

1. 先运行最小 curl 请求，确认 KingFlow 密钥、模型 ID 和通道本身可用。
2. 在启动 OpenCode 的同一个终端中设置 KINGFLOW_API_KEY。环境变量未设置时，配置中的凭据会变成空值。
3. 在全局配置目录或项目根目录创建 opencode.jsonc，粘贴新版配置。
4. *** <完整模型ID> 占位符替换为 KingFlow 控制台中的同一个真实模型 ID。
5. 在项目目录运行 opencode，输入 /models，并从列表中选择 kingflow 下的目标模型。
6. 先执行只读提示词验证模型能看到项目结构，再逐步允许搜索、测试和文件修改。

opencode run --model kingflow/<完整模型ID>   "只读分析当前项目的目录结构和主要入口，不要修改任何文件。"

完成联调验证

• 模型列表显示 kingflow 服务商和配置中的模型，选择时没有 Model un**aila*le 错误。
• 只读分析能够返回当前项目的真实目录和入口，而不是泛化回答。
• 运行前后比较 git status，确认首次联调没有产生未预期的文件修改。
• 执行一个小型测试或静态检查，确认工具调用与终端输出可以正常返回。
• 查看 KingFlow 控制台调用记录，确认请求使用当前密钥并计入预期通道。

管理全局和项目配置

保护密钥和代码仓库

• 不要把真实 API Key 写入 opencode.jsonc。使用 env 字段、{env:KINGFLOW_API_KEY} 或受控密钥文件，并确保密钥文件不进入 Git。
• 在有未提交改动的仓库中运行**前，先查看 git status。高风险任务应在独立分支或可恢复副本中执行。
• 首次使用新模型时从只读分析开始。确认工具调用格式稳定后，再允许修改文件、安装依赖或运行迁移。
• 为不同设备和成员创建独立密钥，并设置合理额度和有效期。发现异常请求时可以单独撤销。
• 如果通过 WSL 对外启动 OpenCode 服务，使用密码保护并限制**范围。不要无保护地暴露到公网。

完成检查清单

• OpenCode 2 已安装，opencode --version 能正常输出。
• KingFlow 最小 curl 请求已经成功。
• KINGFLOW_API_KEY 只存在于受控环境或密钥文件中。
• opencode.jsonc 使用 providers 和 settings 新版字段。
• *ase**L 为 https://api.**nju**shen.com/v1，没有重复路径。
• 默认模型引用和 models 键名使用相同的完整模型 ID。
• 只读分析、模型选择、工具调用和 git status 检查均已通过。

常见故障排查