★ FEATURED ARTICLE 1. 为什么要在 GitLab 的 Issue 和合并请求里塞进 OpenCode很多团队已经把代码托管迁到 GitLab日常协作几乎都发生在 Issue 评论区和合并请求Merge Request简称 MR的讨论串里。问题也正好出在这里一个 Issue 描述写得含糊得有人先去读代码、翻日志、把上下文拼起来一个 MR 改动涉及五六个文件审查的人要来回跳转才能看懂意图。这些活儿本身不难但特别占时间而且重复度极高。OpenCode 是一个跑在终端里的 AI 编码助手它能读你仓库里的文件、执行命令、按提示词改代码最后把改动整理成提交。把它接到 GitLab 上本质上是让它在 GitLab Runner 里跑起来然后通过 Issue 评论或 MR 描述去触发它。触发之后它读上下文、干活、回帖或者直接开分支提 MR。对团队来说这相当于在评论区多了一个随时待命的同事。适合谁用三类人最划算。第一类是维护开源项目或者内部平台的团队Issue 量大、重复问题多想让 AI 先做一轮分诊和解释。第二类是中小研发团队没有专职的代码审查人力希望 MR 提交后能自动过一遍基础检查。第三类是已经在用 TaoToken 统一 Key 的团队因为 OpenCode 需要一个模型提供方的 API 通道而 TaoToken 的 endpoint 和 Key 可以直接复用不用再单独申请一套凭证。这里要区分两种集成路径。一种是走 GitLab CI/CD 组件把 OpenCode 当成管道里的一个 job 来跑适合自定义程度要求高的场景比如你想控制它用哪个配置目录、跑什么命令、输出到哪里。另一种是走 GitLab Duo 的 CLI agent 集成在评论里 一下触发词OpenCode 就在后台的管道里执行适合想要“评论区喊一声就干活”的轻量用法。两条路最后都是跑在 GitLab 自己的 Runner 上权限边界清晰代码不出自己的基础设施。我试过把这两种方式都搭了一遍踩的坑主要集中在认证配置和触发词识别上。下面按可复制的步骤来写重点放在 TaoToken 的 endpoint 怎么填、auth.json 怎么写、以及怎么验证请求确实走了统一通道。2. TaoToken 前置准备endpoint、Key 与 auth.json 的对应关系在把 OpenCode 塞进 GitLab 之前得先把模型通道准备好。OpenCode 本身不绑定某一家模型它通过配置文件读取 API 地址和密钥。TaoToken 提供的是统一的 API 通道你拿到一个 Base URL 和一个 Key就能在 OpenCode 里指向它。先明确三个东西的对应关系这是后面所有配置的基础配置项在 TaoToken 里的位置在 OpenCode 里的字段Base URLAPI 地址形如 https://taotoken.net/apiprovider 的 baseURLAPI Key控制台生成的密钥auth.json 里的 apiKeyModel ID模型列表里的标识配置里的 model 字段Base URL 用https://taotoken.net/api注意不要在后面多加斜杠或者拼错路径。Key 在控制台的 API Keys 页面生成生成后只显示一次复制下来存好。Model ID 根据你实际要用的模型填比如做代码解释和审查选一个上下文窗口够大的就行。OpenCode 读取认证信息的方式是读一个 auth.json 文件。这个文件的结构大致是这样你可以直接复制改{ taotoken: { type: api, apiKey: sk-你的TaoToken密钥, baseURL: https://taotoken.net/api } }注意type字段写apiapiKey填你生成的 KeybaseURL就是上面那个地址。这个文件在本地跑的时候放在 OpenCode 的配置目录里在 GitLab CI 里则要转成环境变量后面会讲怎么处理。如果你用的是 Coding Plan 这类长期编码场景Key 的权限和额度策略可能不一样建议在控制台里确认一下这个 Key 能访问哪些模型。生成 Key 的入口在 API Keys 页面接入文档里有更细的字段说明遇到字段对不上的时候去翻一下文档比猜要快。还有一个容易忽略的点OpenCode 的 provider 名字要和 auth.json 里的顶层 key 对应上。上面我写的是taotoken那在 OpenCode 的配置文件里引用 provider 时也要写taotoken。名字本身可以自定义但两处必须一致否则会出现找不到凭证的报错。准备好这三样之后本地可以先跑一次验证确认 Key 和地址是通的再去动 GitLab 的配置。本地验证的命令很简单装好 OpenCode 后直接跑一个最小请求看它能不能返回内容。这一步过了后面 CI 里的问题基本就只剩环境变量和触发逻辑了。3. 可复制配置.gitlab-ci.yml 与 auth.json 的完整片段这一节给两份可以直接抄的配置。第一份是走 CI 组件的方式第二份是走 GitLab Duo 触发的方式。两份都围绕同一个 auth.json 结构区别在于触发入口和变量传递方式。先说 CI 组件方式。社区里有一个现成的组件nagyv/gitlab-opencode它会在管道里自动把 OpenCode 环境搭好你只需要提供认证 JSON 和提示词。第一步是把 auth.json 的内容存成 GitLab CI 变量。路径是项目设置 → CI/CD → 变量Variables新建一个变量类型选 “File”勾上 “Masked and hidden”。变量名比如叫OPENCODE_AUTH_JSON值就是上面那段 JSON 的完整内容。然后在项目根目录的.gitlab-ci.yml里加上这段include: - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode2 inputs: config_dir: ${CI_PROJECT_DIR}/opencode-config auth_json: $OPENCODE_AUTH_JSON command: optional-custom-command message: 请解释这个 Issue 的核心问题并给出可能的修复方向这里几个 input 的含义要清楚。config_dir指向你仓库里存放 OpenCode 配置的目录不同 job 可以用不同目录来启用或禁用不同功能。auth_json填的是存放认证 JSON 的那个变量名注意这里写的是变量名本身不是 JSON 内容。command是可选的自定义命令message就是给 AI 的提示词。如果你想让不同任务用不同配置可以在仓库里建多个目录比如opencode-config/triage和opencode-config/review然后在不同的 job 里分别指向它们。这样分诊用的提示词和审查用的提示词就不会互相干扰。再说 GitLab Duo 触发方式。这种方式下OpenCode 跑在 CI/CD 管道里你在 Issue 或 MR 评论里 触发词它就会执行。配置步骤大致是先把 CI/CD 跑通拿到模型 API 密钥这里就是 TaoToken 的 Key创建一个服务账号配置好 CI/CD 变量最后写一个流程配置文件。流程配置文件是这种方式的核心它决定了触发词是什么、触发后执行什么动作。一个简化的配置结构如下name: opencode-agent trigger: opencode actions: explain: prompt: 阅读当前 Issue 的全部内容用简洁的语言解释问题所在 fix: prompt: 分析问题并修复创建新分支提交合并请求 review: prompt: 审查当前合并请求的改动指出潜在问题和改进点触发词不一定是opencode你可以改成团队习惯的词。三个动作分别对应解释 Issue、修复 Issue、审查 MR。实际配置里还要指定用哪个 provider 和 model这部分和 auth.json 里的 provider 名字对应。无论走哪条路auth.json 的结构都是一样的Base URL 都是https://taotoken.net/api。区别只是 CI 组件方式把 JSON 存成 File 类型变量Duo 方式可能通过服务账号的凭证注入。两种方式都建议把 Key 设为 Masked避免在日志里泄露。4. 验证请求在 Issue 评论和 MR 描述里触发并确认返回配置写完之后最关键的一步是验证请求真的发出去了而且走的是 TaoToken 的统一通道。这一步不能只看“有没有回复”还要确认回复内容符合预期、没有报认证错误。先验证 Issue 评论触发。打开一个测试用的 Issue在评论区写opencode explain this issue如果触发词配置的是opencode管道会被拉起OpenCode 在 Runner 里读这个 Issue 的内容然后回一条评论解释问题。你看到回复之后去管道的 job 日志里翻一下确认请求的 endpoint 是https://taotoken.net/api而不是别的地址。日志里通常会打印 provider 和 baseURL这是最直接的证据。再验证 MR 描述触发。新建一个合并请求在描述里写opencode review this merge requestOpenCode 会读取这个 MR 的 diff然后给出审查意见。审查意见一般会以评论形式出现指出改动里可能的问题。同样去日志里确认请求地址。修复类动作的验证稍微复杂一点因为涉及创建分支和提交 MR。在 Issue 里写opencode fix this它会切一个新分支改代码然后提一个 MR 出来。验证的时候重点看两件事一是新分支和 MR 确实被创建了二是 MR 里的改动和 Issue 描述的问题对得上。如果 MR 创建了但改动是空的多半是提示词不够具体或者 OpenCode 没读到相关文件。验证成功的标志有三个评论或 MR 里有 AI 生成的回复内容管道 job 状态是 passed日志里的请求地址是 TaoToken 的 endpoint。三个都满足说明统一通道是通的。如果回复内容出现了但明显答非所问先别急着改配置去看日志里实际发给模型的提示词是什么。有时候是触发词后面的文本没被正确捕获导致提示词是空的模型只能瞎猜。5. 常见报错排查401、local proxy failed 与 reading choices配置过程中最容易撞上的几类报错这里逐个拆开说。第一类是 401 认证失败。日志里出现401 Unauthorized或者invalid api key基本就是 auth.json 里的 Key 不对或者环境变量没传进去。排查顺序先确认 GitLab CI 变量里OPENCODE_AUTH_JSON的值是完整的 JSON不是只有 Key 字符串再确认变量类型选的是 File不是 Variable最后确认 auth.json 里的apiKey字段名没写错。如果 Key 是从控制台复制的注意有没有多复制了空格或者换行。第二类是local proxy failed或者连接超时。这类报错通常指向 Base URL 写错或者 Runner 的网络策略不允许访问外部地址。先检查 auth.json 里的baseURL是不是https://taotoken.net/api有没有多写路径或者少写协议头。如果地址没问题去看 Runner 的网络配置确认它能出网。有些自建 Runner 默认只允许访问内网需要单独放行。第三类是reading choices相关的报错比如error reading choices: unexpected end of JSON input。这通常意味着模型返回的内容不是预期的 JSON 结构可能是请求被中途截断或者 provider 配置和实际返回格式不匹配。排查时先确认 model 字段填的是 TaoToken 支持的模型 ID再确认 provider 类型写的是api。如果模型 ID 写错有些通道会返回一个非标准响应解析时就报这个错。第四类是触发词没反应。评论发出去了但管道没被拉起。先确认触发词和流程配置文件里写的一致大小写敏感。再确认服务账号有权限触发管道。如果是 Duo 方式还要确认 CLI agent 功能在项目里是开启状态。第五类是 MR 创建了但内容是空的。这多半是提示词太模糊OpenCode 不知道要改哪个文件。把提示词写具体一点比如指明文件路径或者函数名命中率会高很多。排查的时候有一个通用技巧把 CI job 的日志级别调高让 OpenCode 打印出完整的请求和响应。这样能直接看到发出去的 endpoint、model 和提示词比猜要快得多。6. 把统一 Key 用顺之后的日常用法与 CTA配置跑通之后日常用法其实很轻。Issue 分诊的时候让 OpenCode 先读一遍把问题归类、指出可能的原因人工再接手就快很多。MR 审查的时候让它先过一遍基础检查比如有没有明显的逻辑漏洞、有没有漏掉边界条件人工审查聚焦在业务逻辑上。小 Bug 修复可以直接让它开分支提 MR人工只需要 review 那个 MR 就行。几个实用技巧。触发词可以按团队习惯改不用死守opencode改成ai或者helper都行只要流程配置文件里同步改。提示词尽量具体带上文件路径或者函数名比泛泛地说“修一下”有效得多。不同任务用不同的 config_dir把分诊、审查、修复的提示词分开管理避免互相污染。Key 的额度要留意审查大 MR 的时候上下文消耗会比较大可以在控制台里看用量。如果你还没配好 Key去 API Keys 页面生成一个接入文档里有字段说明和示例。想先试试模型对话的效果可以直接在模型对话里发一条请求确认通道是通的。长期做编码和 Agent 场景的话Coding Plan 的额度策略更适合高频调用。整套流程跑下来最花时间的其实是第一次把 auth.json 和环境变量对齐。对齐之后后面加新的触发动作就是改改流程配置文件的事。
阅读完成 · 觉得有帮助？
