AI 编程教程中文版
官方教程中文版入门

使用 CLI

整理 OpenCode CLI 的常用命令、启动参数和适合新手的最小验证流程。

OpenCode CLI 有两种用法：不带参数时进入 TUI；带子命令时可以做非交互运行、凭据管理、MCP 管理、服务器启动、会话导入导出和插件安装。

这一篇用 12 分钟换什么：你会知道第一次应该跑哪些命令，TUI、run、serve、web、attach 分别适合什么场景，以及哪些危险参数不该随手用。

先给结论：先会 6 个入口就够

新手不用背完整 CLI。先把这 6 个入口用熟：

入口用途第一次建议
opencode启动 TUI默认入口
opencode run非交互执行一次任务先做只读解释
opencode auth管理 provider 凭据用 login / list 验证
opencode models查看可用模型名配模型前先确认名称
opencode serve / web启动后端或 Web UI只在理解认证后开放端口
opencode mcp管理 MCP server先只接 1-3 个必要工具

CLI 不是越多越高级。第一次上手先完成“命令可用、provider 可用、只读任务可控、低风险写入可回滚”这条闭环。

CLI 入口地图

flowchart TB
  CLI[opencode CLI] --> TUI[opencode<br/>交互式 TUI]
  CLI --> Run[opencode run<br/>脚本和一次性任务]
  CLI --> Auth[opencode auth<br/>provider 凭据]
  CLI --> Models[opencode models<br/>模型列表]
  CLI --> MCP[opencode mcp<br/>外部工具接入]
  CLI --> Server[serve / web / attach<br/>远程和 Web 使用]
  CLI --> Ops[session / stats / export / import<br/>会话运维]
  CLI --> Ext[agent / plugin / github / pr<br/>扩展和自动化]

如果你只是日常写代码，80% 时间会在 opencode 和 opencode run 之间切换。

第一次先做最小验证

安装后先确认命令可用：

opencode --help
opencode --version

进入真实 Git 仓库后启动 TUI：

cd /path/to/project
opencode

不想进入 TUI，只想跑一次只读问题，可以用 run：

opencode run "Explain the structure of this repository. Do not edit files."

如果这三步都稳定，再继续配置 provider、rules、agents、skills、MCP 或 plugin。

TUI：默认交互入口

opencode [project]

不带参数运行时，OpenCode 默认启动终端 TUI。常用参数只需要先记住这些：

  • --continue / -c：继续上一个会话。
  • --session / -s：继续指定会话。
  • --fork：继续会话时分叉（把当前会话复制成独立分支，原会话保留不动；适合"我想试一个新方向但不想丢掉之前的对话"）。
  • --model / -m：指定 provider/model。
  • --agent：指定 Agent。
  • --prompt：启动时带一段提示词。
  • --port、--hostname、--mdns、--cors：涉及服务和网络时再用。

新手不要一开始就指定太多参数。先确认默认 TUI 能稳定读取项目，再逐步加模型、Agent 和端口配置。

run：非交互任务入口

run 适合脚本、批量检查、CI 里的只读任务，或者你只想快速问一个问题：

opencode run "List the likely test command for this project. Do not edit files."

常用能力：

  • --file / -f：把文件附加到消息。
  • --format json：输出原始 JSON 事件，适合脚本处理。
  • --command：运行一个 OpenCode command，并把 message 作为参数。
  • --continue、--session、--fork：复用或分叉会话。
  • --attach：连接到已经运行的 serve 实例，减少 MCP 冷启动。
  • --variant、--thinking：需要 provider 特定推理能力时再用。

--dangerously-skip-permissions 会自动批准未明确拒绝的权限。真实项目里不要把它当成省事参数。

auth 和 models：先把 provider 管清楚

登录 provider：

opencode auth login
opencode auth list

退出 provider：

opencode auth logout

查看模型：

opencode models
opencode models anthropic
opencode models --refresh
opencode models --verbose

OpenCode 的 provider 列表来自 Models.dev。配 opencode.json 前，先用 models 确认模型名，避免写错 provider/model。

mcp：外部工具接入入口

MCP 用来把外部系统接进 OpenCode，例如文档搜索、GitHub、Sentry、数据库或内部服务。

opencode mcp add
opencode mcp list
opencode mcp auth <name>
opencode mcp debug <name>
opencode mcp logout <name>

新手原则：

  • 内置工具能解决的问题，不接 MCP。
  • 第一次只接 1-3 个必要 MCP。
  • 先验证查询类工具，再考虑写入类工具。
  • OAuth 或 API key 不要写进教程、仓库或截图。

serve、web 和 attach：远程使用要先管认证

serve 启动无界面 HTTP 服务：

opencode serve

web 启动带 Web UI 的后端：

opencode web

attach 把终端 TUI 连到已经运行的后端：

opencode attach http://localhost:4096

如果要绑定到局域网地址或公网地址，先设置认证：

export OPENCODE_SERVER_PASSWORD="change-me"
opencode web --port 4096 --hostname 0.0.0.0

OPENCODE_SERVER_USERNAME 可以覆盖默认用户名，默认用户名是 opencode。

不要在没有认证的情况下把 serve 或 web 绑定到 0.0.0.0。这会把你的项目上下文和工具能力暴露给网络。

会话和运维命令

这些命令不需要每天用，但排障和迁移时很有用：

  • opencode session list：列出会话，可配 --max-count 和 --format json。
  • opencode session delete <sessionID>：删除指定会话。
  • opencode stats：查看 token 和费用统计，可按天、工具、模型或项目筛选。
  • opencode export [sessionID]：导出会话，--sanitize 可脱敏 transcript / file data。
  • opencode import <file>：从 JSON 文件或分享链接导入会话。

导出会话前先想清楚是否包含私有代码、路径、密钥片段或客户信息。

扩展和自动化命令

这些命令适合已经跑通基础流程后再用：

  • opencode agent create / agent list：创建或查看 Agent。非交互创建时可以传 --path、--description、--mode、--permissions、--model。
  • opencode plugin <module> / opencode plug <module>：安装插件并更新配置。--global 会影响全局，--force 会替换已有版本。
  • opencode github install / github run：安装或运行 GitHub agent，通常配合 GitHub Actions。
  • opencode pr <number>：拉取并 checkout GitHub PR 分支，然后运行 OpenCode。
  • opencode acp：启动 ACP server。
  • opencode db / db path：数据库工具，主要用于调试。
  • opencode debug：调试工具入口。
  • opencode upgrade：升级到最新或指定版本。
  • opencode uninstall：卸载，可用 --dry-run、--keep-config、--keep-data 先确认影响。

插件、GitHub 自动化、ACP、数据库工具都属于进阶入口。不要在第一天全配上。

全局标志和环境变量

常用全局标志：

  • --help / -h：帮助。
  • --version / -v：版本。
  • --print-logs：把日志输出到 stderr。
  • --log-level：设置日志级别。
  • --pure：不加载外部插件运行，适合排查插件问题。

常用环境变量可以按用途分组记：

  • 配置位置：OPENCODE_CONFIG、OPENCODE_TUI_CONFIG、OPENCODE_CONFIG_DIR、OPENCODE_CONFIG_CONTENT。
  • 权限和兼容：OPENCODE_PERMISSION、OPENCODE_DISABLE_CLAUDE_CODE、OPENCODE_DISABLE_CLAUDE_CODE_PROMPT、OPENCODE_DISABLE_CLAUDE_CODE_SKILLS。
  • 服务器认证：OPENCODE_SERVER_PASSWORD、OPENCODE_SERVER_USERNAME。
  • 行为开关：OPENCODE_DISABLE_AUTOUPDATE、OPENCODE_DISABLE_AUTOCOMPACT、OPENCODE_DISABLE_DEFAULT_PLUGINS、OPENCODE_DISABLE_MOUSE。
  • 模型和工具：OPENCODE_ENABLE_EXPERIMENTAL_MODELS、OPENCODE_DISABLE_MODELS_FETCH、OPENCODE_ENABLE_EXA、OPENCODE_MODELS_URL。

实验性环境变量可能变化或移除，只在你明确知道影响时启用。

新手常见坑

  • 把 CLI 参考当成学习路径，结果第一天就研究所有命令。
  • run 没写“不要改文件”，却拿它做真实仓库检查。
  • 把 serve / web 暴露到网络但没设置密码。
  • 一次性接太多 MCP，模型开始乱选工具。
  • 用全局 plugin 解决项目专属问题。
  • 升级、卸载、导出会话前没有看影响范围。

接下来去哪

入门

从安装、provider、初始化和第一轮 TUI 使用建立完整闭环。

终端 TUI

理解 TUI 里的快捷键、模式切换、会话和工具交互。

连接 MCP 服务器

当内置工具不够用时，再把外部系统接入 OpenCode。

Server API

如果要把 OpenCode 接到自动化系统，再继续看 server 接口。

官方资料

入门

汇总 OpenCode 入门路径，按 CLI、TUI、分享和 IDE 入口建立第一条可运行闭环。

使用 TUI

说明 OpenCode 终端界面的基本操作、常见状态和新手第一次使用的检查点。

本页目录

先给结论：先会 6 个入口就够CLI 入口地图第一次先做最小验证TUI：默认交互入口run：非交互任务入口auth 和 models：先把 provider 管清楚mcp：外部工具接入入口serve、web 和 attach：远程使用要先管认证会话和运维命令扩展和自动化命令全局标志和环境变量新手常见坑接下来去哪官方资料