# OpenCode 与 GitHub 联用操作手册

## 目录- [一、概述](#一概述)- [二、基础 CLI 命令](#二基础-cli-命令)- [三、GitHub 集成命令](#三github-集成命令)- [四、安装与配置](#四安装与配置)- [五、实际使用场景示例](#五实际使用场景示例)- [六、配置参数详解](#六配置参数详解)- [七、支持的 GitHub 触发事件](#七支持的-github-触发事件)- [八、权限配置最佳实践](#八权限配置最佳实践)- [九、常见问题与排错](#九常见问题与排错)- [十、进阶技巧](#十进阶技巧)---## 一、概述OpenCode 是一个开源的 AI 编程助手可深度集成 GitHub 工作流让 AI 直接参与 Issue、Pull Request 和代码审查流程。通过在评论中输入 /opencode 或 /oc 即可触发 AI 自动执行任务。**核心特性**- Issue 自动分析与分类- 自动创建分支并提交修复 PR- 代码行级精准审查- 在你的 GitHub Runner 中安全执行---## 二、基础 CLI 命令### 2.1 启动 OpenCode| 命令 | 中文说明 | 使用示例 ||------|---------|---------|| opencode | 启动终端用户界面TUI | opencode || opencode [project] | 在指定项目目录启动 | opencode my-project || opencode tui | 显式启动 TUI 模式 | opencode tui |### 2.2 非交互式运行| 命令 | 中文说明 | 使用示例 ||------|---------|---------|| opencode run prompt | 直接执行 AI 任务不启动 TUI | opencode run 解释这段代码 || opencode run --model provider/model prompt | 指定模型执行任务 | opencode run --model anthropic/claude-sonnet-4 优化这段代码 || opencode run --continue | 继续上一个会话 | opencode run --continue 继续实现该功能 || opencode run --session [id] | 从指定会话继续 | opencode run --session abc123 修复 bug |### 2.3 认证管理| 命令 | 中文说明 | 使用示例 ||------|---------|---------|| opencode auth login | 登录并配置模型提供商 API Key | opencode auth login || opencode auth list | 列出已认证的所有提供商 | opencode auth list || opencode auth logout | 登出并清除凭证 | opencode auth logout |### 2.4 模型管理| 命令 | 中文说明 | 使用示例 ||------|---------|---------|| opencode models | 列出所有可用模型 | opencode models || opencode models [provider] | 过滤显示指定提供商的模型 | opencode models anthropic |---## 三、GitHub 集成命令### 3.1 GitHub 安装与配置| 命令 | 中文说明 | 使用场景 ||------|---------|---------|| opencode github install | 在仓库中安装 GitHub Agent推荐 | 在仓库根目录执行推荐使用此方式 || opencode github run --event mock-event.json | 在 GitHub Actions 中运行 Agent | 用于测试和调试 || --token 指定 GitHub 个人访问令牌PAT | 用于认证和授权操作 | 适用于需要手动触发的场景 |---## 四、安装与配置### 4.1 快速安装推荐bash# 1. 在 GitHub 项目根目录运行cd your-github-repoopencode github install# 该命令自动完成# - 安装 GitHub App# - 创建 GitHub Actions 工作流文件# - 引导配置 API Key### 4.2 手动安装进阶**步骤 1安装 GitHub App**bash# 访问以下网址安装 App# https://github.com/apps/opencode-agent# 选择目标仓库进行安装**步骤 2创建工作流文件**创建 .github/workflows/opencode.ymlyamlname: opencodeon:issue_comment:types: [created]pull_request_review_comment:types: [created]jobs:opencode:if: |contains(github.event.comment.body, /oc) ||contains(github.event.comment.body, /opencode)runs-on: ubuntu-latestpermissions:id-token: writecontents: writepull-requests: writeissues: writesteps:- name: Checkout repositoryuses: actions/checkoutv6with:fetch-depth: 1persist-credentials: false- name: Run OpenCodeuses: anomalyco/opencode/githublatestenv:ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}with:model: anthropic/claude-sonnet-4-20250514# share: true# token: ${{ secrets.GITHUB_TOKEN }}**步骤 3配置 Secrets**1. 进入 GitHub 仓库 → Settings → Secrets → Actions2. 添加所需的 API Key如 ANTHROPIC_API_KEY---## 五、实际使用场景示例### 5.1 场景一解释 Issue**在 Issue 评论中输入**/opencode explain this issue**或使用缩写**/oc summarize this issue and suggest possible solutions**AI 执行动作**- 读取整个 Issue 线程包括所有评论- 分析问题的核心要点- 回复清晰的解释和建议---### 5.2 场景二自动修复 Issue 并创建 PR**在 Issue 评论中输入**/opencode fix this bug**或更详细的指令**/oc fix this authentication issue, follow the same pattern as in the user service**AI 自动执行流程**1. 创建新分支自动命名如 fix-auth-issue-1232. 分析代码库定位问题3. 实现修复方案4. 提交代码变更5. 自动创建 Pull Request6. 在 Issue 中回复 PR 链接---### 5.3 场景三修改现有 PR**在 PR 评论中直接输入需求**Delete the attachment from S3 when the note is removed /oc**或单独使用**/oc add input validation to this form handler**AI 执行动作**- 直接在当前 PR 分支提交修改- 保留原有提交历史- 无需人工干预---### 5.4 场景四代码行级精准操作最强功能**操作步骤**1. 进入 PR 的 Files changed 标签页2. 在特定代码行上点击评论3. 输入/oc add error handling here**AI 自动获取的上下文**- ✅ 精确的文件路径- ✅ 具体的行号- ✅ 周围的 diff 上下文- ✅ 代码变更历史**无需手动说明位置**---### 5.5 场景五PR 自动审查**创建 .github/workflows/opencode-review.yml**yamlname: opencode-reviewon:pull_request:types: [opened, synchronize, reopened, ready_for_review]jobs:review:runs-on: ubuntu-latestpermissions:id-token: writecontents: readpull-requests: readissues: readsteps:- uses: actions/checkoutv6with:persist-credentials: false- uses: anomalyco/opencode/githublatestenv:ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}with:model: anthropic/claude-sonnet-4-20250514use_github_token: trueprompt: |审查这个 Pull Request:- 检查代码质量问题- 查找潜在的 Bug- 提出改进建议- 检查是否符合项目编码规范**触发时机**- PR 首次创建时- 有新提交同步时- PR 从草稿变为就绪时---### 5.6 场景六定时自动化任务**示例每周一扫描代码库的 TODO**创建 .github/workflows/opencode-scheduled.ymlyamlname: Scheduled TODO Scanon:schedule:- cron: 0 9 * * 1 # 每周一 9:00 执行workflow_dispatch: # 也支持手动触发jobs:todo-scan:runs-on: ubuntu-latestpermissions:id-token: writecontents: writepull-requests: writesteps:- uses: actions/checkoutv6- uses: anomalyco/opencode/githublatestenv:ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}with:model: anthropic/claude-sonnet-4-20250514prompt: |扫描整个代码库:1. 查找所有 TODO 和 FIXME 注释2. 按优先级分类3. 创建一个 Issue 汇总所有发现4. 建议哪些可以立即修复---### 5.7 场景七Issue 自动分类防垃圾**创建 .github/workflows/opencode-triage.yml**yamlname: Issue Triageon:issues:types: [opened]jobs:triage:runs-on: ubuntu-latestpermissions:id-token: writecontents: writepull-requests: writeissues: writesteps:- name: Check account ageid: checkuses: actions/github-scriptv7with: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/checkoutv6if: steps.check.outputs.result true- uses: anomalyco/opencode/githublatestif: steps.check.outputs.result trueenv:ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}with:model: anthropic/claude-sonnet-4-20250514prompt: |审查这个 Issue:- 如果有明确的修复方案提供指导- 如果是文档相关问题提供相关文档链接- 如果需要更多信息礼貌请求- 如果是垃圾信息不要回应---## 六、配置参数详解| 参数 | 中文说明 | 可选值/格式 | 必填 ||------|---------|-----------|-----|| model | 使用的 AI 模型 | provider/model如 anthropic/claude-sonnet-4 | ✅ || agent | 指定使用的 Agent | Agent 名称 | ❌ || share | 是否分享会话链接 | true/false | ❌ || prompt | 自定义提示词 | 字符串支持多行 | ❌ || token | GitHub 访问令牌 | PAT 或 ${{ secrets.GITHUB_TOKEN }} | ❌ |---## 七、支持的 GitHub 触发事件| 事件类型 | 触发方式 | 说明 ||---------|---------|-----|| issue_comment | Issue 或 PR 评论 | 评论中包含 /oc 或 /opencode 时触发 || pull_request_review_comment | PR 代码行评论 | 在 Files 标签页的特定代码行上评论 || issues | Issue 创建/更新 | 自动处理新 Issue需提供 prompt || pull_request | PR 创建/更新 | 自动审查 PR可选自定义 prompt || schedule | Cron 定时任务 | 定时执行必须提供 prompt || workflow_dispatch | 手动触发 | 通过 GitHub Actions 页面手动运行 |---## 八、权限配置最佳实践**推荐最小权限配置**yamlpermissions:id-token: write # 用于 OpenID Connect 认证contents: write # 代码读写权限pull-requests: write # PR 操作权限issues: write # Issue 操作权限**安全提示**- 仅授予必要的权限最小权限原则- 对于公开仓库建议设置 share: true 方便团队协作- 敏感仓库可禁用会话分享share: false---## 九、常见问题与排错### Q: OpenCode 没有响应我的评论**A:** 检查以下几点1. 工作流文件是否正确创建2. Secrets 中的 API Key 是否正确配置3. GitHub Actions 日志中是否有报错4. 确认评论中包含 /oc 或 /opencode### Q: 如何使用自定义模型**A:** 在工作流的 with 中修改 model 参数yamlwith:model: openai/gpt-4o### Q: 可以使用 GITHUB_TOKEN 而不安装 App 吗**A:** 可以只需在工作流中配置yamlwith:use_github_token: trueenv:GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}### Q: 如何查看执行日志**A:**1. 进入仓库的 Actions 标签2. 点击对应的工作流运行记录3. 展开 Run OpenCode 步骤查看详细日志---## 十、进阶技巧### 10.1 团队代码规范自动化yamlprompt: |审查此 PR 是否符合团队规范:- 使用 TypeScript 严格模式- 组件命名使用 PascalCase- 函数使用 JSDoc 注释- 测试覆盖率不低于 80%不符合的地方请明确指出并提供修正建议### 10.2 安全自动化审查yamlprompt: |安全审查此代码变更:- 检查 SQL 注入漏洞- 验证 XSS 防护- 确认认证授权逻辑- 检查敏感信息泄露发现问题请标记 severity 等级### 10.3 文档自动更新yamlprompt: |检查此 PR 是否需要更新文档:- 如果 API 有变化更新 OpenAPI 规范- 如果配置项变更更新 README- 创建或更新相关文档文件自动提交文档变更到同一 PR---**参考资源**- 官方网站: [opencode.ai](https://opencode.ai)- 官方文档: [opencode.ai/docs](https://opencode.ai/docs)- GitHub: [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode)---## 附录命令速查表### 基础命令| 命令 | 说明 | 示例 ||------|------|------|| opencode | 启动 TUI | opencode my-project || opencode run | 非交互运行 | opencode run 优化这段代码 || opencode auth login | 配置 API Key | - || opencode models | 查看可用模型 | opencode models anthropic |### GitHub 命令| 命令 | 说明 | 示例 ||------|------|------|| opencode github install | 安装 GitHub Agent | 在仓库根目录执行 || opencode github run | 运行 Agent | opencode github run --event event.json |**触发关键字在 GitHub 评论中使用**- /oc - 触发 OpenCode- /opencode - 触发 OpenCode完整写法