OpenCode GitHub 集成实战教程：AI 自动化 Issue 与 PR 处理

📚 分类: 开发工具 / CI/CD 集成 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: GitHub 账号、一个拥有管理员权限的仓库（公开或私有均可）

你将学到什么

完成本教程后，你将能够：

[ ] 在 GitHub 仓库中安装 OpenCode GitHub App
[ ] 配置自动工作流，让 OpenCode 响应 Issue 和 PR 评论
[ ] 使用 /opencode 命令让 AI 自动处理 Issue 和 PR 审查
[ ] 设置定时任务，让 OpenCode 按计划执行自动化任务
[ ] 理解 OpenCode 的权限模型和安全机制

最终效果

你将拥有一个由 AI 驱动的 GitHub 自动化助手。在 Issue 或 PR 中评论 /opencode explain this issue，OpenCode 会自动分析并回复；评论 /opencode fix this，它会创建修复分支并提交 PR。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求	验证方法
GitHub 账号	已注册	登录 github.com
目标仓库	拥有管理员权限	能进入仓库 Settings
可用的 API 密钥	例如 Anthropic API Key	已从提供商获取

1. 准备 API 密钥（以 Anthropic 为例）

bash

# 访问 https://console.anthropic.com/ 创建 API Key
# 复制生成的密钥字符串，形如：sk-ant-xxxxxxxxxxxxxxxx

✅ 验证：你手中应有一个以 sk-ant- 开头的密钥字符串。

第 1 步：安装 OpenCode GitHub App

🎯 目标：将 OpenCode 应用安装到你的 GitHub 仓库中，这是最快捷的方式。

📝 操作：

打开浏览器，访问 https://github.com/apps/opencode-agent
点击绿色的 "Install" 按钮
选择要安装的仓库：
- 可以选择 "All repositories"（所有仓库）
- 或 "Only select repositories"（仅指定仓库）
点击 "Install" 确认

💡 提示：如果你只想在特定仓库试用，建议选择"Only select repositories"。

✅ 验证：进入目标仓库，点击 Settings → GitHub Apps（左侧边栏），你应该能看到 opencode-agent 已出现在已安装的应用列表中。

🤔 为什么要这样做？ OpenCode GitHub App 会提供一个安装访问令牌（Installation Access Token），让 OpenCode 能代表你执行创建评论、提交代码、创建 PR 等操作，而无需手动配置 Token。

第 2 步：创建工作流文件

🎯 目标：在仓库中添加 GitHub Actions 工作流，让 OpenCode 能在收到评论时自动响应。

📝 操作：

在你的仓库中，创建目录 .github/workflows/
在该目录下创建文件 opencode.yml
将以下内容复制到文件中：

yaml

# .github/workflows/opencode.yml
name: opencode

# 触发条件：当 Issue 或 PR 上有新评论时
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  opencode:
    # 仅当评论中包含 /oc 或 /opencode 时执行
    if: |
      contains(github.event.comment.body, '/oc') ||
      contains(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: 检出仓库代码
        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false

      - name: 运行 OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          # share: true          # 可选：是否共享会话（公开仓库默认为 true）
          # github_token: xxxx   # 可选：使用自定义 Token 替换默认的 App Token

保存文件并提交到仓库的默认分支（通常是 main 或 master）

bash

$ git add .github/workflows/opencode.yml
$ git commit -m "添加 OpenCode 工作流"
$ git push origin main

✅ 验证：提交后，进入仓库的 Actions 选项卡，你应该能看到名为 opencode 的工作流已列出。

⚠️ 常见错误：如果工作流文件格式错误，GitHub Actions 会显示语法错误。检查 YAML 缩进是否正确（每级缩进 2 个空格）。

第 3 步：将 API 密钥存储为 Secrets

🎯 目标：安全地存储 API 密钥，让工作流能访问它。

📝 操作：

进入你的 GitHub 仓库页面
点击 Settings（设置）标签
在左侧边栏找到 Secrets and variables，展开后点击 Actions
点击绿色的 "New repository secret" 按钮
在 Name 字段输入：ANTHROPIC_API_KEY
在 Secret 字段粘贴你之前复制的 API 密钥
点击 "Add secret" 保存

✅ 验证： Secret 添加后，你会看到 ANTHROPIC_API_KEY 出现在 Secrets 列表中。注意：添加后密钥内容不可再查看，只能删除或替换。

💡 提示：如果你使用其他模型提供商（如 OpenAI），只需将 ANTHROPIC_API_KEY 替换为对应的密钥名称（如 OPENAI_API_KEY），并在工作流文件中同步修改 env 部分。

第 4 步：测试 OpenCode 响应

🎯 目标：创建一个测试 Issue，验证 OpenCode 能正常响应。

📝 操作：

进入你的仓库，点击 Issues 选项卡
点击 "New issue" 按钮
标题输入：测试：OpenCode 集成
正文输入任意内容（例如："这是一个测试 Issue"）
点击 "Submit new issue"
在刚创建的 Issue 下方评论区，输入：

/opencode explain this issue

点击 "Comment" 提交评论

✅ 验证：

几秒内，你应该会看到仓库的 Actions 选项卡中出现一个正在运行的工作流
工作流运行完成后，OpenCode 会在 Issue 下方回复一条评论，对 Issue 进行分析和解释

💡 提示：如果工作流未触发，检查：

工作流文件是否在默认分支上
评论中是否包含了 /opencode 或 /oc（区分大小写）
仓库的 Actions 功能是否启用

⚠️ 常见错误：如果看到报错 Error: ANTHROPIC_API_KEY not found，说明 Secret 未正确设置。请回到第 3 步检查。

第 5 步：尝试更多命令

🎯 目标：体验 OpenCode 的更多功能。

📝 操作：

在同一个测试 Issue 下，尝试以下评论：

命令 1：请求修复

/opencode fix this

🔄 OpenCode 会：

创建一个新分支（如 opencode/fix-issue-1）
实现代码变更
提交一个包含所有修改的 Pull Request

命令 2：审查特定代码行（需要在 PR 的 Files 选项卡中操作）

创建一个新的 Pull Request
在 PR 的 Files changed 选项卡中，点击某行代码左侧的 + 号
在评论框中输入：

/oc add error handling here

点击 "Start a review" 或 "Add single comment"

✅ 验证：

对于 fix 命令，你会看到一个由 OpenCode 自动创建的新 PR
对于代码行审查，OpenCode 会在该行下方回复建议的代码修改

🤔 为什么要这样做？/opencode fix this 让 AI 自动完成修复工作，省去手动查找和修改代码的时间。而代码行级评论则允许你精确指定需要修改的位置。

进阶技巧（可选）

掌握基础后，你可以尝试配置更复杂的工作流：

1. 定时任务：每周自动审查代码中的 TODO

yaml

# .github/workflows/opencode-scheduled.yml
name: 定时 OpenCode 任务

on:
  schedule:
    - cron: "0 9 * * 1"  # 每周一 UTC 时间 9:00

jobs:
  opencode:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
      - uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            审查代码库中所有的 TODO 注释并创建一个摘要。
            如果发现值得处理的问题，创建一个 Issue 来跟踪它们。

2. 自动 PR 审查（无需手动触发）

yaml

# .github/workflows/opencode-review.yml
name: opencode-review

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: read
      issues: read
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
      - uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          use_github_token: true
          prompt: |
            审查这个 Pull Request：
            - 检查代码质量问题
            - 寻找潜在的错误
            - 提出改进建议

3. Issue 自动分类（过滤垃圾信息）

yaml

# .github/workflows/opencode-triage.yml
name: Issue 分类

on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: 检查账号年龄
        id: check
        uses: actions/github-script@v7
        with:
          script: |
            const user = await github.rest.users.getByUsername({
              username: context.payload.issue.user.login
            });
            const created = new Date(user.data.created_at);
            const days = (Date.now() - created) / (1000 * 60 * 60 * 24);
            return days >= 30;
          result-encoding: string

      - uses: actions/checkout@v6
        if: steps.check.outputs.result == 'true'
        with:
          persist-credentials: false

      - uses: anomalyco/opencode/github@latest
        if: steps.check.outputs.result == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            审查这个 Issue。如果有明确的修复方法或相关的文档：
            - 提供文档链接
            - 为代码示例添加错误处理指导
            否则，不要评论。

常见问题 (FAQ)

Q1: 工作流没有触发，怎么办？A: 按以下顺序排查：

确认 .github/workflows/opencode.yml 文件存在于默认分支
确认评论中包含 /opencode 或 /oc（注意是正斜杠 /，不是反斜杠 \）
确认仓库的 Actions 功能未禁用（Settings → Actions → Allow all actions）
查看 Actions 运行日志，寻找具体错误信息

Q2: 报错 ANTHROPIC_API_KEY not found 怎么解决？A: 说明 Secret 未正确配置。请回到第 3 步，确认：

Secret 名称必须为 ANTHROPIC_API_KEY（区分大小写）
密钥值已正确粘贴（不要有多余空格）
Secret 添加到了正确的仓库

Q3: 如何让 OpenCode 使用我自己的 GitHub Token 而不是 App Token？A: 在工作流中添加 use_github_token: true 配置，并授予相应权限：

yaml

permissions:
  contents: write
  pull-requests: write
  issues: write

或者使用个人访问令牌（PAT）：

yaml

with:
  github_token: ${{ secrets.MY_PAT }}

Q4: 定时任务工作流为什么没有创建 PR？A: 定时事件没有用户上下文，需要显式授予 contents: write 和 pull-requests: write 权限。同时，prompt 参数是必填项，因为定时任务没有评论可提取指令。

Q5: 如何修改使用的 AI 模型？A: 修改工作流中的 model 参数：

yaml

with:
  model: openai/gpt-4o           # 使用 OpenAI
  # 或
  model: anthropic/claude-sonnet-4-20250514  # 使用 Anthropic

同时确保对应的 API 密钥已添加到 Secrets 中。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

安装 OpenCode App：通过 GitHub App 商店快速安装，获得自动的访问令牌
配置工作流：创建 .github/workflows/opencode.yml 文件，定义触发条件和执行逻辑
安全存储密钥：使用 GitHub Secrets 管理 API 密钥，避免硬编码
使用命令：/opencode explain 分析 Issue，/opencode fix 自动修复，/oc 快捷触发
进阶配置：定时任务、自动 PR 审查、Issue 分类等高级用法

OpenCode GitHub 集成实战教程：AI 自动化 Issue 与 PR 处理 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 准备 API 密钥（以 Anthropic 为例） ​

第 1 步：安装 OpenCode GitHub App ​

第 2 步：创建工作流文件 ​

第 3 步：将 API 密钥存储为 Secrets ​

第 4 步：测试 OpenCode 响应 ​

第 5 步：尝试更多命令 ​

进阶技巧（可选） ​

1. 定时任务：每周自动审查代码中的 TODO ​

2. 自动 PR 审查（无需手动触发） ​

3. Issue 自动分类（过滤垃圾信息） ​

常见问题 (FAQ) ​

总结 ​

OpenCode GitHub 集成实战教程：AI 自动化 Issue 与 PR 处理

你将学到什么

最终效果

前置准备

1. 准备 API 密钥（以 Anthropic 为例）

第 1 步：安装 OpenCode GitHub App

第 2 步：创建工作流文件

第 3 步：将 API 密钥存储为 Secrets

第 4 步：测试 OpenCode 响应

第 5 步：尝试更多命令

进阶技巧（可选）

1. 定时任务：每周自动审查代码中的 TODO

2. 自动 PR 审查（无需手动触发）

3. Issue 自动分类（过滤垃圾信息）

常见问题 (FAQ)

总结