OpenCode OAuth2 Plugin 使用指南

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

目录

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

• 二、安装

• 三、配置

• 四、使用

• 五、卸载

• 六、常见问题

• 七、许可证

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

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

• 已安装 OpenCode 客户端

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

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

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

二、安装

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

1. 私有仓库配置

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

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

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

Bun 配置（持久化生效）

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

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

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

2. 安装插件

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

# 使用 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 文件，添加以下配置（直接复制替换或补充）：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@opentj/opencode-oauth2-plugin"],
  "provider": {
    "tj": {
      "id": "1",
      "name": "tj",
      "api": "http://192.168.69.126:6573/v1",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
      "qwen3.6-35b-a3b-fp8": {
        "name": "qwen3.6-35b-a3b-fp8"
      }
    }
    }
  }
}

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

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

2. 验证安装与配置

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

opencode debug config

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

四、使用

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

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

opencode auth login

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

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

2. 同步私有化模型列表

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

opencode

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

/tj-models-refresh

命令注册说明：/tj-models-refresh 命令通过 OpenCode 配置目录下的 commands/tj-models-refresh.md 文件注册。OPENCODE_CONFIG_DIR 环境变量指定的目录下的 commands/ 子目录中的 .md 文件会自动注册为 slash 命令。文件的 frontmatter description 为命令描述，正文内容为命令执行说明。

命令注册示例

假设 OPENCODE_CONFIG_DIR=/path/to/opencode，注册 /tj-models-refresh 命令：

# 创建 commands 目录（如果不存在）
mkdir -p $OPENCODE_CONFIG_DIR/commands

# 创建 tj-models-refresh 命令文件
cat > $OPENCODE_CONFIG_DIR/commands/tj-models-refresh.md << 'EOF'
---
description: Refresh tj models from private server
---

Call the tj-models-refresh tool to fetch model list from the tj private server and update OpenCode local configuration.
EOF

启动模式

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

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

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

3. 查看登录状态

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

opencode auth list

4. 登出账号

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

opencode auth logout

五、卸载

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

1. 卸载插件

# 使用 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/）可正常访问。

3. 模型同步失败？

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

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

4. 插件安装失败？

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

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

5. 插件升级后未生效？

• 核心原因：OpenCode 缓存了旧版本插件，导致新功能不可见

• 解决方案：清空 OpenCode 插件缓存后重试

# macOS/Linux
rm -rf ~/.cache/opencode/packages

# Windows
rd /s /q %USERPROFILE%\.cache\opencode\packages

清空缓存后，重新执行安装命令即可：

npm install -g @opentj/opencode-oauth2-plugin
# 或
bun add -g @opentj/opencode-oauth2-plugin

七、许可证

MIT 许可证