tflow
控制台
客户端集成

OpenCode 终端集成指南

配置由 Go 开发的开源 TUI 命令行智能体与桌面应用 OpenCode，通过重定向内置的 OpenAI 协议端点将流量无缝桥接至 tflow 统一网关。

什么是 OpenCode？

OpenCode 是一个开源的 AI 编码智能体，提供终端交互面板（TUI）和桌面应用（Beta 阶段）。它原生集成语言服务器协议 (LSP) 以感知项目上下文，具备多会话切换、Git 提交自动生成等功能。通过将内置的 OpenAI 渠道基址重定向为网关入口，您可以轻松使用 tflow 聚合的全部主力大模型。

快速开始 (Quick Start)

只需几步，即可在本地安装 OpenCode 并完成与 tflow 的服务对接。

1安装 OpenCode

根据您的系统类型与工具包喜好，选择以下任一方式进行全局安装：

macOS, Linux, WSL 一键安装脚本:
terminal.sh
curl -fsSL https://opencode.ai/install | bash
桌面端支持： 您也可以安装桌面版应用，macOS 下可执行 `brew install --cask opencode-desktop` 或是直接从官网下载安装包。若在 Windows 环境下运行，强烈推荐基于 WSL (Windows Subsystem for Linux) 安装并执行客户端。

2获取 API 密钥

请登录您的 tflow 控制台 并获取调用令牌：

  1. 点击顶部导航栏前往「API Keys」页面。
  2. 创建一个具备调用对应模型权限的 API 密钥。
  3. 复制生成的密钥令牌值（以 sk-... 开头）。

3方法一：终端交互式授权

在终端交互面板中注册 OpenAI 渠道密钥，即可安全存储凭证：

  1. 在终端中进入您要开发的工程目录，并启动 OpenCode CLI：
    terminal.sh
    cd /path/to/your/project
opencode
  2. 在 OpenCode 输入栏中执行 `/connect openai` 命令以绑定您的 tflow 凭证：
    OpenCode TUI
    /connect openai
  3. 根据提示粘贴您的 tflow API 密钥。
  4. 连接完成后，通过键入以下命令交互式地浏览与挑选您想要使用的具体模型名称：
    OpenCode TUI
    /models

4方法二：静态配置文件配置

除了交互式界面之外，您还可以使用静态配置文件方式。OpenCode 支持在项目根目录或全局用户目录下读取 opencode.json。

A. 重定向内置 OpenAI 提供商基址:

创建全局配置文件 ~/.config/opencode/opencode.json 或是具体开发项目根目录下的 opencode.json，并将基地址与模型列表映射至 tflow：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://tflow.ai-links.com/v1"
      },
      "models": {
        "MiniMax-M3": {},
        "deepseek-v4-pro": {}
      }
    }
  }
}
B. 存放您的 API 密钥凭证:

将对应的 API 密钥配置写入用户的静态认证文件 ~/.local/share/opencode/auth.json（如果文件不存在，请手动创建）：

auth.json
{
  "openai": {
    "type": "api",
    "key": "sk-your-tflow-api-key"
  }
}
加载优先级： 位于工程项目目录下的本地 opencode.json 文件的规则优先级始终高于全局用户配置，常用于对特定项目覆盖定义专有的 API 密钥与模型白名单列表。

常见问题与诊断

接口鉴权报错 (Authentication Error)

请确保 `auth.json` 或 `/connect` 命令中绑定的密钥完整，且属于已激活的有效密钥组。您可以在 tflow 后台实时检索请求日志，以确定请求是否已被网关拦截并返回了 401 报错。

未能获取或加载特定模型 (Model Not Found)

若要在 OpenCode 中调用特殊别名模型，请确保 `opencode.json` 中配置的模型标识已被添加到您当前 API 密钥的模型白名单里，或者已经在 tflow 后台的管理台重定向选项中建立了别名映射。

终端界面（TUI）排版扭曲或闪退

OpenCode 命令行终端渲染基于 Go Tview/Ccell 库。它对屏幕 the minimal width 有硬性要求。如果在极窄终端窗口内启动会导致报错闪退。请尝试将命令行终端窗口最大化（或适当调小终端字体大小）后再重新执行命令。

相关资源