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