12.4 非交互模式

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

OpenCode 不仅是一个交互式工具——它也可以在非交互模式下运行，适用于 CI/CD 流水线、自动化脚本和代码生成等场景。

12.4.1 run 子命令：Pipeline / CI 场景

opencode run 是非交互模式的核心命令。它接受一个提示词（通过参数或标准输入），执行 Agentic Loop，流式输出结果，然后退出。

# 直接传入提示词
opencode run "Fix the TypeScript errors in src/utils.ts"

# 通过管道传入
cat bug_report.md | opencode run

# 组合使用
echo "Add unit tests for the auth module" | opencode run --model anthropic/claude-sonnet-4

# 继续上一个会话
opencode run -c "Now fix the remaining two test failures"

# 指定输出格式
opencode run --format json "What files were modified?"

实现解析

run.ts 的 handler 函数展示了非交互模式的完整流程：

// cli/cmd/run.ts (简化)
export const RunCommand = cmd({
  command: "run [prompt]",
  builder: (yargs) => yargs
    .positional("prompt", { type: "string" })
    .option("continue", { alias: "c", type: "boolean" })
    .option("session", { alias: "s", type: "string" })
    .option("fork", { type: "boolean" })
    .option("model", { alias: "m", type: "string" })
    .option("agent", { type: "string" })
    .option("file", { alias: "f", type: "array" })
    .option("format", { type: "string", choices: ["json"] })
    .option("thinking", { type: "boolean" }),
  handler: async (args) => {
    await bootstrap(cwd, async () => {
      // 1. 创建或继续会话
      const session = await resolveSession(args)

      // 2. 构建提示词（支持管道输入 + 文件附件）
      const prompt = buildPrompt(args)

      // 3. 发送消息并获取事件流
      const events = await sdk.session.chat({
        sessionID: session.id,
        content: prompt,
      })

      // 4. 流式处理事件
      for await (const event of events.stream) {
        switch (event.type) {
          case "message.part.updated":
            handlePartUpdate(event)  // 输出文本、工具调用等
            break
          case "session.status":
            if (event.status === "idle") return  // 完成
            break
          case "permission.asked":
            handlePermission(event)  // 非交互模式自动处理
            break
        }
      }
    })
  },
})

工具调用的格式化输出

run 命令为每种工具提供了简洁的格式化输出，让用户在终端中看到 Agent 正在做什么：

function tool(part: ToolPart) {
  if (part.tool === "bash") return bash(props<typeof BashTool>(part))
  if (part.tool === "glob") return glob(props<typeof GlobTool>(part))
  if (part.tool === "read") return read(props<typeof ReadTool>(part))
  if (part.tool === "grep") return grep(props<typeof GrepTool>(part))
  if (part.tool === "edit") return edit(props<typeof EditTool>(part))
  if (part.tool === "write") return write(props<typeof WriteTool>(part))
  if (part.tool === "task") return task(props<typeof TaskTool>(part))
  // ... 其他工具
  return fallback(part)  // 未知工具使用通用格式
}

每种工具的输出格式经过精心设计，以在终端中提供清晰、紧凑的信息：

✱ Glob "**/*.test.ts" in src/ · 12 matches
→ Read src/auth/auth.test.ts [offset=1, limit=50]
⎔ Edit src/auth/auth.ts (3 changes)
⚙ Bash npm test
  ✓ 47 passed, 0 failed
✱ Grep "TODO" in src/ · 3 matches
⌁ Task "Fix remaining TODOs" → session_abc123

JSON 输出格式

当使用 --format json 时，run 命令输出结构化的 JSON，便于在脚本中解析：

opencode run --format json "What files were modified?" | jq '.messages[-1].content'

管道输入支持

run 命令支持通过标准输入（stdin）接收提示词：

const prompt = await iife(async () => {
  const piped = !process.stdin.isTTY ? await Bun.stdin.text() : undefined
  if (!args.prompt) return piped
  return piped ? piped + "\n" + args.prompt : args.prompt
})

当标准输入不是 TTY（例如来自管道或重定向）时，读取标准输入的内容作为提示词的前缀。这使得以下用法成为可能：

# 将文件内容作为上下文
cat error_log.txt | opencode run "Analyze this error and suggest a fix"

# 与其他工具链组合
git diff | opencode run "Review this diff and suggest improvements"

12.4.2 generate 子命令：代码生成模式

opencode generate 是另一个非交互命令，用于生成 OpenAPI 规范和代码示例：

// cli/cmd/generate.ts
export const GenerateCommand = cmd({
  command: "generate",
  describe: "generate openapi spec with code samples",
  handler: async (args) => {
    await bootstrap(cwd, async () => {
      // 生成 OpenAPI JSON
      const spec = generateOpenAPISpec()
      
      // 输出到标准输出或文件
      console.log(JSON.stringify(spec, null, 2))
    })
  },
})

这个命令主要用于开发者工具链——生成的 OpenAPI 规范可以用于自动生成 SDK、API 文档、或测试客户端。

12.4.3 serve 子命令：无头 Server

opencode serve 启动一个没有 TUI 的 HTTP Server，适合在服务器环境中运行：

// cli/cmd/serve.ts
export const ServeCommand = cmd({
  command: "serve",
  describe: "starts a headless opencode server",
  handler: async (args) => {
    if (!Flag.OPENCODE_SERVER_PASSWORD) {
      console.log("Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.")
    }
    const opts = await resolveNetworkOptions(args)
    const server = Server.listen(opts)
    console.log(`opencode server listening on http://${server.hostname}:${server.port}`)
    // 保持进程永久运行
    await new Promise(() => {})
  },
})

serve 命令的典型使用场景：

• 远程开发：在远程服务器上运行 opencode serve，通过 Web UI 或 SDK 从本地访问。

• IDE 集成：IDE 扩展连接到正在运行的 OpenCode Server。

• 自动化平台：通过 API 与 OpenCode 交互，实现自动化代码审查、重构等。

12.4.4 其他非交互命令

OpenCode 还提供了一系列管理命令，均为非交互模式：

# 查看可用模型
opencode models

# 管理认证
opencode auth login
opencode auth status

# 管理 MCP Server
opencode mcp list
opencode mcp add <name> --command <cmd>

# 会话管理
opencode session list
opencode session export <id>

# 统计信息
opencode stats

# 版本管理
opencode upgrade
opencode uninstall

12.4.5 小结

OpenCode 的非交互模式体现了"Unix 哲学"——每个命令做好一件事，通过管道和脚本组合起来完成复杂任务：

1. run：单次执行，支持管道输入，适合 CI/CD 和自动化脚本。

2. serve：无头 Server，适合远程和集成场景。

3. generate：工具链支持，输出结构化数据。

4. 管理命令：配置和状态管理，支持脚本化操作。

这种交互与非交互模式的双重支持，使 OpenCode 既可以作为日常开发的交互式助手，也可以集成到自动化工作流中。