605 lines
17 KiB
Markdown
605 lines
17 KiB
Markdown
---
|
||
title: CLI
|
||
description: OpenCode CLI 選項和指令。
|
||
---
|
||
|
||
import { Tabs, TabItem } from "@astrojs/starlight/components"
|
||
|
||
OpenCode CLI 在不帶任何參數執行時，預設啟動 [TUI](/docs/tui)。
|
||
|
||
```bash
|
||
opencode
|
||
```
|
||
|
||
但它也接受本頁面中記錄的指令，使您可以透過程式方式與 OpenCode 進行互動。
|
||
|
||
```bash
|
||
opencode run "Explain how closures work in JavaScript"
|
||
```
|
||
|
||
---
|
||
|
||
### tui
|
||
|
||
啟動 OpenCode 終端機使用者介面。
|
||
|
||
```bash
|
||
opencode [project]
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| ------------ | ---- | ------------------------------------------------------------- |
|
||
| `--continue` | `-c` | 繼續上一個工作階段 |
|
||
| `--session` | `-s` | 要繼續的工作階段 ID |
|
||
| `--fork` | | 繼續時分岔工作階段（與 `--continue` 或 `--session` 搭配使用） |
|
||
| `--prompt` | | 要使用的提示詞 |
|
||
| `--model` | `-m` | 要使用的模型，格式為 provider/model |
|
||
| `--agent` | | 要使用的代理 |
|
||
| `--port` | | 監聽連接埠 |
|
||
| `--hostname` | | 監聽主機名稱 |
|
||
|
||
---
|
||
|
||
## 指令
|
||
|
||
OpenCode CLI 還提供以下指令。
|
||
|
||
---
|
||
|
||
### agent
|
||
|
||
管理 OpenCode 的代理。
|
||
|
||
```bash
|
||
opencode agent [command]
|
||
```
|
||
|
||
---
|
||
|
||
### attach
|
||
|
||
將終端機連接到已透過 `serve` 或 `web` 指令啟動的 OpenCode 後端伺服器。
|
||
|
||
```bash
|
||
opencode attach [url]
|
||
```
|
||
|
||
這允許將 TUI 與遠端 OpenCode 後端搭配使用。例如：
|
||
|
||
```bash
|
||
# Start the backend server for web/mobile access
|
||
opencode web --port 4096 --hostname 0.0.0.0
|
||
|
||
# In another terminal, attach the TUI to the running backend
|
||
opencode attach http://10.20.30.40:4096
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| ----------- | ---- | ------------------- |
|
||
| `--dir` | | 啟動 TUI 的工作目錄 |
|
||
| `--session` | `-s` | 要繼續的工作階段 ID |
|
||
|
||
---
|
||
|
||
#### create
|
||
|
||
使用自訂設定建立新的代理。
|
||
|
||
```bash
|
||
opencode agent create
|
||
```
|
||
|
||
此指令將引導您使用自訂系統提示詞和工具設定來建立新的代理。
|
||
|
||
---
|
||
|
||
#### list
|
||
|
||
列出所有可用的代理。
|
||
|
||
```bash
|
||
opencode agent list
|
||
```
|
||
|
||
---
|
||
|
||
### auth
|
||
|
||
管理供應商的憑證和登入資訊的指令。
|
||
|
||
```bash
|
||
opencode auth [command]
|
||
```
|
||
|
||
---
|
||
|
||
#### login
|
||
|
||
OpenCode 基於 [Models.dev](https://models.dev) 的供應商列表運作，因此您可以使用 `opencode auth login` 為任何想要使用的供應商設定 API 金鑰。金鑰儲存在 `~/.local/share/opencode/auth.json` 中。
|
||
|
||
```bash
|
||
opencode auth login
|
||
```
|
||
|
||
OpenCode 啟動時會從憑證檔案載入供應商資訊，同時也會載入環境變數或專案中 `.env` 檔案中定義的金鑰。
|
||
|
||
---
|
||
|
||
#### list
|
||
|
||
列出憑證檔案中儲存的所有已認證供應商。
|
||
|
||
```bash
|
||
opencode auth list
|
||
```
|
||
|
||
或使用簡寫版本。
|
||
|
||
```bash
|
||
opencode auth ls
|
||
```
|
||
|
||
---
|
||
|
||
#### logout
|
||
|
||
從憑證檔案中清除供應商資訊以完成登出。
|
||
|
||
```bash
|
||
opencode auth logout
|
||
```
|
||
|
||
---
|
||
|
||
### github
|
||
|
||
管理用於儲存庫自動化的 GitHub 代理。
|
||
|
||
```bash
|
||
opencode github [command]
|
||
```
|
||
|
||
---
|
||
|
||
#### install
|
||
|
||
在您的儲存庫中安裝 GitHub 代理。
|
||
|
||
```bash
|
||
opencode github install
|
||
```
|
||
|
||
此指令會設定必要的 GitHub Actions 工作流程並引導您完成設定過程。[了解更多](/docs/github)。
|
||
|
||
---
|
||
|
||
#### run
|
||
|
||
執行 GitHub 代理。通常在 GitHub Actions 中使用。
|
||
|
||
```bash
|
||
opencode github run
|
||
```
|
||
|
||
##### 旗標
|
||
|
||
| 旗標 | 說明 |
|
||
| --------- | ------------------------------ |
|
||
| `--event` | 用於執行代理的 GitHub 模擬事件 |
|
||
| `--token` | GitHub 個人存取權杖 |
|
||
|
||
---
|
||
|
||
### mcp
|
||
|
||
管理 Model Context Protocol 伺服器。
|
||
|
||
```bash
|
||
opencode mcp [command]
|
||
```
|
||
|
||
---
|
||
|
||
#### add
|
||
|
||
將 MCP 伺服器新增到您的設定中。
|
||
|
||
```bash
|
||
opencode mcp add
|
||
```
|
||
|
||
此指令將引導您新增本地或遠端 MCP 伺服器。
|
||
|
||
---
|
||
|
||
#### list
|
||
|
||
列出所有已設定的 MCP 伺服器及其連線狀態。
|
||
|
||
```bash
|
||
opencode mcp list
|
||
```
|
||
|
||
或使用簡寫版本。
|
||
|
||
```bash
|
||
opencode mcp ls
|
||
```
|
||
|
||
---
|
||
|
||
#### auth
|
||
|
||
對支援 OAuth 的 MCP 伺服器進行認證。
|
||
|
||
```bash
|
||
opencode mcp auth [name]
|
||
```
|
||
|
||
如果您不提供伺服器名稱，系統將提示您從可用的支援 OAuth 的伺服器中進行選擇。
|
||
|
||
您還可以列出支援 OAuth 的伺服器及其認證狀態。
|
||
|
||
```bash
|
||
opencode mcp auth list
|
||
```
|
||
|
||
或使用簡寫版本。
|
||
|
||
```bash
|
||
opencode mcp auth ls
|
||
```
|
||
|
||
---
|
||
|
||
#### logout
|
||
|
||
移除 MCP 伺服器的 OAuth 憑證。
|
||
|
||
```bash
|
||
opencode mcp logout [name]
|
||
```
|
||
|
||
---
|
||
|
||
#### debug
|
||
|
||
偵錯 MCP 伺服器的 OAuth 連線問題。
|
||
|
||
```bash
|
||
opencode mcp debug <name>
|
||
```
|
||
|
||
---
|
||
|
||
### models
|
||
|
||
列出已設定供應商的所有可用模型。
|
||
|
||
```bash
|
||
opencode models [provider]
|
||
```
|
||
|
||
此指令以 `provider/model` 的格式顯示所有已設定供應商中可用的模型。
|
||
|
||
這對於確定在[設定檔](/docs/config/)中使用的確切模型名稱非常有用。
|
||
|
||
您可以選擇傳入供應商 ID 來按供應商篩選模型。
|
||
|
||
```bash
|
||
opencode models anthropic
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 說明 |
|
||
| ----------- | ------------------------------------------ |
|
||
| `--refresh` | 從 models.dev 重新整理模型快取 |
|
||
| `--verbose` | 使用更詳細的模型輸出（包含費用等中繼資料） |
|
||
|
||
使用 `--refresh` 旗標可以更新快取的模型列表。當供應商新增了模型並且您希望在 OpenCode 中看到它們時，此功能非常有用。
|
||
|
||
```bash
|
||
opencode models --refresh
|
||
```
|
||
|
||
---
|
||
|
||
### run
|
||
|
||
以非互動模式執行 OpenCode，直接傳入提示詞。
|
||
|
||
```bash
|
||
opencode run [message..]
|
||
```
|
||
|
||
這對於指令碼編寫、自動化或無需啟動完整 TUI 即可快速取得答案的情境非常有用。例如：
|
||
|
||
```bash "opencode run"
|
||
opencode run Explain the use of context in Go
|
||
```
|
||
|
||
您還可以連接到正在執行的 `opencode serve` 實例，以避免每次執行時 MCP 伺服器的冷啟動時間：
|
||
|
||
```bash
|
||
# Start a headless server in one terminal
|
||
opencode serve
|
||
|
||
# In another terminal, run commands that attach to it
|
||
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| ------------ | ---- | -------------------------------------------------------------- |
|
||
| `--command` | | 要執行的指令，使用 message 作為參數 |
|
||
| `--continue` | `-c` | 繼續上一個工作階段 |
|
||
| `--session` | `-s` | 要繼續的工作階段 ID |
|
||
| `--fork` | | 繼續時分岔工作階段（與 `--continue` 或 `--session` 搭配使用） |
|
||
| `--share` | | 分享工作階段 |
|
||
| `--model` | `-m` | 要使用的模型，格式為 provider/model |
|
||
| `--agent` | | 要使用的代理 |
|
||
| `--file` | `-f` | 附加到訊息的檔案 |
|
||
| `--format` | | 格式：default（格式化輸出）或 json（原始 JSON 事件） |
|
||
| `--title` | | 工作階段標題（未提供值時使用截斷的提示詞） |
|
||
| `--attach` | | 連接到正在執行的 opencode 伺服器（例如 http://localhost:4096） |
|
||
| `--port` | | 本地伺服器連接埠（預設為隨機連接埠） |
|
||
|
||
---
|
||
|
||
### serve
|
||
|
||
啟動無介面的 OpenCode 伺服器以提供 API 存取。查看[伺服器文件](/docs/server)了解完整的 HTTP 介面。
|
||
|
||
```bash
|
||
opencode serve
|
||
```
|
||
|
||
此指令啟動一個 HTTP 伺服器，提供對 OpenCode 功能的 API 存取，無需 TUI 介面。設定 `OPENCODE_SERVER_PASSWORD` 可啟用 HTTP 基本認證（使用者名稱預設為 `opencode`）。
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 說明 |
|
||
| ------------ | -------------------------- |
|
||
| `--port` | 監聽連接埠 |
|
||
| `--hostname` | 監聽主機名稱 |
|
||
| `--mdns` | 啟用 mDNS 探索 |
|
||
| `--cors` | 允許 CORS 的額外瀏覽器來源 |
|
||
|
||
---
|
||
|
||
### session
|
||
|
||
管理 OpenCode 工作階段。
|
||
|
||
```bash
|
||
opencode session [command]
|
||
```
|
||
|
||
---
|
||
|
||
#### list
|
||
|
||
列出所有 OpenCode 工作階段。
|
||
|
||
```bash
|
||
opencode session list
|
||
```
|
||
|
||
##### 旗標
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| ------------- | ---- | ------------------------------------- |
|
||
| `--max-count` | `-n` | 限制為最近 N 個工作階段 |
|
||
| `--format` | | 輸出格式：table 或 json（預設 table） |
|
||
|
||
---
|
||
|
||
### stats
|
||
|
||
顯示 OpenCode 工作階段的 Token 用量和費用統計資訊。
|
||
|
||
```bash
|
||
opencode stats
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 說明 |
|
||
| ----------- | ---------------------------------------------------- |
|
||
| `--days` | 顯示最近 N 天的統計資訊（預設為所有時間） |
|
||
| `--tools` | 顯示的工具數量（預設為全部） |
|
||
| `--models` | 顯示模型用量明細（預設隱藏）。傳入數字可顯示前 N 個 |
|
||
| `--project` | 按專案篩選（預設為所有專案，傳入空字串表示當前專案） |
|
||
|
||
---
|
||
|
||
### export
|
||
|
||
將工作階段資料匯出為 JSON。
|
||
|
||
```bash
|
||
opencode export [sessionID]
|
||
```
|
||
|
||
如果您不提供工作階段 ID，系統將提示您從可用的工作階段中進行選擇。
|
||
|
||
---
|
||
|
||
### import
|
||
|
||
從 JSON 檔案或 OpenCode 分享連結匯入工作階段資料。
|
||
|
||
```bash
|
||
opencode import <file>
|
||
```
|
||
|
||
您可以從本地檔案或 OpenCode 分享連結匯入。
|
||
|
||
```bash
|
||
opencode import session.json
|
||
opencode import https://opncd.ai/s/abc123
|
||
```
|
||
|
||
---
|
||
|
||
### web
|
||
|
||
啟動帶有 Web 介面的無介面 OpenCode 伺服器。
|
||
|
||
```bash
|
||
opencode web
|
||
```
|
||
|
||
此指令啟動一個 HTTP 伺服器並開啟瀏覽器，透過 Web 介面存取 OpenCode。設定 `OPENCODE_SERVER_PASSWORD` 可啟用 HTTP 基本認證（使用者名稱預設為 `opencode`）。
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 說明 |
|
||
| ------------ | -------------------------- |
|
||
| `--port` | 監聽連接埠 |
|
||
| `--hostname` | 監聽主機名稱 |
|
||
| `--mdns` | 啟用 mDNS 探索 |
|
||
| `--cors` | 允許 CORS 的額外瀏覽器來源 |
|
||
|
||
---
|
||
|
||
### acp
|
||
|
||
啟動 ACP（Agent Client Protocol）伺服器。
|
||
|
||
```bash
|
||
opencode acp
|
||
```
|
||
|
||
此指令啟動一個透過 stdin/stdout 使用 nd-JSON 進行通訊的 ACP 伺服器。
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 說明 |
|
||
| ------------ | ------------ |
|
||
| `--cwd` | 工作目錄 |
|
||
| `--port` | 監聽連接埠 |
|
||
| `--hostname` | 監聽主機名稱 |
|
||
|
||
---
|
||
|
||
### uninstall
|
||
|
||
解除安裝 OpenCode 並刪除所有相關檔案。
|
||
|
||
```bash
|
||
opencode uninstall
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| --------------- | ---- | ------------------------------ |
|
||
| `--keep-config` | `-c` | 保留設定檔 |
|
||
| `--keep-data` | `-d` | 保留工作階段資料和快照 |
|
||
| `--dry-run` | | 顯示將被刪除的內容但不實際刪除 |
|
||
| `--force` | `-f` | 跳過確認提示 |
|
||
|
||
---
|
||
|
||
### upgrade
|
||
|
||
將 OpenCode 更新到最新版本或指定版本。
|
||
|
||
```bash
|
||
opencode upgrade [target]
|
||
```
|
||
|
||
更新到最新版本。
|
||
|
||
```bash
|
||
opencode upgrade
|
||
```
|
||
|
||
更新到指定版本。
|
||
|
||
```bash
|
||
opencode upgrade v0.1.48
|
||
```
|
||
|
||
#### 旗標
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| ---------- | ---- | ------------------------------------------ |
|
||
| `--method` | `-m` | 使用的安裝方式：curl、npm、pnpm、bun、brew |
|
||
|
||
---
|
||
|
||
## 全域旗標
|
||
|
||
OpenCode CLI 接受以下全域旗標。
|
||
|
||
| 旗標 | 簡寫 | 說明 |
|
||
| -------------- | ---- | ------------------------------------ |
|
||
| `--help` | `-h` | 顯示說明資訊 |
|
||
| `--version` | `-v` | 印出版本號 |
|
||
| `--print-logs` | | 將日誌輸出到 stderr |
|
||
| `--log-level` | | 日誌等級（DEBUG、INFO、WARN、ERROR） |
|
||
|
||
---
|
||
|
||
## 環境變數
|
||
|
||
OpenCode 可以透過環境變數進行設定。
|
||
|
||
| 變數 | 類型 | 說明 |
|
||
| ------------------------------------- | ------- | ------------------------------------------- |
|
||
| `OPENCODE_AUTO_SHARE` | boolean | 自動分享工作階段 |
|
||
| `OPENCODE_GIT_BASH_PATH` | string | Windows 上 Git Bash 可執行檔的路徑 |
|
||
| `OPENCODE_CONFIG` | string | 設定檔路徑 |
|
||
| `OPENCODE_TUI_CONFIG` | string | TUI 設定檔路徑 |
|
||
| `OPENCODE_CONFIG_DIR` | string | 設定目錄路徑 |
|
||
| `OPENCODE_CONFIG_CONTENT` | string | 內嵌 JSON 設定內容 |
|
||
| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | 停用自動更新檢查 |
|
||
| `OPENCODE_DISABLE_PRUNE` | boolean | 停用舊資料清理 |
|
||
| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | 停用自動終端機標題更新 |
|
||
| `OPENCODE_PERMISSION` | string | 內嵌 JSON 權限設定 |
|
||
| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | 停用預設外掛程式 |
|
||
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | 停用 LSP 伺服器自動下載 |
|
||
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | 啟用實驗性模型 |
|
||
| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | 停用自動上下文壓縮 |
|
||
| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | 停用讀取 `.claude`（提示詞 + 技能） |
|
||
| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | 停用讀取 `~/.claude/CLAUDE.md` |
|
||
| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | 停用載入 `.claude/skills` |
|
||
| `OPENCODE_DISABLE_MODELS_FETCH` | boolean | 停用從遠端來源擷取模型 |
|
||
| `OPENCODE_FAKE_VCS` | string | 用於測試目的的模擬 VCS 供應商 |
|
||
| `OPENCODE_DISABLE_FILETIME_CHECK` | boolean | 停用檔案時間檢查最佳化 |
|
||
| `OPENCODE_CLIENT` | string | 用戶端識別碼（預設為 `cli`） |
|
||
| `OPENCODE_ENABLE_EXA` | boolean | 啟用 Exa 網路搜尋工具 |
|
||
| `OPENCODE_SERVER_PASSWORD` | string | 為 `serve`/`web` 啟用基本認證 |
|
||
| `OPENCODE_SERVER_USERNAME` | string | 覆寫基本認證使用者名稱（預設為 `opencode`） |
|
||
| `OPENCODE_MODELS_URL` | string | 自訂模型設定擷取 URL |
|
||
|
||
---
|
||
|
||
### 實驗性功能
|
||
|
||
這些環境變數用於啟用可能會變更或移除的實驗性功能。
|
||
|
||
| 變數 | 類型 | 說明 |
|
||
| ----------------------------------------------- | ------- | ------------------------------- |
|
||
| `OPENCODE_EXPERIMENTAL` | boolean | 啟用所有實驗性功能 |
|
||
| `OPENCODE_EXPERIMENTAL_ICON_DISCOVERY` | boolean | 啟用圖示探索 |
|
||
| `OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT` | boolean | 停用 TUI 中的選取即複製 |
|
||
| `OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number | bash 指令的預設逾時時間（毫秒） |
|
||
| `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | number | LLM 回應的最大輸出 Token 數 |
|
||
| `OPENCODE_EXPERIMENTAL_FILEWATCHER` | boolean | 啟用整個目錄的檔案監看器 |
|
||
| `OPENCODE_EXPERIMENTAL_OXFMT` | boolean | 啟用 oxfmt 格式化器 |
|
||
| `OPENCODE_EXPERIMENTAL_LSP_TOOL` | boolean | 啟用實驗性 LSP 工具 |
|
||
| `OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | 停用檔案監看器 |
|
||
| `OPENCODE_EXPERIMENTAL_EXA` | boolean | 啟用實驗性 Exa 功能 |
|
||
| `OPENCODE_EXPERIMENTAL_LSP_TY` | boolean | 為 python 檔案啟用 TY LSP |
|
||
| `OPENCODE_EXPERIMENTAL_MARKDOWN` | boolean | 啟用實驗性 Markdown 功能 |
|
||
| `OPENCODE_EXPERIMENTAL_PLAN_MODE` | boolean | 啟用計畫模式 |
|