npm package: @opentj/opencode-oauth2-plugin
Description: OpenCode OAuth2 认证插件
Author: Taiji
Latest version: 1.0.3

# OpenCode OAuth2 Plugin 使用指南

为 [OpenCode](https://opencode.ai) 提供企业 OAuth2 认证功能，支持太极 SSO 单点登录及私有化模型服务接入，适配公司内网环境，全程可直接复制命令执行。

## 目录

- [一、环境前置检查（必做）](#一环境前置检查必做)

- [二、安装](#二安装)

- [三、配置](#三配置)

- [四、使用](#四使用)

- [五、卸载](#五卸载)

- [六、常见问题](#六常见问题)

- [七、许可证](#七许可证)

## 一、环境前置检查（必做）

使用插件前，需确保以下环境条件已满足，避免后续操作报错：

- 已安装 OpenCode 客户端

- 已安装 Node.js 18+（配套 npm）或 Bun 运行环境

- 已连接公司内网（关键，否则无法访问私有仓库及认证服务）

- 已获得企业管理员提供的 OAuth2 凭证（使用太极 SSO 单点登录无需额外配置凭证）

## 二、安装

安装前需先配置公司私有仓库（内网专属），再执行插件安装命令，确保依赖从内网仓库下载。

### 1. 私有仓库配置

根据使用的包管理工具（npm / Bun），选择对应配置方式，配置后立即生效。

#### npm 配置（临时+全局生效）

```Bash

# 配置公司私有 npm 仓库（全局生效）
npm set registry https://repo.taiji.com.cn:8082/repository/npm-all/
```

#### Bun 配置（持久化生效）

需在用户根目录创建配置文件，实现持久化配置：

```Bash

# 1. 创建配置文件（用户根目录）
touch ~/.bunfig.toml

# 2. 写入以下内容到 .bunfig.toml
[install]
registry = "https://repo.taiji.com.cn:8082/repository/npm-all/"
```

### 2. 安装插件

配置完私有仓库后，执行全局安装命令，二选一即可：

```Bash

# 使用 npm 安装
npm install -g @opentj/opencode-oauth2-plugin

# 使用 Bun 安装
bun add -g @opentj/opencode-oauth2-plugin
```

## 三、配置

插件安装完成后，需在 OpenCode 配置文件（opencode.json）中添加插件及提供商配置，确保插件正常加载。

### 1. 配置 opencode.json

找到全局的 opencode.json 或者当前项目根目录下的 opencode.json 文件，添加以下配置（直接复制替换或补充）：

```JSON

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@opentj/opencode-oauth2-plugin"],
  "provider": {
    "tj": {
      "id": "1",
      "name": "tj",
      "api": "http://192.168.69.126:6537/",
      "npm": "@ai-sdk/openai-compatible",
      "models": {}
    }
  }
}
```

### opencode 配置文件优先级（从低到高）

|配置类型|路径|用途|
|---|---|---|
|远程配置|.well-known/opencode|组织级默认|
|全局配置|~/.config/opencode/opencode.json|用户偏好|
|自定义路径|OPENCODE_CONFIG_DIR 环境变量|自定义覆盖|
|项目配置|项目根目录 opencode.json|项目专属|
|内联配置|OPENCODE_CONFIG_CONTENT 环境变量|运行时覆盖|
### 2. 验证安装与配置

执行以下命令，检查插件是否已正确加载：

```Bash

opencode debug config
```

若配置成功，输出结果中可明确看到 `@opentj/opencode-oauth2-plugin` 已在插件列表中。

## 四、使用

插件配置完成后，可通过终端命令完成企业 SSO 登录、模型同步、登录状态查看及登出操作，全程适配太极 SSO 单点登录。

### 1. 企业 SSO 登录（核心操作）

```Bash

opencode auth login
```

执行后按提示选择 "Other"，输入提供商名称 "tj"，跟随引导完成登录。

说明：使用太极 SSO 登录时，无需额外输入 OAuth2 凭证，按页面提示完成公司账号验证即可。

### 2. 同步私有化模型列表

登录成功后，执行以下命令同步公司私有化模型，确保插件可调用内网模型服务：

```Bash

opencode
```

进入 OpenCode 交互界面后，输入命令并执行：

```Plain Text

/tj-models-refresh
```

### 启动模式

执行 `opencode` 后有两种 agent，可使用 tab 切换：

- `build`：默认模式，适合文件操作

- `plan`：适用于指定计划，默认拒绝修改文件

### 3. 查看登录状态

查看当前登录账号及凭证有效性：

```Bash

opencode auth list
```

### 4. 登出账号

退出当前登录账号，清除本地认证凭证：

```Bash

opencode auth logout
```

## 五、卸载

若无需使用插件，需执行卸载命令，并删除配置文件中的插件信息，避免影响 OpenCode 正常运行。

### 1. 卸载插件

```Bash

# 使用 npm 卸载
npm uninstall -g @opentj/opencode-oauth2-plugin

# 使用 Bun 卸载
bun remove -g @opentj/opencode-oauth2-plugin
```

### 2. 清理配置

卸载后，需打开 opencode.json 文件，删除 `"plugin": ["@opentj/opencode-oauth2-plugin"]` 这一行，保存配置即可。

## 六、常见问题

针对内网环境及插件使用过程中常见的报错，提供快速排查方案：

### 1. 认证页面无法打开？

- 核心原因：未连接公司内网或内网访问受限

- 解决方案：确认已连接公司内网/VPN；手动复制终端输出的认证链接，粘贴到浏览器打开。

### 2. Token 请求失败？

- 核心原因：OAuth2 凭证配置错误或 API 地址不可访问

- 解决方案：核对管理员提供的 OAuth2 凭证（无空格、无拼写错误）；检查 opencode.json 中 `api` 地址（[http://192.168.69.126:6537/](http://192.168.69.126:6537/)）可正常访问。

### 3. 模型同步失败？

- 核心原因：未成功登录（Token 失效）或 SProxy 地址错误

- 解决方案：重新执行 `opencode auth login` 完成登录；检查内网 SProxy 地址配置正确，确保可访问模型服务。

### 4. 插件安装失败？

- 核心原因：未配置公司私有仓库，导致无法下载插件依赖

- 解决方案：重新执行“二、安装 > 1. 私有仓库配置”步骤，配置完成后再重新安装插件。

## 七、许可证

MIT 许可证