LowHow 文档中心

中文

English

中文

English

深色模式

OpenCode 非交互模式：自动化脚本 ​

📚 分类: AI 编程工具 / 开发效率 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 opencode 命令行工具 (最新稳定版)

你将学到什么 ​

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

  • [ ] 掌握 opencode 非交互模式的基本用法 (-p 参数)
  • [ ] 独立控制输出格式（纯文本、JSON）和显示行为（安静模式）
  • [ ] 理解非交互模式下的权限模型和安全注意事项
  • [ ] 用 Shell 脚本集成 opencode，实现代码审查、生成提交信息等自动化任务

最终效果 ​

你将能像使用一个“AI Shell 命令”一样，在终端里直接向 OpenCode 提问并获得回答，例如：

bash
$ opencode -p "用中文解释 Go 语言中 context 包的主要用途" -q
# 终端会直接打印出 AI 的解释，没有多余的动画或界面。

前置准备 ​

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

检查项要求验证命令
OpenCode已安装opencode --version

1. 安装 OpenCode (如果尚未安装) ​

如果你还没有安装 OpenCode，请根据你的系统执行以下操作。

macOS/Linux (使用 Homebrew):

bash
$ brew install opencode-ai/tap/opencode    // 通过 Homebrew 安装
$ opencode --version                        // 验证安装

Windows / 其他系统: 请参考 OpenCode 官方文档 的安装指引。

✅ 验证：如果看到输出版本号（如 v1.2.3），说明安装成功。

第 1 步：运行你的第一个非交互式命令 ​

🎯 目标：在不打开图形界面的情况下，让 OpenCode 回答一个简单问题。

📝 操作：

在终端中输入以下命令：

bash
$ opencode -p "用中文解释 Go 语言中 context 包的主要用途"
  • -p 或 --prompt：这是非交互模式的核心参数，后面跟你的提问内容。

💡 提示：首次运行可能需要你进行一些初始配置（如选择 AI 模型），请根据终端提示完成。

✅ 验证： 执行后，终端会先显示一个旋转的加载动画（spinner），然后 OpenCode 会打印出 AI 的完整回答，最后自动退出。你应该会看到类似以下的输出：

text
🤔 思考中...（加载动画）

Go 语言中的 `context` 包主要用于在多个 goroutine 之间传递请求作用域的数据、取消信号和超时时间。它常用于以下场景：
1. **超时控制**：防止长时间运行的请求...
2. **取消传播**：当一个请求被取消时，所有子任务也自动取消...
3. **传递元数据**：传递一些请求级别的数据，如 trace ID、认证 token 等...

主要使用 `context.Background()` 创建根 Context，使用 `context.WithCancel()`、`context.WithTimeout()` 等函数派生子 Context。

第 2 步：控制输出格式与安静模式 ​

🎯 目标：学习如何让 AI 的输出更易于程序解析，以及如何去掉加载动画，用于脚本集成。

📝 操作：

2.1 使用 JSON 格式输出 ​

当你需要将 AI 的回答集成到脚本或 CI/CD 流程中时，JSON 格式更方便程序解析。

bash
$ opencode -p "列出当前项目的所有 Go 文件" -f json
  • -f json 或 --output-format json：指定输出格式为 JSON。

✅ 验证： 输出将是一个 JSON 对象，而不是纯文本。

json
{
  "response": "当前项目的 Go 文件有:\n- main.go\n- handler.go\n- utils.go\n..."
}

2.2 使用安静模式 (Quiet Mode) ​

在管道操作或自动化脚本中，旋转的加载动画可能会干扰输出或导致错误。使用 -q 参数可以禁用它。

bash
$ opencode -p "检查 main.go 中是否有语法错误" -q
  • -q 或 --quiet：抑制所有非回答输出（如加载动画）。

✅ 验证： 执行后，终端不会显示加载动画，而是直接打印出 AI 的回答。

2.3 组合使用参数 ​

你可以将多个参数组合起来，实现最理想的输出控制。

bash
$ opencode -p "分析这个代码库的安全风险" -f json -q
  • 这条命令会直接输出一个 JSON 格式的回答，没有加载动画，非常适合脚本处理。

🤔 为什么要这样做？-f json 让输出结构化，便于 jq 等工具解析；-q 避免了非文本输出对脚本逻辑的干扰。组合使用是实现自动化集成的关键。

第 3 步：在指定目录下运行并启用调试日志 ​

🎯 目标：学习如何让 OpenCode 在特定项目目录下工作，并在遇到问题时获取详细的调试信息。

📝 操作：

bash
$ opencode -c /path/to/your/project -p "找到所有 TODO 注释" -d
  • -c /path/to/your/project 或 --chdir：指定工作目录。OpenCode 会在这个目录下分析代码。
  • -d 或 --debug：启用调试日志，输出详细的运行信息，有助于排查问题。

✅ 验证： 执行后，终端会先打印出大量的调试信息（以 [DEBUG] 开头），最后输出 AI 找到的 TODO 注释列表。调试信息可能如下：

text
[DEBUG] Reading config file: /home/user/.opencode.json
[DEBUG] Model set to: claude-3.7-sonnet
[DEBUG] Working directory: /path/to/your/project
[DEBUG] Sending prompt to AI...
...

💡 提示：-d 参数主要用于开发和调试，日常使用中通常不需要添加。

第 4 步：理解非交互模式的权限模型 ​

🎯 目标：了解非交互模式下 AI 的行为边界，避免潜在的安全风险。

📝 操作：

在非交互模式下，OpenCode 的权限策略与交互模式不同：所有权限请求都会被自动批准。

这意味着 AI 可以：

  • ✅ 直接执行命令：无需你手动确认。
  • ✅ 直接修改文件：AI 可以读取、修改甚至删除文件。
  • ✅ 直接访问 URL：AI 可以获取网络资源。

⚠️ 重要安全警告： 请务必谨慎使用！ 在运行一个可能对系统造成破坏的命令前（例如包含 rm -rf 或修改系统配置的 prompt），请仔细审查你的 -p 参数内容。

bash
# ❌ 危险示例：不要轻易执行这样的命令
$ opencode -p "删除 /tmp 目录下的所有文件" -q
# 这会直接执行，非常危险！

# ✅ 安全示例：询问建议，而不是直接执行破坏性操作
$ opencode -p "如何安全地清理 /tmp 目录下的临时文件？" -q
# AI 会给出建议，而不是直接执行删除操作。

✅ 验证： 你可以用一个安全的命令来验证自动批准行为：

bash
$ opencode -p "运行 'touch /tmp/opencode_test.txt' 命令" -q
# 执行后，检查 /tmp 目录，会发现 opencode_test.txt 文件已被创建。
# 这说明 AI 无需询问你，就直接执行了命令。

进阶技巧（可选） ​

掌握基础后，你可以尝试以下自动化脚本。

1. 用 Shell 函数创建快捷命令 ​

将常用操作封装成 Shell 函数，提升效率。

bash
# 在你的 ~/.bashrc 或 ~/.zshrc 中添加以下函数
ai-review() {
  opencode -p "Review the current git diff for common issues" -q
}

ai-explain() {
  opencode -p "$*" -q
}

之后，你就可以在终端中直接使用：

bash
$ ai-review
$ ai-explain "解释一下什么是闭包"

2. 生成 Git 提交信息 ​

将暂存区的代码变更发给 AI，让它帮你生成提交信息。

bash
$ git diff --cached | opencode -p "为一个 Git 提交生成描述性的提交信息" -q

3. 集成到 Git Hooks ​

在 pre-commit 钩子中自动进行代码审查。

bash
# 文件: .git/hooks/pre-commit
#!/bin/bash
changed_files=$(git diff --cached --name-only)
opencode -p "Review these changes for common issues: $changed_files" -q

常见问题 (FAQ) ​

Q1: 为什么我的命令执行后没有输出？A: 最常见的原因是网络问题或 API 密钥配置错误。

  1. 检查网络连接：ping api.opencode.ai (假设是这个地址)
  2. 检查 API 密钥：cat ~/.opencode.json，确认 apiKey 字段已正确配置。
  3. 尝试添加 -d 参数查看详细的调试日志，定位具体错误。

Q2: 如何在脚本中判断命令是否成功执行？A: OpenCode 非交互模式会返回标准的退出码。

  • 0：成功
  • 1：失败（配置错误、网络问题、AI 返回错误等）

你可以在脚本中这样使用：

bash
if opencode -p "修复这个 bug" -q; then
  echo "AI 成功完成"
else
  echo "AI 执行出错"
  exit 1
fi

Q3: 非交互模式和交互模式有什么区别？A: 主要区别在于：

  • 会话连续性：非交互模式每次运行都是独立的，无法进行多轮对话。对于复杂任务，请使用 opencode 启动交互模式。
  • 权限控制：非交互模式自动批准所有权限，交互模式会请求确认。
  • 目的：非交互模式适合脚本、自动化和简单问答；交互模式适合深度分析和多轮对话。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 核心命令：使用 opencode -p "你的问题" 实现基础的非交互式调用。
  2. 输出控制：使用 -f json 和 -q 参数控制输出格式和行为，为脚本集成做好准备。
  3. 权限与安全：非交互模式下权限自动批准，务必谨慎使用，避免执行破坏性操作。
  4. 自动化集成：通过 Shell 脚本、函数和 Git Hooks，将 OpenCode 无缝融入你的开发工作流。

© 2026 LowHow