06-CLI命令参考

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

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

1. 启动 TUI

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. 子命令一览

run

serve

web

agent

auth

mcp

models

session

stats

export

import

upgrade

uninstall

github

acp

4. run —— 非交互执行

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

opencode run"Explain how closures work in JavaScript"

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

opencode serve# 终端 A：启动无头服务opencode run--attachhttp://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 —— 服务与界面

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 管理

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

7. auth —— 凭证管理

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

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

8. mcp —— MCP 服务管理

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

9. models —— 模型查看

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

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

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

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

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

12. github —— GitHub 自动化

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

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

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

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

14. acp —— Agent Client Protocol

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_PASSWORDserve/web 基本认证
OPENCODE_DISABLE_CLAUDE_CODE禁用读取.claude（提示词+技能）

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

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