OpenCode CLI 使用

OpenCode 提供了强大的命令行接口（CLI），不仅可以启动交互式 TUI，还可以通过命令实现自动化、脚本化操作。

默认情况下，OpenCode CLI 会启动 TUI，但它的真正能力在于可编程调用。

OpenCode CLI 不只是一个命令工具，而是一个可编程的 AI 开发接口。

OpenCode CLI 可以抽象为三层：

• 交互层：tui / web / attach
• 执行层：run / agent / mcp / github
• 服务层：serve / acp

👉 本质是一个AI Agent + 本地开发环境 + 可编程 CLI + Server API的统一入口。

下面是 OpenCode CLI 命令完整表：

基础行为

命令/用法	作用说明	备注
opencode	默认启动 TUI	无参数时
opencode run "msg"	非交互执行任务	自动化/脚本

tui 启动参数

标志	简写	作用说明
--continue	-c	继续上一次会话
--session	-s	指定会话 ID
--fork	—	分叉会话
--prompt	—	初始提示词
--model	-m	指定模型
--agent	—	指定代理
--port	—	监听端口
--hostname	—	主机地址

核心 CLI 命令

命令	作用说明	关键子命令
agent	管理代理	create / list
auth	管理认证	login / list / logout
attach	连接远程后端	—
github	GitHub 自动化	install / run
mcp	MCP 服务管理	add / list / auth / debug
models	查看模型列表	—
run	非交互执行	—
serve	启动 API 服务	—
web	Web UI 服务	—
session	会话管理	list
stats	Token/费用统计	—
export	导出会话	—
import	导入会话	—
acp	启动 ACP 协议服务	—
uninstall	卸载	—
upgrade	升级版本	—

run 命令参数

标志	简写	作用说明
--continue	-c	继续会话
--session	-s	指定会话
--fork	—	分叉
--share	—	分享会话
--model	-m	指定模型
--agent	—	指定代理
--file	-f	附加文件
--format	—	输出格式（json）
--title	—	会话标题
--attach	—	连接已有服务
--port	—	本地端口

服务类命令参数

serve / web / acp

标志	作用说明
--port	监听端口
--hostname	主机地址
--mdns	局域网发现
--cors	允许跨域

session / stats 参数

命令	标志	说明
session	--max-count (-n)	最近 N 条
session	--format	table/json
stats	--days	最近 N 天
stats	--tools	工具统计
stats	--models	模型用量
stats	--project	项目筛选

全局标志

标志	简写	作用说明
--help	-h	帮助
--version	-v	版本
--print-logs	—	输出日志
--log-level	—	日志级别

环境变量

变量	类型	作用
OPENCODE_AUTO_SHARE	boolean	自动分享
OPENCODE_CONFIG	string	配置路径
OPENCODE_TUI_CONFIG	string	TUI 配置
OPENCODE_DISABLE_AUTOUPDATE	boolean	禁用更新
OPENCODE_SERVER_PASSWORD	string	API 认证
OPENCODE_MODELS_URL	string	模型源

实验性功能

变量	类型	作用
OPENCODE_EXPERIMENTAL	boolean	启用全部实验功能
OPENCODE_EXPERIMENTAL_LSP_TOOL	boolean	LSP 工具
OPENCODE_EXPERIMENTAL_PLAN_MODE	boolean	规划模式
OPENCODE_EXPERIMENTAL_FILEWATCHER	boolean	文件监听

---

一、基础用法

1、启动 TUI（默认行为）

opencode

等同于进入交互式终端界面

2、指定项目目录

opencode /path/to/project

在指定目录中启动 TUI，例如在 opencode-runoob-test 目录中启动 ：

opencode opencode-runoob-test

3、非交互模式（脚本调用）

opencode run 解释一下 JavaScript 中闭包的原理

直接返回结果，不进入界面。

---

二、CLI 核心能力

OpenCode CLI 的核心能力可以总结为三类：

• **交互模式：**TUI（默认）
• **命令执行：**run / serve
• **系统管理：**agent / auth / session 等

---

三、常用参数（Flags）

参数	简写	说明
--continue	-c	继续上一个会话
--session	-s	指定会话 ID
--fork		从当前会话分叉
--model	-m	指定模型（provider/model）
--agent		指定代理
--port		服务端口
--hostname		监听地址

---

四、核心命令详解

1、run（最常用）

用于非交互执行：

opencode run 分析这个 Go 项目的上下文使用方式

适用场景：

• 脚本自动化
• CI/CD
• 快速问答

连接后台服务（避免冷启动）

# 启动后台服务
opencode serve

# 使用 run 连接
opencode run --attach http://localhost:4096 解释 async/await

常用参数

参数	说明
--model	指定模型
--file	附加文件
--format	输出格式（json / 默认）
--share	分享会话

五、auth（认证管理）

登录

opencode auth login

配置 API Key（存储在本地）

---

查看已登录提供商

opencode auth list

退出登录

opencode auth logout

---

六、models（模型管理）

查看所有模型

opencode models

按提供商筛选

opencode models anthropic

刷新模型列表

opencode models --refresh

---

七、agent（代理系统）

创建代理

opencode agent create

可自定义提示词 + 工具

查看代理

opencode agent list

---

八、session（会话管理）

查看会话

opencode session list

限制数量

opencode session list -n 10

---

九、serve（服务模式）

启动 API 服务：

opencode serve

提供 HTTP 接口（无界面）

可选参数：

• --port：端口
• --hostname：监听地址

---

十、web（Web UI）

opencode web

启动带网页界面的版本

---

十一、mcp（扩展能力）

添加 MCP 服务

opencode mcp add

查看列表

opencode mcp list

MCP 用于扩展 AI 能力（如工具调用）

---

十二、stats（使用统计）

opencode stats

查看 Token 使用量与费用

---

十三、export / import

导出会话

opencode export

导入会话

opencode import session.json

---

十四、升级与卸载

升级

opencode upgrade

卸载

opencode uninstall

---

十五、全局参数

参数	说明
--help	查看帮助
--version	查看版本
--log-level	日志级别

---

十六、环境变量（高级配置）

OpenCode 支持通过环境变量控制行为，例如：

OPENCODE_DISABLE_AUTOUPDATE=true
OPENCODE_SERVER_PASSWORD=123456

常见用途：

• 关闭自动更新
• 配置服务认证
• 自定义配置路径

---

十七、使用建议（重点）

• 日常开发使用 TUI
• 自动化使用 run
• 复杂任务结合 agent
• 高频调用使用 serve + attach

AI 思考中...

OpenCode TUI（终端界面）

OpenCode Web 使用