OpenCode: OpenCode CLI使用
最后更新：2026-08-31
OpenCode CLI 不仅是启动 TUI 的入口，更是一个可编程的 AI 开发接口。
1. 你将学到
- CLI 三层架构
- 核心命令详解
- run 命令与自动化
- 服务模式
- 环境变量
2. CLI 三层架构
| 层级 | 命令 | 说明 |
|---|---|---|
| 交互层 | tui / web / attach |
面向用户的交互界面 |
| 执行层 | run / agent / mcp / github |
执行具体任务 |
| 服务层 | serve / acp |
提供 API 服务 |
本质是一个 AI Agent + 本地开发环境 + 可编程 CLI + Server API 的统一入口。
3. 基础用法
(1) 启动 TUI（默认行为）
BASH
opencode
(2) 指定项目目录
BASH
opencode /path/to/project
(3) 非交互模式
BASH
opencode run 解释一下 JavaScript 中闭包的原理
直接返回结果，不进入界面。
4. 核心命令一览
| 命令 | 作用 | 关键子命令 |
|---|---|---|
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 |
导入会话 | — |
upgrade |
升级版本 | — |
uninstall |
卸载 | — |
5. run 命令（最常用）
用于非交互执行，适合脚本自动化和 CI/CD：
BASH
opencode run 分析这个 Go 项目的上下文使用方式
(1) 常用参数
| 参数 | 简写 | 说明 |
|---|---|---|
--continue |
-c |
继续会话 |
--session |
-s |
指定会话 |
--model |
-m |
指定模型 |
--agent |
— | 指定代理 |
--file |
-f |
附加文件 |
--format |
— | 输出格式（json） |
--share |
— | 分享会话 |
--attach |
— | 连接已有服务 |
(2) 连接后台服务
避免每次冷启动：
BASH
# 启动后台服务
opencode serve
# 使用 run 连接
opencode run --attach http://localhost:4096 解释 async/await
6. auth 命令
BASH
# 登录
opencode auth login
# 查看已登录提供商
opencode auth list
# 退出登录
opencode auth logout
7. models 命令
BASH
# 查看所有模型
opencode models
# 按提供商筛选
opencode models anthropic
# 刷新模型列表
opencode models --refresh
8. agent 命令
BASH
# 创建代理
opencode agent create
# 查看代理
opencode agent list
9. serve 命令
启动 API 服务，提供 HTTP 接口：
BASH
opencode serve
可选参数：
--port：端口--hostname：监听地址
10. web 命令
启动带网页界面的版本：
BASH
opencode web
11. stats 命令
查看 Token 使用量与费用：
BASH
opencode stats
# 最近 7 天
opencode stats --days 7
# 按模型统计
opencode stats --models
# 按工具统计
opencode stats --tools
12. TUI 启动参数
| 标志 | 简写 | 说明 |
|---|---|---|
--continue |
-c |
继续上次会话 |
--session |
-s |
指定会话 ID |
--fork |
— | 分叉会话 |
--prompt |
— | 初始提示词 |
--model |
-m |
指定模型 |
--agent |
— | 指定代理 |
--port |
— | 监听端口 |
13. 全局标志
| 标志 | 简写 | 说明 |
|---|---|---|
--help |
-h |
查看帮助 |
--version |
-v |
查看版本 |
--print-logs |
— | 输出日志 |
--log-level |
— | 日志级别 |
14. 环境变量
| 变量 | 类型 | 作用 |
|---|---|---|
OPENCODE_AUTO_SHARE |
boolean | 自动分享 |
OPENCODE_CONFIG |
string | 配置路径 |
OPENCODE_DISABLE_AUTOUPDATE |
boolean | 禁用更新 |
OPENCODE_SERVER_PASSWORD |
string | API 认证 |
OPENCODE_MODELS_URL |
string | 模型源 |
OPENCODE_EXPERIMENTAL |
boolean | 启用实验功能 |
15. 使用建议
| 场景 | 推荐命令 |
|---|---|
| 日常开发 | opencode（TUI） |
| 自动化/脚本 | opencode run |
| CI/CD 集成 | opencode serve + run --attach |
| 高频调用 | opencode serve + 客户端 |
| Web 界面 | opencode web |
❓ 常见问题
Q run 命令和 TUI 有什么区别？
A run 是非交互模式，输入问题后直接返回结果，适合脚本和自动化；TUI 是交互模式，支持多轮对话和斜杠命令。
Q 如何在 CI/CD 中使用 OpenCode？
A 先启动
opencode serve，然后通过 opencode run --attach 连接服务执行任务。避免每次冷启动。Q Alice 用 run 做代码审查，Bob 用 TUI 做开发，谁更高效？
A 各有所长。Alice 的 run 模式适合批量自动化审查，Bob 的 TUI 模式适合交互式开发。根据场景选择。
📖 小节
- CLI 三层：交互层、执行层、服务层
opencode run是自动化的核心命令opencode serve提供 API 服务，避免冷启动- 环境变量适合 CI/CD 和临时配置
- 日常用 TUI，自动化用 run，高频用 serve
📝 作业
-
基础题：使用
opencode run执行一次非交互式代码分析。 -
进阶题：启动
opencode serve，然后通过run --attach连接执行任务。 -
挑战题：编写一个 Shell 脚本，使用
opencode run自动分析项目代码并生成报告。
