---
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="/zh-Hant/docs/opencode/official/00-getting-started">
    從安裝、provider、初始化和第一輪 TUI 使用建立完整閉環。
  </Card>
  <Card title="終端 TUI" href="/zh-Hant/docs/opencode/official/00-getting-started/tui">
    理解 TUI 裡的快捷鍵、模式切換、會話和工具互動。
  </Card>
  <Card title="連線 MCP 伺服器" href="/zh-Hant/docs/opencode/official/04-tools-mcp/mcp-servers">
    當內建工具不夠用時，再把外部系統接入 OpenCode。
  </Card>
  <Card title="Server API" href="/zh-Hant/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/)
