OpenCode 非交互模式与 CI/CD 自动化实战指南

OpenCode 非交互模式与 CI/CD 自动化实战指南

引言

OpenCode 最为人熟知的是其强大的终端交互界面（TUI），你可以在其中编写代码、搜索文件、执行命令，与 AI 进行持续对话。但 OpenCode 的能力远不止于此——它还提供了完整的非交互模式，让你能够将 AI 编程助手集成到脚本、CI/CD 流水线和自动化工作流中。

在非交互模式下，OpenCode 接受一个提示词（prompt），独立执行完整的 Agentic Loop，完成后自动退出。这意味着你可以在 GitHub Actions 中自动审查 PR、在定时任务中检查代码质量、在本地脚本中批量重构代码——全程无需人工干预。

本文将从基础用法到生产级 CI/CD 集成，全面讲解 OpenCode 非交互模式的实战技巧。

opencode run：非交互模式的核心命令

opencode run 是非交互模式的入口。最基本的用法是在命令行中直接传入提示词：

opencode run "给 src/api.ts 添加错误处理"

这条命令会启动一个 Agent，按照提示词执行任务，将结果输出到终端，然后自动退出。与 TUI 模式不同，整个过程不会进入交互界面。

关键参数

opencode run 支持丰富的命令行参数：

| 参数 | 简写 | 说明 |
|------|------|------|
| --continue | -c | 继续上一次会话 |
| --session | -s | 指定要恢复的会话 ID |
| --fork | | 分支会话（需配合 --continue 或 --session） |
| --model | -m | 指定模型，格式为 provider/model |
| --agent | | 指定使用的 Agent |
| --file | -f | 附加文件到提示词中 |
| --format | | 输出格式：默认格式化或 json |
| --title | | 设置会话标题 |
| --attach | | 连接到运行中的 OpenCode 服务器 |
| --port | | 本地服务器端口（默认随机） |

指定模型运行

你可以在非交互模式下临时切换模型：

opencode run -m anthropic/claude-sonnet-4-20250514 "审查 src/ 目录下的代码，找出潜在的性能问题"

这样可以在不同任务中使用不同的模型——用快速廉价的模型做简单检查，用功能强大的模型做深度分析。

恢复历史会话

有时你需要继续上一次的工作，而不想从零开始：

# 继续上一会话
opencode run -c "继续上一次的代码审查工作"

# 继续指定会话
opencode run -s ses_abc123 "刚才的重构还没完成，请继续"

配合 --fork 参数，你可以在不修改原始会话的前提下，基于历史会话创建一个分支继续探索：

opencode run -c --fork "尝试另一种实现方案"

JSON 输出：为自动化而生

在脚本和 CI/CD 中，文本输出难以解析。使用 --format json 可以让 OpenCode 输出结构化的 JSON 数据：

opencode run --format json "检查项目中是否有未使用的依赖"

JSON 输出会流式返回一系列事件对象，你可以用 jq 等工具进行解析。一个典型的输出可能是这样的：

{
  "type": "progress",
  "sessionID": "ses_abc123",
  "content": "正在检查 package.json..."
}

结合 jq 进行脚本化处理

# 提取会话 ID
SESSION_ID=$(opencode run --format json "分析代码" | jq -r '.sessionID' | head -n 1)

# 获取最终结果
RESULT=$(opencode run --format json "列出所有 TODO 注释" | jq -rs 'last.content')

你可以把这种模式封装成 shell 函数，在 Makefile 或 CI 脚本中复用：

review:
	@opencode run --format json "review PR changes" | jq .

管道输入：将数据喂给 OpenCode

opencode run 支持从标准输入（stdin）接收数据。当 stdin 不是 TTY 时（比如来自管道或重定向），输入内容会被作为提示词的前缀使用：

# 将文件内容作为上下文传入
cat src/api.ts | opencode run "给上述代码添加错误处理"

# 从日志中提取关键信息进行分析
tail -n 100 ./logs/app.log | opencode run "分析这些日志，找出错误原因并给出修复建议"

# Git diff 分析
git diff HEAD~1 | opencode run "审查这次提交的改动，指出潜在问题"

这种模式特别适合将 OpenCode 整合到现有的 Unix 工具链中，发挥管道组合的威力。

GitHub Actions 集成：自动化你的开发流程

OpenCode 提供了原生的 GitHub Actions 集成，通过在 Issue 或 PR 评论中使用 /opencode 或 /oc 指令即可触发 AI 助手执行任务。

安装 GitHub 集成

在项目根目录下运行：

opencode github install

这条命令会自动在 .github/workflows/ 目录下创建 opencode.yml 工作流文件。核心工作流配置如下：

name: opencode
on:
  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-latest
    permissions:
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false
      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514

配置完成后，你只需要在 GitHub 评论中写下指令：

/oc 修复这个 bug，添加单元测试

OpenCode 会自动在 Actions runner 中执行任务，创建新分支并提交 PR。

PR 自动审查

你可以配置工作流在 PR 创建或更新时自动进行代码审查：

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: |
            Review this pull request:
            - Check for code quality issues
            - Look for potential bugs
            - Suggest improvements

当 pull_request 事件触发且没有提供 prompt 时，OpenCode 默认会进行 PR 审查。

Issue 自动分流

对于新创建的 Issue，可以配置 OpenCode 自动进行分析和分流：

name: Issue Triage
on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: Check account age
        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: |
            Review this issue. If there's a clear fix or relevant docs:
            - Provide documentation links
            - Add error handling guidance for code examples
            Otherwise, do not comment.

这个示例中还加入了一个账户年龄检查，防止新注册的垃圾账户触发自动化操作。

支持的事件类型

OpenCode GitHub Action 支持多种触发事件：

| 事件类型 | 触发方式 | 说明 |
|---------|---------|------|
| issue_comment | Issue/PR 评论中包含 /oc 或 /opencode | 在评论中给出指令 |
| pull_request_review_comment | 代码行评论中包含 /oc 或 /opencode | 针对特定代码行给出指令 |
| issues | Issue 创建或编辑 | 自动处理 Issue，需要 prompt |
| pull_request | PR 打开、更新、重新打开 | 自动审查 PR |
| schedule | Cron 定时任务 | 周期执行任务，需要 prompt |
| workflow_dispatch | 手动触发 | 按需通过 Actions 页面触发 |

定时任务：让 AI 定期守护你的代码库

通过 schedule 事件，你可以配置 OpenCode 定期执行代码维护任务：

name: Scheduled OpenCode Task
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:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          persist-credentials: false
      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            Review the codebase for any TODO comments and create a summary.
            If you find issues worth addressing, open an issue to track them.

对于定时任务，prompt 参数是必需的——因为没有用户评论需要解析。此外，如果希望 OpenCode 创建分支或 PR，工作流必须授予 contents: write 和 pull-requests: write 权限。

常见的定时任务应用场景：

  • 每周代码质量扫描：检查 TODO/FIXME 注释并创建 Issue 跟踪
  • 依赖更新检查：定期查看 package.json 或 go.mod 是否有可更新的依赖
  • 文档同步：检查代码变更是否同步更新了相关文档
  • 安全漏洞扫描：配合安全工具，审查新提交的代码是否存在已知漏洞模式

opencode serve：无头服务器模式

除了 run 命令，OpenCode 还提供了 serve 命令，以 HTTP 服务器的形式运行：

opencode serve --port 4096 --hostname 0.0.0.0

这将启动一个无桌面的 OpenCode 服务器实例，监听在指定端口上。典型的使用场景包括：

  • 远程开发：在远程服务器上运行 opencode serve，通过 Web UI 或 SDK 从本地访问
  • IDE 集成：IDE 扩展连接到运行中的 OpenCode 服务器
  • 自动化平台：通过 API 与 OpenCode 交互，实现自动化代码审查和重构

如果需要安全性，可以设置密码：

export OPENCODE_SERVER_PASSWORD="your-strong-password"
opencode serve --port 4096

连接到运行中的服务器

如果你已有一个 opencode serve 实例在运行，可以通过 --attach 将 run 命令连接到它：

opencode run --attach http://localhost:4096/ "分析 src/ 目录的代码结构"

这样可以避免每次执行 run 时重复加载 MCP 服务器的冷启动延迟。

环境变量与全局配置

OpenCode 支持丰富的环境变量来控制非交互模式下的行为：

| 环境变量 | 说明 |
|---------|------|
| OPENCODE_CONFIG | 指定配置文件路径 |
| OPENCODE_CONFIG_CONTENT | 内联 JSON 配置内容（直接嵌入 CI 脚本） |
| OPENCODE_CONFIG_DIR | 指定 .opencode 目录路径 |
| OPENCODE_AUTO_SHARE | 自动分享会话 |
| OPENCODE_DISABLE_AUTOUPDATE | 禁止自动更新检查 |
| OPENCODE_SERVER_PASSWORD | 为 serve/web 模式设置基础认证密码 |
| OPENCODE_CLIENT | 客户端标识（默认 cli） |

这对于 CI/CD 环境特别有用。例如，在 GitHub Actions 中，你可以通过 OPENCODE_CONFIG_CONTENT 直接内联完整配置：

- uses: anomalyco/opencode/github@latest
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    OPENCODE_CONFIG_CONTENT: |
      {
        "permission": {
          "edit": "allow",
          "bash": "allow",
          "webfetch": "deny",
          "websearch": "deny"
        }
      }
  with:
    model: anthropic/claude-sonnet-4-20250514
    prompt: "修复 TypeScript 类型错误"

常见问题与最佳实践

权限配置

在非交互模式下，权限管理尤为重要。因为没有人可以响应 "ask" 弹窗，你需要确保代理拥有完成任务所需的所有权限：

{
  "permission": {
    "edit": "allow",
    "bash": "allow",
    "glob": "allow",
    "grep": "allow",
    "read": "allow",
    "question": "deny",
    "plan_enter": "deny",
    "plan_exit": "deny"
  }
}

特别注意 question 工具——在非交互模式下应该设为 deny，否则 Agent 可能会尝试向用户提问而导致流程挂起。

会话清理

每次 opencode run 都会创建一个持久化会话。如果你只是执行一次性脚本任务，这些会话会污染历史记录。目前的一个变通方案是执行后手动清理：

# 执行任务并捕获会话 ID
SESSION=$(opencode run --format json "修复 lint 错误" | jq -r '.sessionID' | head -n 1)

# 清理会话
opencode session delete "$SESSION"

（社区正在讨论 --ephemeral / --no-session 等原生支持一次性会话的功能，届时将更加方便。）

日志调试

当非交互模式出现问题时，可以打开详细日志排查：

opencode run --print-logs --log-level DEBUG "Create a test file"

这会输出 DEBUG 级别的详细日志，帮助你了解 Agent 的决策过程和工具调用情况。

选择合适的模型

不同任务对模型的要求不同，合理选择模型可以优化成本和效果：

# 简单任务用快速便宜的模型
opencode run -m opencode-go/deepseek-v4-flash "格式化代码"

# 复杂分析用能力强的模型
opencode run -m anthropic/claude-sonnet-4-20250514 "全面审查安全漏洞"

总结

OpenCode 的非交互模式打破了"AI 编程助手只能在 TUI 中使用"的印象，将 AI 的能力延伸到了自动化工作流的每一个角落。

从简单的 opencode run 到完整的 GitHub Actions 集成，你拥有了一个在 CI/CD 流水线中自动进行代码审查、Issue 分流、定时巡检的能力。配合 JSON 格式化输出和管道输入，OpenCode 完美融入了 Unix 工具链，成为了脚本和自动化系统的原生组成部分。

当你下一次面对重复的代码审查工作、琐碎的文档同步任务、或需要定期巡检的代码质量问题时，不妨将 OpenCode 的非交互模式纳入你的自动化武器库——让 AI 替你完成那些机械的、可模式化的工作，把宝贵的时间留给真正需要创造力的部分。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客