1. 为什么要把 OpenCode 塞进终端流水线OpenCode 是一个跑在终端里的 AI 编码代理它能读文件、改代码、执行命令而不只是吐一段建议。很多人第一次用它是在本地敲opencode 帮我重构这个函数看着它把改动落到磁盘上觉得挺爽。但爽完之后问题就来了每次都要手动开终端、手动贴提示词、手动确认权限这套动作在个人项目里还行一旦放到团队协作或者每天要跑几十次的场景里就变成了纯体力活。我真正开始重视 CLI 自动化是因为一个很具体的痛点我们有个仓库每周要合并十几个 PR人工 review 经常漏掉类型定义和边界条件。我想让 OpenCode 在 PR 提交时自动跑一遍代码审查把问题以评论形式贴回去。这个需求逼着我把 OpenCode 从「交互式玩具」改造成「非交互式流水线组件」。这篇要解决的就是这件事怎么用 OpenCode 的 CLI 能力把本地脚本、CI/CD 流水线、远程协作三个场景串起来。核心检索词是 OpenCode CLI 自动化与 CI/CD 集成适合已经用过 OpenCode 基础功能、想把它接进工程流程的开发者。读完之后你应该能照着配置复现一次完整的自动化流程本地脚本调用、GitHub Actions 里跑非交互任务、远程机器上共享同一套模型通道。先说清楚一个前提OpenCode 本身不绑定某一家模型服务它通过 provider 配置去调用后端。远程协作和 CI 场景里最麻烦的往往不是 OpenCode 的用法而是「每台机器、每个流水线都要配一遍 Key 和地址」。所以我会用统一的 API 通道来收口这件事让本地、CI、远程三处的鉴权配置保持一致。这样你改一次配置三处都能用。下面按「本地 CLI 自动化 → 统一 Key 通道 → CI/CD 集成 → 远程协作 → 报错排查」的顺序展开每一步都给可复制的片段。2. 本地 CLI 自动化非交互模式与脚本串联OpenCode 的非交互模式是自动化的地基。交互模式下它会等你确认脚本里没人点确认所以必须走非交互路径。基本形态是直接把提示词作为参数传进去opencode 请重构这个函数使其更加可读 --model claude-sonnet这条命令跑完就退出不会停在交互界面。但实际脚本里更常见的是从标准输入喂内容比如把当前改动的文件管道进去cat src/utils/parser.ts | opencode 请为这个文件补充类型注释不要改变逻辑 --model claude-sonnet这里有个细节值得说管道输入的内容会作为上下文提示词里的「这个文件」指的就是管道进来的内容。我试过把整个目录cat进去结果上下文太长反而让模型抓不住重点所以建议一次只喂一个文件或一段 diff。真正让脚本化变得可控的是环境变量。OpenCode 支持用环境变量覆盖配置文件里的对应项这在 CI 和远程场景里特别关键export OPENCODE_API_KEYsk-xxx export OPENCODE_CONFIG/path/to/config.json export OPENCODE_CONFIG_CONTENT{model:claude-sonnet} export OPENCODE_DISABLE_CLAUDE_CODE1 export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT1 export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS1OPENCODE_CONFIG指向配置文件路径OPENCODE_CONFIG_CONTENT则直接内联一段 JSON 配置适合在流水线里临时注入。后面三个DISABLE_CLAUDE_CODE*变量用于关掉 Claude Code 相关的兼容行为在纯自动化场景里能减少不必要的交互提示。把这些拼起来一个本地自动化脚本大概长这样#!/usr/bin/env bash set -euo pipefail export OPENCODE_API_KEY${TAOTOKEN_API_KEY} export OPENCODE_CONFIG_CONTENT{model:anthropic/claude-sonnet-4-5} for f in $(git diff --name-only HEAD~1 HEAD | grep \.ts$); do echo 审查文件: $f cat $f | opencode --headless 请审查这个文件的代码质量指出潜在 bug 和类型问题 \ --model claude-sonnet done--headless明确告诉 OpenCode 不要进入交互界面适合在脚本和流水线里用。set -euo pipefail保证任何一步失败就中断避免半途出错还继续跑。这里要提醒一个坑非交互模式下权限控制很重要。默认配置里edit可能是ask脚本里没人应答就会卡住。所以自动化场景要把权限显式设成允许或拒绝这个在下一节的配置片段里给。3. 统一 Key 通道一份配置打通本地与流水线本地、CI、远程三处如果各配各的 Key维护成本会爆炸。我的做法是用统一的 API 通道收口所有环境都指向同一个 Base URL 和同一套 Key 管理方式。这样本地调试通过的配置直接复制到流水线就能用。OpenCode 的配置文件是opencode.json放在项目根目录或用户配置目录。下面是一份可以直接复制的全量配置注意provider段里的baseURL和apiKey写法{ schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-5, autoupdate: true, server: { port: 4096, host: 0.0.0.0 }, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 } } } }, permission: { read: allow, edit: allow, bash: ask } }几个关键点。baseURL填https://taotoken.net/api注意 API 地址不带查询参数。apiKey用{env:TAOTOKEN_API_KEY}的语法从环境变量读取这样配置文件可以进版本库Key 本身留在环境里。permission段里read和edit设成allow是为了非交互模式能顺利改文件bash保留ask是安全考虑——脚本里如果需要执行命令最好单独评估。如果你在 CI 里不想挂载配置文件可以用OPENCODE_CONFIG_CONTENT内联同样的内容export OPENCODE_CONFIG_CONTENT{ model: taotoken/claude-sonnet-4-5, provider: { taotoken: { npm: ai-sdk/openai-compatible, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} } } }, permission: {read: allow, edit: allow} }这样流水线里只需要注入一个TAOTOKEN_API_KEY环境变量其余配置全部内联不依赖仓库里的文件。本地开发时用opencode.jsonCI 里用内联内容两边指向同一个 Base URL模型行为一致。关于 Key 的获取可以在控制台里创建地址是https://taotoken.net/console创建后把 Key 存到本地环境变量或 CI 的 secrets 里。接入文档在https://taotoken.net/doc里面有各语言 SDK 的调用示例配 OpenCode 时主要看 provider 那部分的字段说明。这里有个容易踩的坑baseURL结尾不要多加/v1之类的路径OpenCode 的 openai-compatible provider 会自己拼接。我一开始多写了/v1结果请求 404排查了半天。4. CI/CD 集成在 GitHub Actions 里跑非交互任务把 OpenCode 接进 CI 的核心诉求是「PR 提交时自动审查」。GitHub Actions 的配置大概是这样name: OpenCode Review on: pull_request: types: [opened, synchronize] jobs: code-review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install OpenCode run: npm install -g opencode - name: Run OpenCode review env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} OPENCODE_CONFIG_CONTENT: | { model: taotoken/claude-sonnet-4-5, provider: { taotoken: { npm: ai-sdk/openai-compatible, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} } } }, permission: {read: allow, edit: allow} } run: | git diff origin/${{ github.base_ref }}...HEAD /tmp/pr.diff cat /tmp/pr.diff | opencode --headless \ 请审查这个 PR 的代码质量重点关注类型安全、边界条件和潜在 bug \ --model taotoken/claude-sonnet-4-5几个设计点。fetch-depth: 0是为了能拿到完整的 git 历史否则git diff对比基线会失败。OPENCODE_CONFIG_CONTENT用 YAML 的多行字符串内联避免在 CI 里再维护一个配置文件。TAOTOKEN_API_KEY从 GitHub secrets 读取不落盘。git diff origin/${{ github.base_ref }}...HEAD拿到的是 PR 相对目标分支的完整改动喂给 OpenCode 做审查。--headless保证不进入交互--model显式指定模型避免依赖默认值。跑通之后你会在 Actions 日志里看到 OpenCode 输出的审查意见。如果想让它把意见贴回 PR 评论可以再加一步用ghCLI 提交评论这里不展开核心的审查逻辑已经跑通了。CI 场景里最常见的失败是 Key 没配好导致 401。排查方法是在流水线里加一步echo ${TAOTOKEN_API_KEY:0:8}确认 Key 被正确注入只打印前 8 位避免泄露。如果这一步输出为空说明 secrets 没传到 env检查env段的变量名是否和配置文件里的{env:...}一致。另一个坑是 OpenCode 版本。CI 里每次npm install -g opencode拉的是最新版如果某次更新改了 CLI 参数流水线可能突然挂掉。稳妥做法是锁定版本比如npm install -g opencode0.5.x等验证过再升级。5. 远程协作共享模型通道与鉴权验证远程协作的场景是这样的团队里有人用大内存机器跑 OpenCode 实例其他人从弱机连过去用它的算力或者多台机器共享同一套模型配置避免每人各配一份 Key。OpenCode 的远程模式支持连接到其他机器上的实例opencode remote --host example.com --port 4096--host和--port对应配置文件里server段的host和port。服务端启动时监听0.0.0.0:4096客户端连过去就能复用服务端的模型配置和权限设置。远程模式的价值在于配置收口。服务端配好opencode.json指向统一的 API 通道客户端不需要本地再配 Key。这样团队里新成员加入只要连上远程实例就能用不用每人去申请 Key、配环境变量。验证远程连接是否正常可以分三步。第一步在服务端确认实例在监听ss -tlnp | grep 4096应该看到0.0.0.0:4096处于 LISTEN 状态。第二步从客户端发一个简单请求opencode remote --host server-ip --port 4096 请回复 ok如果返回ok说明连接和鉴权都通了。第三步验证模型调用走的是服务端的通道可以在服务端日志里看到对应的请求记录。远程场景的鉴权要特别注意。服务端监听0.0.0.0意味着同网络内都能访问生产环境建议加一层网络隔离或反向代理做访问控制。API Key 只存在服务端客户端不接触 Key这是远程模式相对本地配置的优势。如果远程连接报local proxy failed通常是网络不通或端口没开。先在客户端telnet server-ip 4096确认端口可达再检查服务端防火墙规则。如果报 401说明服务端的 Key 配置有问题回到服务端检查TAOTOKEN_API_KEY环境变量是否设置、baseURL是否正确。远程协作还有一个实用技巧把AGENTS.md放在项目根目录服务端和客户端都能读到这样无论谁连过来OpenCode 都能理解项目结构。AGENTS.md里写清楚项目用的框架、目录约定、代码风格能显著提升审查和重构的准确率。6. 常见报错排查401、proxy failed、choices 解析失败自动化跑起来之后报错基本集中在几类。下面按真实遇到的错误对照排查。401 Unauthorized 是最常见的。表现是 OpenCode 返回鉴权失败日志里能看到 401 状态码。原因通常是 Key 没注入或注入错误。排查顺序先确认环境变量存在echo ${TAOTOKEN_API_KEY:0:8}再确认配置文件里的{env:TAOTOKEN_API_KEY}拼写一致最后确认baseURL是https://taotoken.net/api没有多余路径。如果 Key 是从控制台新建的确认它没有被删除或过期。local proxy failed一般出现在远程模式。表现是客户端连不上服务端。排查服务端ss -tlnp | grep 4096确认监听客户端telnet确认端口可达检查服务端server.host是否设成了0.0.0.0而不是127.0.0.1。如果服务端只监听127.0.0.1外部就连不上。reading choices相关的解析错误通常是模型返回格式和 OpenCode 预期不一致。表现是日志里出现解析choices字段失败。原因可能是baseURL指向了不兼容 OpenAI 格式的端点或者模型 ID 写错了。确认provider段用的是ai-sdk/openai-compatiblebaseURL指向兼容端点模型 ID 和 provider 里定义的models键一致。OAuth 相关报错在 CI 里比较少见但如果你的配置里混入了需要 OAuth 的 provider非交互模式下会卡住。解决办法是在自动化配置里只保留 API Key 鉴权的 provider把 OAuth 相关的 provider 移除。OPENCODE_DISABLE_CLAUDE_CODE系列变量也能减少这类兼容行为。还有一个隐蔽的坑CI 里git diff为空导致 OpenCode 收到空输入。表现是 OpenCode 返回「没有内容可审查」或者直接报错。排查方法是先在流水线里wc -l /tmp/pr.diff确认 diff 非空。如果为空检查fetch-depth和github.base_ref是否正确。排查这类问题的通用思路是先确认网络和鉴权401、proxy failed再确认输入内容空 diff最后确认模型返回格式choices 解析。按这个顺序走大部分报错都能定位到具体环节。7. 把自动化流程固化下来走到这里你应该已经跑通了一条完整的链路本地脚本用非交互模式调用 OpenCodeCI 流水线在 PR 提交时自动审查远程实例共享同一套模型通道。这三处的配置都指向同一个 Base URLKey 通过环境变量注入配置文件可以进版本库。接下来可以做的固化动作有几个。把本地脚本放进scripts/目录加个make review的入口团队成员直接调用。CI 配置锁定 OpenCode 版本避免自动升级带来的意外。远程服务端用 systemd 或容器管理保证重启后自动拉起。如果想让审查结果更贴合项目在仓库根目录放一份AGENTS.md写清楚技术栈和代码规范。OpenCode 在本地、CI、远程三处都会读它相当于给所有自动化任务统一了上下文。需要长期跑编码任务或者 Agent 场景的话可以了解下 Coding Plan地址是https://taotoken.net/coding-plan适合把这类自动化流程做成常态化的团队能力。模型调用验证可以用模型对话页面快速试https://taotoken.net/model-chat。接入细节和字段说明在文档里https://taotoken.net/doc。Key 的创建和管理在控制台https://taotoken.net/consoleAPI Keys 页面是https://taotoken.net/api-keys。最后留一个我踩过的坑CI 里第一次跑通不代表一直能跑通。模型服务端的限流、网络抖动、OpenCode 版本更新都可能让流水线突然红。建议在流水线里加失败重试和超时控制别让一次偶发失败阻塞整个 PR 流程。自动化是为了省事不是为了制造新的焦虑源。