OpenCode

开源终端 AI coding agent（sst/opencode），是联想内部 tianxicode（opencode 二开的模型调用 CLI）的上游基座。本页覆盖更新机制与配置文件/凭据（参考级）。

更新机制

opencode upgrade [version]：升级到最新或指定版本
--method 显式/自动识别安装方式：curl / npm / pnpm / bun / brew / choco / scoop——升级路径感知安装渠道，按原渠道升级
配置项 "autoupdate": false（~/.config/opencode/opencode.json）可关闭自动更新（本机即关闭）
数据/状态在 ~/.local/share/opencode（db/快照/日志），更新不动用户数据

配置文件与凭据

两个核心文件职责分离：

文件	角色	位置
`opencode.json`	配置：声明 provider、endpoint、模型清单、默认行为	XDG 配置目录 `~/.config/opencode/`
`auth.json`	凭据库：只存 API Key / OAuth Token，`opencode auth login` 写入	XDG 数据目录 `~/.local/share/opencode/`，权限 0600

opencode.json 回答「连哪里、有哪些模型」，auth.json 回答「用哪个密钥/身份」。

opencode.json 示例

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false,
  "provider": {
    "my-gateway": {
      "npm": "@ai-sdk/openai-compatible",  // AI SDK 适配器
      "name": "My Gateway",                 // /models 展示名
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "sk-****"                 // 可内联，也可只放 auth.json
      },
      "models": {
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  }
}

provider.<id>.npm：AI SDK 适配器。OpenAI 兼容网关用 @ai-sdk/openai-compatible；原生 OpenAI 协议用 @ai-sdk/openai。
options.baseURL：网关地址；options.apiKey 支持 {env:VAR}（环境变量）或 {file:path}（文件内容）占位，避免明文入库。
models：模型清单/别名，决定 /models 可见项。
其他可选顶层项：model（默认模型）、agent、mcp、permission、theme。

auth.json 示例

API Key 形态：

{
  "my-gateway": {
    "type": "api",
    "key": "sk-****"
  }
}

OAuth 形态（浏览器登录写入）：

{
  "github-copilot": {
    "type": "oauth",
    "refresh": "...",
    "access": "...",
    "expires": 1799999999999
  }
}

顶层 key 必须与 opencode.json 的 provider ID 对齐。
type: api 用 key；type: oauth 用 access/refresh/expires。
运行时数据，含明文密钥，不应纳入 Git。
管理命令：opencode auth list / opencode auth login / opencode auth logout。

凭据解析优先级

按 v1.18.21 二进制实测的 provider 合并顺序（后者覆盖前者）：

provider 声明的环境变量（provider.<id>.env，如 OPENAI_API_KEY）
auth.json 中对应 provider 的凭据
opencode.json 的 provider.<id>.options.apiKey

即 opencode.json 显式 apiKey 优先级最高，其次 auth.json，最后环境变量。官方也说明配置文件选项优先于环境变量（如 Bedrock）。

因此推荐「配置写 endpoint + 模型，密钥交给 auth.json 或环境变量」；全写进 opencode.json 虽然省事，但文件本身即明文密钥，易误提交。反过来若同时存在，配置里的 key 会盖掉 auth.json，排查认证失败时要先确认没有旧 key 残留。

本机现状：auth.json 第 8 行缺少结尾引号导致 JSON 解析失败，opencode auth list 显示 0 credentials；当前 provider 仍可用是因为 opencode.json 已内联 apiKey。opencode.json.bak 为无内联密钥的旧版，说明密钥后来被搬进了配置。

分发

安装脚本（curl）为主，各包管理器全覆盖；单二进制形态，版本号 semver（本机 1.18.21）

对天喜的启发

「升级命令感知安装方式」值得借鉴：用户怎么装的就怎么升，避免渠道错配导致的双安装/更新失效。详见 ai-devtool-update-strategies。

关系

同类：claude-code、antigravity
调研汇总：ai-devtool-update-strategies

zhaoweiguo 的知识库

目录