06-CLI命令参考

OpenCode 操作指导书（六）：CLI 命令参考

适用版本：OpenCode v1.18.3

本篇目标：掌握 OpenCode 全部命令行接口，便于脚本化、自动化与无界面（headless）使用。

1. 启动 TUI

bash 复制代码

opencode                 # 启动 TUI（默认）
opencode /path/to/project  # 直接打开某项目

常用 TUI 启动参数：

参数	简写	说明
`--continue`	`-c`	继续上一个会话
`--session`	`-s`	继续指定会话 ID
`--fork`		继续时 fork 会话
`--prompt`		启动即使用的提示词
`--model`	`-m`	指定模型 `provider/model`
`--agent`		指定 Agent
`--port`		监听端口
`--hostname`		监听主机名

2. 全局标志

标志	简写	说明
`--help`	`-h`	显示帮助
`--version`	`-v`	打印版本号
`--print-logs`		将日志打印到 stderr
`--log-level`		日志级别：`DEBUG`/`INFO`/`WARN`/`ERROR`

3. 子命令一览

#mermaid-svg-dVoLT5oDPUOFwO0d{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-dVoLT5oDPUOFwO0d .error-icon{fill:#552222;}#mermaid-svg-dVoLT5oDPUOFwO0d .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-dVoLT5oDPUOFwO0d .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-dVoLT5oDPUOFwO0d .marker{fill:#333333;stroke:#333333;}#mermaid-svg-dVoLT5oDPUOFwO0d .marker.cross{stroke:#333333;}#mermaid-svg-dVoLT5oDPUOFwO0d svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-dVoLT5oDPUOFwO0d p{margin:0;}#mermaid-svg-dVoLT5oDPUOFwO0d .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d .cluster-label text{fill:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d .cluster-label span{color:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d .cluster-label span p{background-color:transparent;}#mermaid-svg-dVoLT5oDPUOFwO0d .label text,#mermaid-svg-dVoLT5oDPUOFwO0d span{fill:#333;color:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d .node rect,#mermaid-svg-dVoLT5oDPUOFwO0d .node circle,#mermaid-svg-dVoLT5oDPUOFwO0d .node ellipse,#mermaid-svg-dVoLT5oDPUOFwO0d .node polygon,#mermaid-svg-dVoLT5oDPUOFwO0d .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-dVoLT5oDPUOFwO0d .rough-node .label text,#mermaid-svg-dVoLT5oDPUOFwO0d .node .label text,#mermaid-svg-dVoLT5oDPUOFwO0d .image-shape .label,#mermaid-svg-dVoLT5oDPUOFwO0d .icon-shape .label{text-anchor:middle;}#mermaid-svg-dVoLT5oDPUOFwO0d .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-dVoLT5oDPUOFwO0d .rough-node .label,#mermaid-svg-dVoLT5oDPUOFwO0d .node .label,#mermaid-svg-dVoLT5oDPUOFwO0d .image-shape .label,#mermaid-svg-dVoLT5oDPUOFwO0d .icon-shape .label{text-align:center;}#mermaid-svg-dVoLT5oDPUOFwO0d .node.clickable{cursor:pointer;}#mermaid-svg-dVoLT5oDPUOFwO0d .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-dVoLT5oDPUOFwO0d .arrowheadPath{fill:#333333;}#mermaid-svg-dVoLT5oDPUOFwO0d .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-dVoLT5oDPUOFwO0d .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-dVoLT5oDPUOFwO0d .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dVoLT5oDPUOFwO0d .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-dVoLT5oDPUOFwO0d .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dVoLT5oDPUOFwO0d .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-dVoLT5oDPUOFwO0d .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-dVoLT5oDPUOFwO0d .cluster text{fill:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d .cluster span{color:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-dVoLT5oDPUOFwO0d .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-dVoLT5oDPUOFwO0d rect.text{fill:none;stroke-width:0;}#mermaid-svg-dVoLT5oDPUOFwO0d .icon-shape,#mermaid-svg-dVoLT5oDPUOFwO0d .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dVoLT5oDPUOFwO0d .icon-shape p,#mermaid-svg-dVoLT5oDPUOFwO0d .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-dVoLT5oDPUOFwO0d .icon-shape .label rect,#mermaid-svg-dVoLT5oDPUOFwO0d .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dVoLT5oDPUOFwO0d .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-dVoLT5oDPUOFwO0d .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-dVoLT5oDPUOFwO0d :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} run
serve
web
agent
auth
mcp
models
session
stats
export
import
upgrade
uninstall
github
acp

4. run ------ 非交互执行

直接传入提示词运行，适合脚本/自动化：

bash 复制代码

opencode run "Explain how closures work in JavaScript"

连接已运行的服务以避免 MCP 冷启动：

bash 复制代码

opencode serve                       # 终端 A：启动无头服务
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"  # 终端 B

常用参数：--continue/-c、--session/-s、--fork、--share、--model/-m、--agent、--file/-f、--format default|json、--title、--attach <url>、--port。

5. serve / web / attach ------ 服务与界面

bash 复制代码

opencode serve                # 无头 HTTP 服务（API 访问，无 TUI）
opencode web                  # 带 Web 界面的无头服务（自动开浏览器）
opencode attach http://10.20.30.40:4096   # 将 TUI 连接到远程后端

设置 OPENCODE_SERVER_PASSWORD 启用 HTTP 基本认证（用户名默认 opencode）。
参数：--port、--hostname、--mdns（mDNS 发现）、--cors。

6. agent ------ Agent 管理

bash 复制代码

opencode agent create     # 交互式创建自定义 Agent
opencode agent list       # 列出所有 Agent

7. auth ------ 凭证管理

bash 复制代码

opencode auth login       # 交互式登录/配置提供方
opencode auth list        # 列出已认证提供方（ls）
opencode auth logout <provider>   # 注销某提供方

凭证存储：~/.local/share/opencode/auth.json。

8. mcp ------ MCP 服务管理

bash 复制代码

opencode mcp add          # 添加 MCP 服务（引导）
opencode mcp list         # 列出及连接状态（ls）
opencode mcp auth <name>  # OAuth 认证
opencode mcp auth list    # 列出支持 OAuth 的服务器（ls）
opencode mcp logout <name>
opencode mcp debug <name> # 调试 OAuth 连接

9. models ------ 模型查看

bash 复制代码

opencode models                  # 列出所有已配置提供方的模型
opencode models anthropic        # 按提供方筛选
opencode models --refresh        # 从 models.dev 刷新缓存
opencode models --verbose        # 含成本等元数据

10. session / stats ------ 会话与统计

bash 复制代码

opencode session list            # 列出会话（-n 限制数量，--format table|json）
opencode stats                   # token 用量与费用
opencode stats --days 7          # 最近 7 天
opencode stats --models 5        # 显示前 5 个模型明细
opencode stats --project ""      # 仅当前项目

11. export / import ------ 会话导入导出

bash 复制代码

opencode export <sessionID>      # 导出会话为 JSON（省略则交互选择）
opencode import session.json     # 从文件导入
opencode import https://opncd.ai/s/abc123   # 从分享链接导入

12. github ------ GitHub 自动化

bash 复制代码

opencode github install          # 在仓库中安装 GitHub Agent（引导）
opencode github run              # 在 Actions 中运行（--event / --token）

在 PR/Issue 评论中 @opencode 或 /oc 即可触发（详见第 07 篇）。

13. upgrade / uninstall ------ 升级与卸载

bash 复制代码

opencode upgrade                 # 升级到最新
opencode upgrade v1.18.3         # 升级到指定版本
opencode uninstall               # 卸载并删除相关文件
# 参数：--keep-config 保留配置 / --keep-data 保留数据 / --dry-run 仅预览 / --force 跳过确认

14. acp ------ Agent Client Protocol

bash 复制代码

opencode acp                    # 启动 ACP 服务（stdin/stdout，nd-JSON）
# 参数：--cwd / --port / --hostname

15. 环境变量速查

变量	作用
`OPENCODE_AUTO_SHARE`	自动分享会话
`OPENCODE_CONFIG`	配置文件路径
`OPENCODE_CONFIG_DIR`	配置目录
`OPENCODE_CONFIG_CONTENT`	内联 JSON 配置
`OPENCODE_DISABLE_AUTOUPDATE`	禁用自动更新检查
`OPENCODE_DISABLE_LSP_DOWNLOAD`	禁用自动 LSP 下载
`OPENCODE_ENABLE_EXA`	启用 Exa 网络搜索工具
`OPENCODE_SERVER_PASSWORD`	serve/web 基本认证
`OPENCODE_DISABLE_CLAUDE_CODE`	禁用读取 `.claude`（提示词+技能）

完整命令在手，进入 07-实战案例.md 把能力用起来。

本篇为 OpenCode 操作指导书系列之一，版本 v1.18.3。