# OpenCode：安裝、模型與首次啟動

> 在 macOS、Linux 與 Windows 上安裝、OpenCode 1.x 與 2.0、連接供應商與 Ollama、設定、費用及疑難排解。

Source: https://ailoot.ai/blog/zh-hant-tw/opencode-installation-models/
Canonical: https://ailoot.ai/blog/zh-hant-tw/opencode-installation-models/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-190
Revision: sha256-30ce49e577bb51f31262bc494f95b432f3e7077eb250e48cb0692f17677f6c6e


OpenCode 是一款開源的終端機 AI 程式設計代理：工具本身免費（MIT 授權），而且你可以連接任何模型，從 Claude、GPT 到透過 Ollama 執行的本機模型都可以。這個專案的 GitHub 儲存庫星數已超過二十萬。「可使用任何模型的免費 Claude Code」聽起來很吸引人，但需要說明清楚：工具免費；使用條款則取決於你選擇的模型。

以下內容均依據官方文件：介紹這款工具、如何在 macOS、Linux 或 Windows 上安裝、如何連接模型，以及首次啟動時該做什麼。文中另設費用專節，因為這裡的「免費」只適用於工具本身：模型需要付費，而這也是最常造成混淆的地方。



[關於 Ailoot 的實用資訊請見文件](https://ailoot.ai/docs/)。

## 簡單來說，OpenCode 是什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

OpenCode 是由 Anomaly 團隊開發的開源 AI 程式設計代理（MIT 授權）。它可在終端機中運作，也提供桌面應用程式、編輯器擴充功能和網頁版。你只要告訴它在專案中要完成什麼，它就會自行讀取檔案、編輯程式碼並執行命令。工具本身免費；雲端或本機模型都由你自行連接。

</div>

簡單來說，OpenCode 和 Claude Code 一樣，會以一般語言接收任務並在你的專案中執行。兩者有兩項不同之處。OpenCode 的程式碼完全開放，你可以閱讀和檢視；而且它不受限於單一模型供應商，支援 75+ 家供應商，從 Anthropic、OpenAI 到在你自己的硬體上執行的本機模型皆可使用。

這個專案由 Anomaly 團隊開發。儲存庫建立於 2025 年 4 月 30 日；截至 2026 年 10 月 4 日，已有[超過 211 千顆星和 28 千個分支](https://github.com/anomalyco/opencode)（已透過 GitHub API 請求查證）。使用的語言是 TypeScript。文件會持續更新，因此以下說明以目前版本為準。

不要混淆這些名稱：目前系列的 npm 套件名為 `opencode-ai`，儲存庫是 `anomalyco/opencode`，終端機命令則簡稱 `opencode`。較舊的文章可能會使用 `sst/opencode` 這個網址：組織已更名，舊連結現在會重新導向至新連結。

<strong>2026 年 10 月 4 日更新：</strong>團隊發布了 OpenCode 2.0，也就是這款工具的下一個主要世代。以下安裝與連接模型的說明仍以目前的 1.x 系列為準（使用命令 `curl -fsSL https://opencode.ai/install | bash` 安裝；截至 2026 年 9 月 30 日，目前版本為 1.18.34）：此版本仍獲積極支援，也是 opencode.ai/docs 官方文件安裝的版本。第二版究竟有哪些變化，以及何時該切換，會在下方的獨立章節說明。

## OpenCode 和 Claude Code、Codex 有何不同？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

Claude Code 只能搭配 Anthropic 模型使用。Codex 是與 ChatGPT 生態系綁定的 OpenAI 代理。OpenCode 是不綁定供應商的開放工具：它免費，你可以從 75+ 家供應商中選擇模型，包括 ChatGPT Plus 和 GitHub Copilot 訂閱方案，也可以使用本機模型。

</div>

| 功能 | OpenCode | Claude Code | Codex |
|----|----|----|----|
| 程式碼 | 開放，MIT | 封閉 | 開放 |
| 模型 | 75+ 家供應商及本機模型 | 僅 Claude | OpenAI 模型 |
| 工具費用 | 免費 | 訂閱或代幣 | ChatGPT 訂閱或代幣 |
| 訂閱方案存取 | ChatGPT Plus、GitHub Copilot、GitLab Duo | Claude Pro/Max（自己的訂閱） | ChatGPT（自己的訂閱） |
| 執行位置 | 終端機、桌面、編輯器、瀏覽器 | 終端機和編輯器 | 終端機、網頁、編輯器 |
| 專案設定 | AGENTS.md | CLAUDE.md | AGENTS.md |

如果你已經訂閱 Claude，繼續將 Claude Code 作為主要工具是合理的；我們有一份[詳細安裝指南](https://ailoot.ai/blog/zh-hant-tw/install-claude-code/)。在三種情況下，OpenCode 會是不錯的選擇：你想透過 ChatGPT Plus 或 GitHub Copilot 訂閱方案工作、想執行本機模型而不產生 API 費用，或想用單一介面操作多種模型。我們也有一份 Codex 的[評測與安裝指南](https://ailoot.ai/blog/zh-hant-tw/openai-codex-install/)。

如果你還在挑選工具，可以先看這份概覽：[2026 年大家用什麼來寫程式](https://ailoot.ai/blog/zh-hant-tw/ai-coding-tools/)。如果你已安裝 OpenCode，並需要透過 ACP 在 Devin Desktop 中與其他代理連接，請參閱我們的[設定指南](https://ailoot.ai/blog/zh-hant-tw/codex-claude-agent-opencode-devin-desktop-acp/)。

## OpenCode 2.0 有哪些變化？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

截至 2026 年 10 月 4 日，OpenCode 2.0 已在 opencode.ai 上提供，搭配自己的安裝程式和新的 npm 套件 `@opencode/cli`。本文安裝的第一版並未消失：文件中將它列為獨立的 `V1` 分支，仍獲積極支援，且仍是預設選項。v2 有三個領域是開發者刻意不維持與第一版相容的：外掛 API、伺服器通訊協定，以及終端機設定檔。

</div>

第二版使用命令 `curl -fsSL https://opencode.ai/v2/install | bash` 安裝。根據官方遷移指南（`opencode.ai/v2/docs/migrate-v1`），兩個版本使用相同的 `opencode` 命令，預設不再並行安裝：v2 安裝程式會取代 v1 二進位檔，而且在透過套件管理員安裝 v2 之前，文件明確要求先移除 v1。不過，設定會從同一批檔案讀取：`~/.config/opencode/` 和 `<project>/.opencode/`，因此設定、代理和 MCP 伺服器無須重寫即可沿用。有三項內容需要重寫：外掛（使用新的 API）、伺服器 API 整合（通訊協定已變更），以及終端機設定（現在改用一個共用的 `cli.json` 檔案，不再是多個 `tui.json` 檔案）。

v2 最值得注意的新功能有兩項。第一，推出了 Console，這是一項面向團隊的付費服務，提供使用量追蹤、預算，以及所有成員共用的政策。第二，團隊終於公布了 Go 訂閱方案的價格：Go 每月 \$10，具備較高限額的 Go Plus 每月 \$40（已於 2026 年 10 月 4 日查證 `opencode.ai/go` 頁面）。此前，文件只寫「低成本訂閱方案」，未列出金額。

如果你是新手，只想安裝代理，請依照下方說明操作；內容採用官方文件本身推薦的目前第一版。如果你需要新的外掛功能或團隊 Console，可以考慮 v2，但要有心理準備，必須依照新 API 重寫部分舊外掛。如果你比較感興趣的是不需要終端機的開源桌面應用程式，我們有一篇[ZCode 評測](https://ailoot.ai/blog/zh-hant-tw/zcode-claude-code-alternative/)，介紹另一款擁有自己介面的類似代理。

## 安裝前需要準備什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

你需要兩樣東西：新式終端機模擬器（文件列出 WezTerm、Alacritty、Ghostty 或 Kitty），以及模型存取權——供應商 API 金鑰、受支援的訂閱方案，或透過 Ollama 使用本機模型。安裝後會需要模型；你會在首次啟動時連接它。

</div>

先多談一點終端機，因為安裝過程中只有這一環可能不如預期。OpenCode 會在終端機中呈現包含面板和醒目標示的完整介面，因此文件要求使用新式模擬器。如果啟動後介面顯示異常，先安裝上述四種選項之一：WezTerm（適用於所有系統）、Alacritty、Ghostty 或 Kitty。在 Windows 上，主要安裝方式是透過 WSL，下方有專節說明。

另一項準備是模型。OpenCode 必須透過你連接的模型運作；它本身不會處理請求。共有四種選擇：訂閱方案（ChatGPT Plus、GitHub Copilot、GitLab Duo）、任何供應商的 API 金鑰、團隊自家的模型聚合服務 OpenCode Zen，或透過 Ollama 使用本機模型。連接模型一節會介紹這四種選擇。

如果沒有專案說明，代理就得猜測建置命令、檔案結構和目前採用的慣例，因此會出現「幻覺」。OpenCode 使用 AGENTS.md 檔案來處理這件事。同樣的方法也適用於 Claude Code 和其他任何代理；只有指令檔名稱不同。



## 如何在 macOS 和 Linux 上安裝 OpenCode？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

在終端機執行一個命令：curl -fsSL <https://opencode.ai/install> \| bash。文件稱這是最簡單的方法。其他選項包括 brew install anomalyco/tap/opencode、npm install -g opencode-ai；在 Arch Linux 上則可使用 pacman 或 paru。

</div>

建議使用官方安裝程式：

1.  ### 執行安裝程式

    ```bash
    curl -fsSL https://opencode.ai/install | bash
    ```

    指令碼會偵測你的系統並下載 OpenCode。如果安裝後找不到命令，請關閉並重新開啟終端機；新的工作階段就會載入路徑。

2.  ### 確認安裝正確

    ```bash
    opencode --version
    ```

    命令會傳回版本號，表示安裝成功。如果回應為「command not found」，請回到第一步：啟動新的終端機工作階段，或手動編輯 PATH。

如果你比較喜歡自行管理套件，可以選擇以下方法：

```bash
brew install anomalyco/tap/opencode
```

```bash
npm install -g opencode-ai
```

Homebrew 命令刻意以 `anomalyco/tap/` 開頭：文件建議使用他們自己的 tap，因為 Homebrew 團隊較少更新 `brew install opencode` 所用的 formula。同一個套件名稱 `opencode-ai` 也能搭配 bun、pnpm 和 yarn 使用（`bun install -g opencode-ai`、`yarn global add opencode-ai`）。在 Arch Linux 上，請從穩定版儲存庫使用 `sudo pacman -S opencode`，或使用 `paru -S opencode-bin` 從 AUR 安裝最新版本。

使用 `opencode upgrade` 更新 OpenCode；如果啟用自動更新，啟動時也會自行下載更新。更新後，用熟悉的 `opencode --version` 檢查版本。也內建解除安裝功能：

```bash
opencode uninstall
```

命令會明確列出即將刪除的內容並要求確認。你可以選擇保留設定和工作階段資料：使用 `--keep-config` 和 `--keep-data` 旗標即可。

## 如何在 Windows 上安裝 OpenCode？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

文件為了效能和完整相容性，建議使用 WSL：安裝 Windows Subsystem for Linux，然後在其中使用一般 Linux 命令安裝 OpenCode。不使用 WSL 時，可以選擇 Chocolatey（`choco install opencode`）、Scoop（`scoop install opencode`）、npm 或桌面應用程式。

</div>

開發者自己推薦的第一個選項是 WSL。在以系統管理員身分執行的 PowerShell 中，用一個命令安裝：

```powershell
wsl --install
```

重新開機後，從開始功能表開啟 Ubuntu，並在其中執行熟悉的命令：

```bash
curl -fsSL https://opencode.ai/install | bash
```

在 WSL 中可透過 `/mnt/` 存取 Windows 磁碟機上的檔案：C: 磁碟機位於 `/mnt/c/`，D: 磁碟機位於 `/mnt/d/`。因此，位於 `C:\Users\Name\project` 的專案可這樣開啟：

```bash
cd /mnt/c/Users/Name/project
opencode
```

第二個選項是不使用 WSL，改用 Windows 套件管理員。在 PowerShell 中執行：

```powershell
choco install opencode
```

```powershell
scoop install opencode
```

第三個選項是桌面應用程式和網頁版。應用程式像一般程式一樣安裝，並在視窗中顯示介面，不需要終端機。網頁版使用 `opencode web` 命令啟動：它會在瀏覽器中開啟 OpenCode，而文件也建議從 WSL 啟動，以避免存取檔案時發生問題。文件還列出較少使用的選項：mise、Docker，以及 GitHub releases 頁面上的預先建置二進位檔。Windows 上透過 bun 安裝的功能仍在開發中；如果 bun 是你的主要套件管理員，請使用 npm 選項。

## 如何為 OpenCode 連接模型？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

在終端機介面輸入 `/connect`，並從清單選擇供應商：可選擇不需自備金鑰即可開始使用的 OpenCode Zen、搭配 API 金鑰的 Anthropic 或 OpenAI、搭配訂閱方案的 ChatGPT Plus 或 GitHub Copilot，或提供本機模型的 Ollama。金鑰會儲存在 auth.json 檔案中；使用 `/models` 選擇特定模型。

</div>

OpenCode 透過 AI SDK 和 Models.dev 支援 75+ 家供應商，也支援本機模型。大多數模型都可在介面中使用 `/connect` 命令連接；本機模型則還需要在設定中指定伺服器位址。不同選項的付款方式與電腦需求各不相同：

| 選項 | 說明 | 費用 |
|----|----|----|
| OpenCode Zen | 經 OpenCode 團隊審核的模型聚合服務 | 按請求付費，為帳戶儲值 |
| OpenCode Go | 團隊提供的開放模型訂閱方案 | Go 每月 \$10；Go Plus（較高限額）每月 \$40 |
| API 金鑰 | Anthropic、OpenAI、Google、DeepSeek 等 | 按用量向供應商付費 |
| 訂閱方案 | ChatGPT Plus、GitHub Copilot、GitLab Duo | 已經付費的方案 |
| Ollama / LM Studio | 在你自己的硬體上執行本機模型 | 沒有 API 費用，但需要效能不錯的電腦 |

文件建議新手從 OpenCode Zen 開始。團隊挑選了特別適合代理工作的模型，並以自己的任務測試模型與供應商的搭配方式。

連接方式如下：輸入 `/connect`，選擇 OpenCode Zen，登入並在 opencode.ai/auth 新增付款方式，取得金鑰後貼上。接著，`/models` 會顯示建議模型清單。截至 2026 年 10 月 4 日，清單包含 GPT 6.1 Sol、GPT 6 Astra、Claude Opus 5.5、Claude Sonnet 5、GLM 5.3 和 Kimi K2.5 等模型。文件也坦承清單並不完整，而且新模型每週都會推出，因此很快就會過時。

訂閱方案也使用相同的 `/connect` 命令連接：從清單選擇 ChatGPT Plus 或 GitHub Copilot，並登入帳戶即可，不需額外設定。

如果選擇 Anthropic，`/connect` 會提供兩種選項：手動輸入 API 金鑰，或選擇 Claude Pro/Max 並透過瀏覽器驗證。不過，Anthropic 禁止使用第三方外掛來利用 Claude Pro/Max 訂閱，而 OpenCode 從 1.3.0 版起已移除這類內建外掛。如果你看到較舊的「透過 Claude 訂閱使用 OpenCode」文章，那指的是已移除的外掛，並非官方授權方式。ChatGPT Plus、GitHub Copilot、標示為實驗性的 GitLab Duo，以及 Atomic Chat 訂閱方案都不需額外設定即可使用。

透過 `/connect` 輸入的金鑰會儲存在 `~/.local/share/opencode/auth.json` 檔案中。如果不想每次都選擇模型，可以在專案根目錄的 `opencode.json` 設定檔中設定預設模型：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}
```

格式為 `provider/model`；兩個識別碼都會顯示在 `/models` 的輸出中。

## 如何透過 Ollama 連接本機模型？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

從 ollama.com 安裝 Ollama，使用 `ollama pull` 命令下載模型——Ollama 可以自動為 OpenCode 完成設定。手動設定時，請在 `opencode.json` 中新增供應商，並指定本機伺服器位址 <http://localhost:11434/v1>。使用 `/models` 選擇模型。如果代理沒有呼叫工具，請將 Ollama 的 `num_ctx` 增加至 16k–32k。

</div>

這個選項完全不會產生 API 費用：模型在你的電腦上執行。如果你正在挑選免費模型，我們另有一篇[評測](https://ailoot.ai/blog/zh-hant-tw/free-coding-models/)，介紹哪些模型作為代理時還算實用，哪些只是紙上談兵。要在 OpenCode 中使用，請從官方網站安裝 Ollama，並下載模型：

```bash
ollama pull qwen3-coder
```

文件中有一項實用資訊：Ollama 可以自動為 OpenCode 完成設定，並提供獨立的整合指南。如果想手動設定，請在 `opencode.json` 中新增供應商，並填入本機 Ollama 伺服器的位址：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}
```

接著，介面中的 `/models` 會列出本機模型。選擇它就可以開始工作。文件有一項實務提醒：如果代理不再呼叫工具（編輯檔案或執行命令），請在 Ollama 設定中提高 `num_ctx`，可以先從 16k–32k 開始。本機模型在代理工作上的表現不如雲端模型，而較小的上下文會讓情況更差。如果本機版本無法滿足需求，可以使用金鑰連接雲端版 Qwen；[如何取得 Qwen Code API 金鑰](https://ailoot.ai/blog/zh-hant-tw/qwen-code-api-key/)指南會說明取得方式。

## 使用 OpenCode 的費用是多少？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

OpenCode 本身免費：原始碼以 MIT 授權發布。你只需支付模型費用，可以透過 API 金鑰或 Zen 按用量付費、訂閱 Go、使用已訂閱的 ChatGPT Plus 或 Copilot，或者完全免費——透過 Ollama 使用本機模型不會產生費用。

</div>

這裡的費用全都與模型有關，使用方式有四種。使用 API 金鑰或 Zen 時，依實際用量付費，金額取決於代理的工作量。Go 是 OpenCode 團隊為開放模型提供的訂閱方案：Go 每月 \$10，具備較高限額的 Go Plus 每月 \$40（已於 2026 年 10 月 4 日查證 `opencode.ai/go` 頁面）。不同模型的限額各異：例如，Go 使用 Kimi K3 時每 5 小時約可提出 110 次請求（每月 440 次）；使用較輕量的 DeepSeek V4.1 Flash 時，每 5 小時約可提出 26,000 次請求。文件也列出超過限額後使用特定模型的另行費用（Kimi K3 每月 \$15，Go Plus \$60）。連接時請參閱訂閱頁面，查看完整模型和限額清單。使用 ChatGPT Plus 或 Copilot 時，請求由你已付費的訂閱方案涵蓋；但請記得訂閱方案也有各自的使用強度限制。最後，透過 Ollama 使用本機模型不需支付請求費用，但要讓模型快速運作，需要效能足夠好的電腦。



## 首次啟動時該做什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

進入專案資料夾，執行 opencode，並使用 `/init` 命令——代理會檢視專案並建立介紹專案的 AGENTS.md 檔案。編輯前按 Tab 切換到 Plan 模式：代理會提出解決方案並顯示修改內容，供你核准。使用 `/undo` 還原錯誤操作。

</div>

首次啟動時，先進入專案資料夾：

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

介面會開啟並顯示輸入欄位。首先使用 `/init` 命令：代理會掃描儲存庫中的重要檔案，必要時提出幾個問題，然後建立 AGENTS.md 檔案，說明專案結構、建置和測試要執行的命令，以及採用的慣例。文件建議將這個檔案提交至 git；之後 OpenCode 會將它作為永久的專案指令。就用途而言，AGENTS.md 相當於 OpenCode 生態系中的 CLAUDE.md。

接著使用 Plan 模式。按 Tab 鍵可在兩個主要代理間切換：Build 擁有檔案和命令的完整存取權；Plan 則負責分析與規劃——預設情況下，在 Plan 模式中編輯檔案和執行 bash 命令都需要你核准。文件建議新任務先從計畫開始：閱讀代理打算採取的步驟、調整措辭，再按 Tab 切回 Build。

文件提供以下建議：

<figure>
<blockquote>
<p>和它交談時，不妨把它當成團隊中的初階開發者。</p>
</blockquote>
<figcaption>— OpenCode 官方文件，https://opencode.ai/docs/</figcaption>
</figure>

任務描述越具體、提供的背景資訊越充分，就越不需要返工。使用 `@` 將檔案加入請求——輸入檔名後，介面會透過模糊搜尋找出檔案。你可以直接將圖片拖入終端機；以 `!` 開頭的訊息會作為 Shell 命令執行，輸出也會加入代理的上下文。如果任務弄錯，或代理做了不該做的事，`/undo` 會還原變更，而且可以連續執行數次。又改變主意了嗎？`/redo` 會還原已撤銷的內容。`/share` 會建立供團隊使用的對話連結；不使用這個命令，對話就不會發布到任何地方。

## OpenCode 還能做什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

你可以使用 `.opencode/commands` 資料夾中的 Markdown 檔案建立自訂命令、使用子代理處理平行任務和讀取程式碼、透過 MCP 伺服器連接外部工具、在瀏覽器中使用網頁版，以及透過伺服器模式進行遠端工作。

</div>

<strong>自訂命令。</strong>任何重複性的請求都能變成命令：在 `.opencode/commands/` 資料夾放入 Markdown 檔案，在 frontmatter 中設定 `description`、`agent` 和 `model`，並在下方撰寫提示範本。之後用 `/` 呼叫命令。發布前檢查專案、檢視最近的錯誤、產生遷移——任何你經常要求的工作都可以建立成命令。

<strong>子代理。</strong>除了 Build 和 Plan，還有另外三種：負責多步驟任務的 General（可使用工作清單以外的所有工具）、能快速閱讀程式碼但未獲准編輯的 Explore，以及研究外部程式庫的 Scout。在訊息中使用 `@` 提及名稱即可呼叫。

<strong>MCP 伺服器。</strong>透過 `opencode.json` 設定中的 `mcp` 區段連接外部工具；本機和遠端伺服器都支援。每個 MCP 伺服器都會將自己的工具加入上下文，像 GitHub 這類資訊量大的伺服器很快就會耗盡上下文，因此請選擇性連接，只啟用需要的工具。我們有一份介紹 MCP 概念的[現成設定指南](https://ailoot.ai/blog/zh-hant-tw/mcp-servers-claude-code/)，內容以 Claude Code 為例，但通訊協定是共通的。

**網頁版和伺服器。**`opencode web` 會在瀏覽器中開啟介面。若要從其他電腦存取，請使用 `opencode serve --hostname 0.0.0.0 --port 4096`；只要能從網路存取，務必使用 `OPENCODE_SERVER_PASSWORD` 變數設定密碼。沒有密碼，伺服器就沒有受到保護。

## 安裝出錯時該怎麼辦？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

幾乎所有問題都可歸納為三類：找不到 `opencode` 命令（啟動新的終端機工作階段或編輯 PATH）、模型沒有回應（在 `/connect` 和 `auth.json` 檔案中檢查金鑰），或介面顯示異常（使用 WezTerm 等新式終端機）。疑難排解時，先檢查 `~/.local/share/opencode/log/` 中的日誌。

</div>

<strong>安裝後顯示「opencode: command not found」。</strong>終端機尚未辨識新的路徑。先關閉再重新開啟終端機。如果仍然無效，找出安裝程式放置二進位檔的位置，並將該資料夾加入終端機的 PATH。

<strong>模型沒有回應或顯示授權錯誤。</strong>確認供應商已連接：輸入 `/connect` 並重新驗證。金鑰儲存在 `~/.local/share/opencode/auth.json`；如果你從另一台電腦搬移安裝，或清除了資料夾，這個檔案可能不存在。文件分別說明 ProviderInitError 和 AI_APICallError 錯誤：遇到前者，請重新授權供應商；遇到後者，請清除 `~/.cache/opencode` 資料夾並重新啟動。

<strong>介面顯示異常：面板散落，或符號變成無法辨識的字元。</strong>先檢查終端機。安裝一種推薦的選項——WezTerm 適用於三種系統——然後從該終端機啟動 OpenCode。

如果問題仍未解決，請檢查日誌：macOS 和 Linux 的日誌位於 `~/.local/share/opencode/log/`；在 Windows 上，按 Win+R 並輸入 `%USERPROFILE%\.local\share\opencode\log`。系統會保留最近 10 個檔案；使用 `opencode --log-level DEBUG` 旗標啟用詳細日誌。你可以附上這些日誌，在專案的 GitHub 儲存庫提交錯誤回報。

## 關於 OpenCode，大家還會問什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

常見問題的簡短回答：OpenCode 作為工具本身免費；你只需支付模型費用。Claude Pro/Max 可透過 `/connect` 連接，但禁止使用第三方外掛來連接。你可以透過網頁版從手機存取。使用 `opencode upgrade` 命令更新 OpenCode。

</div>

<div class="section">

### 常見問題

OpenCode 免費嗎？

是，其原始碼以 MIT 授權發布。你可能需要支付模型費用；所有選項都已在上方的費用專節說明。

可以連接 Claude Pro/Max 訂閱方案嗎？

可以。Anthropic 在 `/connect` 提供官方的 Claude Pro/Max 選項，並透過瀏覽器驗證。較舊的文章若提到透過外掛使用 Claude 訂閱方案，內容已過時：Anthropic 禁止這類外掛，而且 OpenCode 從 1.3.0 版起已將它們移除。

OpenCode 能在手機上使用嗎？

可行的方式是使用網頁版：在電腦或伺服器上執行 `opencode serve`，再用手機的瀏覽器連接。只要能從網路存取，就必須設定密碼 `OPENCODE_SERVER_PASSWORD`。

OpenCode 比 Claude Code 好在哪裡？

這取決於你的模型和訂閱方案：Claude Code 整合 Anthropic 模型，OpenCode 則提供 75+ 家供應商、開源程式碼和本機模型。完整比較請見上方表格。

應該立刻安裝 OpenCode 2.0 嗎？

不一定。文件預設建議使用目前的第一版，也就是本指南透過命令 curl -fsSL https://opencode.ai/install \| bash 安裝的版本。第二版自 2026 年 10 月 4 日起已開放使用，但外掛和伺服器 API 整合的運作方式有所不同，部分程式碼需要重寫。

</div>

<div class="section" role="doc-bibliography" aria-label="來源">

### 來源

- [OpenCode 官方文件](https://opencode.ai/docs/)
- [模型供應商](https://opencode.ai/docs/providers/)
- [選擇及設定模型](https://opencode.ai/docs/models/)
- [OpenCode Zen](https://opencode.ai/docs/zen/)
- [代理和子代理](https://opencode.ai/docs/agents/)
- [AGENTS.md 規則檔](https://opencode.ai/docs/rules/)
- [自訂命令](https://opencode.ai/docs/commands/)
- [MCP 伺服器](https://opencode.ai/docs/mcp-servers/)
- [透過 WSL 在 Windows 上使用 OpenCode](https://opencode.ai/docs/windows-wsl)
- [終端機介面](https://opencode.ai/docs/tui/)
- [網頁版](https://opencode.ai/docs/web/)
- [疑難排解](https://opencode.ai/docs/troubleshooting/)
- [命令列](https://opencode.ai/docs/cli/)
- [GitHub 上的 OpenCode 儲存庫](https://github.com/anomalyco/opencode)
- [OpenCode 2.0：從版本 1 遷移](https://opencode.ai/v2/docs/migrate-v1/)
- [OpenCode Go：方案和限額](https://opencode.ai/go)

</div>





[開啟 Ailoot](https://ailoot.ai/)。

## 常見問題：OpenCode：安裝、模型與首次啟動

### 安裝 OpenCode 為什麼還沒有可用模型？

工具與模型存取分開。/connect 連供應商或支援訂閱，或設定本機模型，再 /models 選取，驗證一項有界專案任務。

### 從 1.x 到 2.0，先查什麼？

檢查外掛、server API 整合及終端機設定相容性。本文列它們為遷移範圍；換 binary 前查版本，保存設定與工作階段。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。
