OpenCode CLI 命令行与自动化完全指南

OpenCode 不仅是一个交互式终端工具，它还是一个强大的命令行程序。通过 CLI 模式，你可以将 AI 编程助手无缝集成到自动化脚本、CI/CD 流水线和日常开发工作流中。本文将全面覆盖 CLI 命令、非交互模式、自动化脚本编写和 CI/CD 集成。

CLI 安装确认

首先确认 CLI 已正确安装：

opencode --version
# opencode version 0.1.x

opencode --help
# 显示所有可用命令和参数

基础 CLI 命令

启动命令

# 进入交互模式
opencode

# 指定工作目录
opencode --cwd /path/to/project

# 指定模型
opencode --model claude-sonnet-4-20250514

# 以 Plan 模式启动
opencode --mode plan

# 指定 Agent
opencode --agent reviewer

专用命令

# 查看配置
opencode config show
opencode config validate

# 初始化项目
opencode init
opencode init --force    # 覆盖已有配置

# 诊断环境
opencode doctor

# MCP 管理
opencode mcp list        # 列出已配置的 MCP 服务器
opencode mcp test <name> # 测试 MCP 连接

# 更新
opencode update
opencode update --check  # 仅检查更新

非交互模式：-p / --prompt

非交互模式是 CLI 自动化的核心，通过 -p 参数直接传递任务：

# 单次任务
opencode -p "帮我修复 src/ 目录下所有的 ESLint 错误"

# 指定模型执行
opencode --model deepseek-chat -p "分析 package.json 中是否有需要更新的依赖"

# 指定工作目录
opencode --cwd /var/www/myapp -p "运行所有测试并输出结果摘要"

非交互模式的特点

  • 不进入 TUI：直接在终端输出结果
  • 适合脚本化：可以通过 &&、| 等与其他命令组合
  • 返回退出码：成功返回 0，失败返回 1

管道输入

# 将文件内容传给 OpenCode 分析
cat error.log | opencode -p "分析这些错误日志，找出最频繁的错误并给出解决方案"

# 通过管道传入代码
cat src/app.ts | opencode -p "审查这段 TypeScript 代码的质量"

文件引用模式

# 引用特定文件
opencode -p "@src/auth.ts 分析这个认证模块的安全性"

# 引用多个文件
opencode -p "@src/api.ts @src/db.ts 检查这两个模块之间的数据流是否合理"

自动化脚本编写

代码质量门禁脚本

#!/bin/bash
# scripts/quality-gate.sh

echo "运行代码质量检查..."

# 1. 运行 lint
opencode --cwd $(pwd) -p "运行 npx eslint src/ --ext .ts,.tsx，如果有任何错误，逐一修复它们。修复后再次运行确认无错误。"

# 2. 运行类型检查
opencode --cwd $(pwd) -p "运行 npx tsc --noEmit，修复所有类型错误"

# 3. 运行测试
opencode --cwd $(pwd) -p "运行 npm test，如果任何测试失败，分析原因并修复代码，不要修改测试用例本身"

echo "代码质量检查完成"

自动生成 Release Notes

#!/bin/bash
# scripts/generate-release-notes.sh

VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.1.0")
echo "生成 $VERSION 的 Release Notes..."

opencode -p "
基于 git log $VERSION..HEAD 的提交记录，
生成格式化的 Release Notes:

格式要求：
## 🚀 新功能
- feature description

## 🐛 修复
- fix description

## 🔧 优化
- refactor/chore description

使用中文描述，每行不超过 60 字。
" > CHANGELOG_${VERSION}.md

echo "已生成 CHANGELOG_${VERSION}.md"

每日代码审查

#!/bin/bash
# scripts/daily-review.sh

echo "今日代码审查..."

# 获取今日提交
TODAY=$(date +%Y-%m-%d)

opencode -p "
审查今天的所有代码提交 ($TODAY):

1. 运行 git log --since='$TODAY 00:00' --until='$TODAY 23:59' --oneline
2. 对每个提交进行审查：
   - 代码逻辑是否正确
   - 有无安全漏洞
   - 有无性能问题
3. 给出审查报告，按严重程度排序
"

CI/CD 集成

GitHub Actions 集成

# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install OpenCode
        run: npm i -g opencode-ai@latest

      - name: AI Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode -p "
          审查 PR #${{ github.event.pull_request.number }} 的代码变更：

          1. 运行 git diff origin/main...HEAD 查看变更
          2. 关注以下方面：
             - 逻辑错误和边界条件
             - 安全漏洞（SQL注入、XSS、敏感信息泄露）
             - 性能瓶颈
             - 代码风格是否与项目一致
             - 是否需要补充测试
          3. 以 PR Review 的格式输出审查意见
          " > review.md

      - name: Post Review
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: review
            });

自动修复 CI 失败

# .github/workflows/auto-fix.yml
name: Auto Fix on Failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  auto-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: AI Auto Fix
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode -p "
          上一个 CI 流程失败了。请：
          1. 查看 GitHub Actions 的失败日志
          2. 分析失败原因
          3. 修复代码使得 CI 能通过
          4. 不要修改测试用例本身（如果是测试失败且是代码问题才修复代码）
          "

      - name: Create Fix PR
        uses: peter-evans/create-pull-request@v6
        with:
          title: "🤖 Auto Fix: CI Failure"
          body: "AI 自动修复 CI 失败"
          branch: auto-fix/ci-failure

GitLab CI 集成

# .gitlab-ci.yml
ai-review:
  stage: review
  image: node:22
  before_script:
    - npm i -g opencode-ai@latest
  script:
    - opencode -p "
      审查这个 MR 的代码变更，关注安全性、性能和代码质量。
      输出审查报告到 review.md。
      "
    - cat review.md
  only:
    - merge_requests
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

批量处理脚本

批量代码迁移

#!/bin/bash
# scripts/migrate-imports.sh

echo "批量迁移 import 路径..."

opencode -p "
将 src/ 目录下所有 TypeScript 文件中的以下 import 路径更新：

旧路径 → 新路径：
'@/utils/' → '@/lib/utils/'
'@/hooks/' → '@/shared/hooks/'
'@/types/' → '@/shared/types/'

规则：
- 只更新路径前缀，保持文件名不变
- 同时更新相关的类型导入
- 完成后运行 npx tsc --noEmit 验证
- 不要改变任何其他代码
"

自动化文档更新

#!/bin/bash
# scripts/update-docs.sh

opencode -p "
检查 src/ 目录中是否有新增的公开 API 或导出的函数，
如果 docs/api.md 中没有对应的文档，请补充。

关注：
- 新添加的 export 函数/类
- 参数和返回值的类型
- 使用示例
- 不要删除任何已有内容
"

自动化最佳实践

1. 错误处理

#!/bin/bash
set -e  # 遇到错误立即退出

if ! opencode -p "运行 npm test 并修复失败的测试"; then
    echo "自动修复失败，需要手动介入"
    exit 1
fi

echo "所有测试通过"

2. 日志记录

#!/bin/bash
LOG_FILE="opencode-$(date +%Y%m%d-%H%M%S).log"

opencode -p "执行代码审查" 2>&1 | tee "$LOG_FILE"

echo "日志已保存到 $LOG_FILE"

3. 超时控制

# 设置任务超时时间
timeout 600 opencode -p "大规模重构任务..." || echo "任务超时"

4. 环境隔离

# 在临时工作区中执行
WORKDIR=$(mktemp -d)
cp -r src/ "$WORKDIR/"

opencode --cwd "$WORKDIR" -p "分析代码"

rm -rf "$WORKDIR"

5. 并发控制

#!/bin/bash
# 并行处理多个独立任务

opencode -p "检查前端代码" > frontend-report.md &
PID1=$!

opencode -p "检查后端代码" > backend-report.md &
PID2=$!

wait $PID1 $PID2

cat frontend-report.md backend-report.md > full-report.md
echo "全量检查完成"

组合使用案例

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Pre-commit: AI 代码审查..."

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$' || true)

if [ -n "$STAGED_FILES" ]; then
    opencode -p "
    审查以下暂存文件的代码变更：
    $(echo "$STAGED_FILES" | tr '\n' ' ')

    关注：
    - console.log / debugger 等调试代码是否遗留
    - 是否有硬编码的密码或 Token
    - 是否有未处理的 Promise
    - TypeScript 类型使用是否正确

    如果有问题，直接列出。如果没有问题，回复 'LGTM'。
    "
fi

Docker 集成

# Dockerfile
FROM node:22-alpine

RUN npm i -g opencode-ai@latest

WORKDIR /workspace

ENTRYPOINT ["opencode"]
CMD ["-p", "分析项目代码"]
docker run --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  opencode-runner -p "检查代码质量并修复问题"

小结

CLI 模式让 OpenCode 不再是只能「聊天」的终端工具，而是可以深度嵌入自动化流程的编程引擎。从 pre-commit hook 到 CI/CD 流水线，从批量重构到自动 Code Review——合理利用 CLI 自动化能力，OpenCode 可以成为你开发流程中无缝运行的一环。

下一篇我们将深入 OpenCode 的权限与安全系统，学习如何精细控制 AI 的每一步操作，确保代码安全。

叶云梦天

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