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：遠端使用要先管認證會話和運維命令擴充套件和自動化命令全域性標誌和環境變數新手常見坑接下來去哪官方資料