CLI 自动化：让 OpenCode 跑在脚本里

📝 课程笔记

本课核心知识点整理：

学完你能做什么

在脚本里调用 OpenCode，无需人工干预

启动远程服务器，让团队成员共享同一个 AI 会话

把 OpenCode 嵌入 CI/CD 流水线，自动审查代码

一键拉取 PR 并启动对应的 OpenCode 会话

你现在的困境

每次都要打开 TUI 手动输入命令，重复劳动太多

想在服务器上跑 OpenCode，但没有图形界面

CI/CD 里想自动让 AI 检查代码，不知道怎么集成

团队协作时，想让大家连到同一个 OpenCode 实例

什么时候用这一招

脚本自动化：批量处理多个项目、定时任务

CI/CD 集成：代码审查、自动修复、生成文档

远程开发：在服务器上运行，本地终端连接

团队协作：共享 OpenCode 实例，协同编辑

🎒 开始前的准备

完成了 5.1a 配置基础

能在终端里运行 opencode 启动 TUI

了解基本的 Shell 命令（cd、echo、管道）

核心思路

OpenCode 提供了两套使用方式：

┌─────────────────────────────────────────────────────────────────────────┐
│                        OpenCode 使用方式                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────────┐              ┌─────────────────┐                  │
│   │   交互模式 TUI   │              │  非交互模式 CLI  │                  │
│   │                 │              │                 │                  │
│   │  opencode       │              │  opencode run   │                  │
│   │                 │              │                 │                  │
│   │  • 适合日常开发  │              │  • 适合脚本     │                  │
│   │  • 实时对话     │              │  • 适合 CI/CD   │                  │
│   │  • 人工决策     │              │  • 自动化流程   │                  │
│   └─────────────────┘              └─────────────────┘                  │
│                                                                          │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                      服务器模式                                   │   │
│   │                                                                   │   │
│   │  opencode serve    →  启动无头服务器（只有 API）                   │   │
│   │  opencode web      →  启动 Web 界面服务器                         │   │
│   │  opencode attach   →  连接远程服务器                              │   │
│   │                                                                   │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

关键区别：

模式	命令	特点
TUI	`opencode`	交互式，适合人工操作
Run	`opencode run`	非交互式，执行完退出
Serve	`opencode serve`	无头服务器，只暴露 API
Web	`opencode web`	带 Web 界面的服务器

第一部分：非交互模式 opencode run

1.1 基本用法

opencode run 是最常用的 CLI 命令，它会执行完任务后自动退出。

1.2 常用选项

选项	说明	示例
`-m, --model`	指定模型	`-m anthropic/claude-opus-4-5`
`--agent`	指定 Agent	`--agent code-reviewer`
`-f, --file`	附加文件	`-f src/main.ts -f package.json`
`-c, --continue`	继续上次会话	`-c`
`-s, --session`	指定会话 ID	`-s session_abc123`
`--format json`	JSON 格式输出	`--format json`
`--share`	自动分享会话	`--share`
`--title`	设置会话标题	`--title "修复登录 Bug"`

1.3 实战示例

示例 1：代码审查脚本

示例 2：从 stdin 读取

示例 3：JSON 格式输出（适合脚本解析）

第二部分：服务器模式

2.1 启动远程服务器

::: info 🤔 什么时候需要远程服务器？

共享会话：团队成员连接同一个 OpenCode 实例

服务器开发：在远程服务器上运行，本地终端连接

避免冷启动：保持 MCP 服务器常驻，opencode run --attach 直接连入
:::

opencode serve（无头模式）

::: warning ⚠️ 安全警告
默认情况下，opencode serve 没有认证保护。

但默认只监听 127.0.0.1（localhost），外部网络无法直接访问。只有当你：

使用 --hostname 0.0.0.0 开放所有网络接口

服务器有公网 IP 且防火墙开放端口

...才会面临安全风险。

开放外网访问时必须设置密码：

:::

opencode web（Web 界面模式）

2.2 服务器选项

选项	说明	默认值
`--port`	监听端口	自动（优先 4096）
`--hostname`	监听地址	127.0.0.1
`--mdns`	启用 mDNS 服务发现	false
`--mdns-domain`	mDNS 域名	opencode.local
`--cors`	CORS 白名单域名	-

2.3 安全配置

环境变量：

变量	说明
`OPENCODE_SERVER_PASSWORD`	服务器密码
`OPENCODE_SERVER_USERNAME`	用户名（默认 opencode）

::: info 💡 为什么只能用环境变量？
密码相关的配置不支持放在 opencode.json 配置文件中，只能通过环境变量设置。

这是出于安全考虑——避免密码被意外提交到 Git 仓库。

全局配置文件 ~/.config/opencode/opencode.json 只支持以下服务器选项：

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "opencode.local",
    "cors": ["http://example.com"]
  }
}

:::

2.4 连接远程服务器

用 attach 连接

用 run 连接

第三部分：CI/CD 集成

3.1 GitHub Actions 示例

3.2 GitLab CI 示例

3.3 自动化脚本模板

第四部分：opencode pr 命令

4.1 功能介绍

opencode pr 是一个专门处理 GitHub PR 的命令，它会：

拉取指定的 PR 到本地

自动创建分支 pr/<PR号>

如果 PR 描述里有 OpenCode 会话链接，自动导入

4.2 使用场景

场景	说明
审查别人的 PR	一键拉取，直接在 OpenCode 里审查
继续之前的会话	PR 作者分享了会话链接，你可以恢复上下文
处理 Fork PR	自动添加 Fork 远程仓库，正确设置上游

4.3 前置条件

第五部分：会话管理 CLI

5.1 列出会话

5.2 导出会话

5.3 导入会话

第六部分：其他实用命令

6.1 opencode models

6.2 opencode stats

6.3 opencode upgrade / uninstall

检查点 ✅

能用 opencode run 执行一次性任务

能用 opencode serve 启动远程服务器并设置密码

能用 opencode attach 连接远程服务器

能用 opencode pr 拉取并处理 GitHub PR

能用 opencode session list 查看会话历史

能用 opencode export/import 备份恢复会话

踩坑提醒

现象	原因	解决
`opencode serve` 报错 "address already in use"	端口被占用	换个端口：`--port 8080`
远程连接被拒绝	防火墙或 hostname 设置	确认 `--hostname 0.0.0.0`，检查防火墙
`opencode pr` 报错 "gh CLI not found"	未安装 GitHub CLI	先安装 gh 并认证
`opencode run` 一直等待	AI 在执行长时间任务	脚本里加超时：`timeout 60 opencode run ...`
JSON 输出解析失败	输出包含多行 JSON	按换行分割，每行是一个 JSON 对象
服务器无认证警告	没有设置密码	`export OPENCODE_SERVER_PASSWORD=xxx`

本课小结

你学会了：

非交互模式：用 opencode run 在脚本里调用 OpenCode

服务器模式：用 opencode serve/web 启动远程服务

安全配置：设置 OPENCODE_SERVER_PASSWORD 保护服务器

CI/CD 集成：把 OpenCode 嵌入自动化流程

PR 处理：用 opencode pr 一键拉取并处理 PR

会话管理：用 CLI 命令列出、导出、导入会话

下一课预告

本课是进阶手册的最后一课。接下来你可以：
回顾速查手册中的 CLI 命令参考
尝试场景实战中的 CI/CD 集成案例
深入学习 SDK 开发编写自己的集成工具

附录：源码参考

点击展开查看源码位置

更新时间：2026-02-14

功能	文件路径	行号
`opencode run` 命令实现	`src/cli/cmd/run.ts`	215-614
`opencode serve` 命令实现	`src/cli/cmd/serve.ts`	6-20
`opencode web` 命令实现	`src/cli/cmd/web.ts`	全文件
`opencode pr` 命令实现	`src/cli/cmd/pr.ts`	6-112
服务器安全检查	`src/flag/flag.ts`	31-32
服务器认证逻辑	`src/server/server.ts`	84-87

关键环境变量：

OPENCODE_SERVER_PASSWORD：服务器密码

OPENCODE_SERVER_USERNAME：服务器用户名（默认 opencode）

"CLI 自动化：让 OpenCode 跑在脚本里 | OpenCode 教程"

CLI 自动化：让 OpenCode 跑在脚本里#

📝 课程笔记#

学完你能做什么#

你现在的困境#

什么时候用这一招#

🎒 开始前的准备#

核心思路#

第一部分：非交互模式 opencode run#

1.1 基本用法#

1.2 常用选项#

1.3 实战示例#

示例 1：代码审查脚本#

示例 2：从 stdin 读取#

示例 3：JSON 格式输出（适合脚本解析）#

第二部分：服务器模式#

2.1 启动远程服务器#

opencode serve（无头模式）#

opencode web（Web 界面模式）#

2.2 服务器选项#

2.3 安全配置#

2.4 连接远程服务器#

用 attach 连接#

用 run 连接#

第三部分：CI/CD 集成#

3.1 GitHub Actions 示例#

3.2 GitLab CI 示例#

3.3 自动化脚本模板#

第四部分：opencode pr 命令#

4.1 功能介绍#

4.2 使用场景#

4.3 前置条件#

第五部分：会话管理 CLI#

5.1 列出会话#

5.2 导出会话#

5.3 导入会话#

第六部分：其他实用命令#

6.1 opencode models#

6.2 opencode stats#

6.3 opencode upgrade / uninstall#

检查点 ✅#

踩坑提醒#

本课小结#

下一课预告#

附录：源码参考#