---
title: "使用 CLI"
description: "整理 OpenCode CLI 的常用命令、启动参数和适合新手的最小验证流程。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **这一篇用 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 个必要工具 |

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

## CLI 入口地图

```mermaid
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` 之间切换。

## 第一次先做最小验证

安装后先确认命令可用：

```bash
opencode --help
opencode --version
```

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

```bash
cd /path/to/project
opencode
```

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

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

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

## TUI：默认交互入口

```bash
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 里的只读任务，或者你只想快速问一个问题：

```bash
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 特定推理能力时再用。

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

## auth 和 models：先把 provider 管清楚

登录 provider：

```bash
opencode auth login
opencode auth list
```

退出 provider：

```bash
opencode auth logout
```

查看模型：

```bash
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、数据库或内部服务。

```bash
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 服务：

```bash
opencode serve
```

`web` 启动带 Web UI 的后端：

```bash
opencode web
```

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

```bash
opencode attach http://localhost:4096
```

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

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

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

> [!WARNING]
> 不要在没有认证的情况下把 `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 解决项目专属问题。
- 升级、卸载、导出会话前没有看影响范围。

## 接下来去哪

<Cards>
  <Card title="入门" href="/docs/opencode/official/00-getting-started">
    从安装、provider、初始化和第一轮 TUI 使用建立完整闭环。
  </Card>
  <Card title="终端 TUI" href="/docs/opencode/official/00-getting-started/tui">
    理解 TUI 里的快捷键、模式切换、会话和工具交互。
  </Card>
  <Card title="连接 MCP 服务器" href="/docs/opencode/official/04-tools-mcp/mcp-servers">
    当内置工具不够用时，再把外部系统接入 OpenCode。
  </Card>
  <Card title="Server API" href="/docs/opencode/official/07-sdk/server">
    如果要把 OpenCode 接到自动化系统，再继续看 server 接口。
  </Card>
</Cards>

## 官方资料

- [OpenCode CLI](https://opencode.ai/docs/cli/)
- [OpenCode TUI](https://opencode.ai/docs/tui/)
- [OpenCode server](https://opencode.ai/docs/server/)
- [OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/)
