---
title: 簡介
description: 開始使用 OpenCode。
---

import { Tabs, TabItem } from "@astrojs/starlight/components"
import config from "../../../../config.mjs"
export const console = config.console

[**OpenCode**](/) 是一個開源的 AI 編碼代理。它提供終端機介面、桌面應用程式和 IDE 擴充功能等多種使用方式。

![使用 OpenCode 主題的 OpenCode TUI](../../../assets/lander/screenshot.png)

讓我們開始吧。

---

#### 前提條件

要在終端機中使用 OpenCode，您需要：

1. 一款現代終端機模擬器，例如：
   - [WezTerm](https://wezterm.org)，跨平台
   - [Alacritty](https://alacritty.org)，跨平台
   - [Ghostty](https://ghostty.org)，Linux 和 macOS
   - [Kitty](https://sw.kovidgoyal.net/kitty/)，Linux 和 macOS

2. 您想使用的 LLM 供應商的 API 金鑰。

---

## 安裝

安裝 OpenCode 最簡單的方法是透過安裝指令碼。

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

您也可以使用以下方式安裝：

- **使用 Node.js**

        <Tabs>

      <TabItem label="npm">
      ```bash
      npm install -g opencode-ai
      ```

          </TabItem>

        <TabItem label="Bun">
        ```bash
        bun install -g opencode-ai
        ```

          </TabItem>

        <TabItem label="pnpm">
        ```bash
        pnpm install -g opencode-ai
        ```

          </TabItem>

        <TabItem label="Yarn">
        ```bash
        yarn global add opencode-ai
        ```

      </TabItem>

  </Tabs>

- **在 macOS 和 Linux 上使用 Homebrew**

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

  > 我們推薦使用 OpenCode tap 以取得最新版本。官方的 `brew install opencode` formula 由 Homebrew 團隊維護，更新頻率較低。

- **在 Arch Linux 上安裝**

  ```bash
  sudo pacman -S opencode           # Arch Linux (Stable)
  paru -S opencode-bin              # Arch Linux (Latest from AUR)
  ```

#### Windows

:::tip[推薦：使用 WSL]
為了在 Windows 上獲得最佳體驗，我們推薦使用 [Windows Subsystem for Linux (WSL)](/docs/windows-wsl)。它提供更好的效能，並完全相容 OpenCode 的所有功能。
:::

- **使用 Chocolatey**

  ```bash
  choco install opencode
  ```

- **使用 Scoop**

  ```bash
  scoop install opencode
  ```

- **使用 NPM**

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

- **使用 Mise**

  ```bash
  mise use -g github:anomalyco/opencode
  ```

- **使用 Docker**

  ```bash
  docker run -it --rm ghcr.io/anomalyco/opencode
  ```

在 Windows 上透過 Bun 安裝 OpenCode 的支援目前正在開發中。

您也可以從 [Releases](https://github.com/anomalyco/opencode/releases) 頁面直接下載二進位檔案。

---

## 設定

透過 OpenCode，您可以設定 API 金鑰來使用任意 LLM 供應商。

如果您剛開始接觸 LLM 供應商，我們推薦使用 [OpenCode Zen](/docs/zen)。這是一組經過 OpenCode 團隊測試和驗證的精選模型。

1. 在 TUI 中執行 `/connect` 指令，選擇 opencode，然後前往 [opencode.ai/auth](https://opencode.ai/auth)。

   ```txt
   /connect
   ```

2. 登入並新增帳單資訊，然後複製您的 API 金鑰。

3. 貼上您的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

您也可以選擇其他供應商。[了解更多](/docs/providers#directory)。

---

## 初始化

設定好供應商後，導覽到您想要處理的專案目錄。

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

然後執行 OpenCode。

```bash
opencode
```

接下來，執行以下指令為專案初始化 OpenCode。

```bash frame="none"
/init
```

OpenCode 會分析您的專案並在專案根目錄建立一個 `AGENTS.md` 檔案。

:::tip
您應該將專案的 `AGENTS.md` 檔案提交到 Git。
:::

這有助於 OpenCode 理解專案結構和編碼規範。

---

## 使用

現在您已經準備好使用 OpenCode 來處理專案了，儘管提問吧！

如果您是第一次使用 AI 編碼代理，以下範例可能會對您有所幫助。

---

### 提問

您可以讓 OpenCode 為您講解程式碼庫。

:::tip
使用 `@` 鍵可以模糊搜尋專案中的檔案。
:::

```txt frame="none" "@packages/functions/src/api/index.ts"
How is authentication handled in @packages/functions/src/api/index.ts
```

當您遇到不熟悉的程式碼時，這個功能非常有用。

---

### 新增功能

您可以讓 OpenCode 為專案新增新功能。不過我們建議先讓它制定一個計畫。

1. **制定計畫**

   OpenCode 有一個*計畫模式*，該模式下它不會進行任何修改，而是建議*如何*實作該功能。

   使用 **Tab** 鍵切換到計畫模式。您會在右下角看到模式指示器。

   ```bash frame="none" title="Switch to Plan mode"
   <TAB>
   ```

   接下來描述您希望它做什麼。

   ```txt frame="none"
   When a user deletes a note, we'd like to flag it as deleted in the database.
   Then create a screen that shows all the recently deleted notes.
   From this screen, the user can undelete a note or permanently delete it.
   ```

   您需要提供足夠的細節，讓 OpenCode 理解您的需求。可以把它當作團隊中的一名初級開發者來溝通。

   :::tip
   為 OpenCode 提供充足的上下文和範例，幫助它理解您的需求。
   :::

2. **迭代計畫**

   當它給出計畫後，您可以提供回饋或補充更多細節。

   ```txt frame="none"
   We'd like to design this new screen using a design I've used before.
   [Image #1] Take a look at this image and use it as a reference.
   ```

   :::tip
   將圖片拖放到終端機中即可將其新增到提示詞中。
   :::

   OpenCode 可以掃描您提供的圖片並將其新增到提示詞中。只需將圖片拖放到終端機視窗即可。

3. **建置功能**

   當您對計畫滿意後，再次按 **Tab** 鍵切換回*建置模式*。

   ```bash frame="none"
   <TAB>
   ```

   然後讓它開始實施。

   ```bash frame="none"
   Sounds good! Go ahead and make the changes.
   ```

---

### 直接修改

對於比較簡單的修改，您可以直接讓 OpenCode 實施，無需先審查計畫。

```txt frame="none" "@packages/functions/src/settings.ts" "@packages/functions/src/notes.ts"
We need to add authentication to the /settings route. Take a look at how this is
handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts
```

請確保提供足夠的細節，以便 OpenCode 做出正確的修改。

---

### 復原修改

假設您讓 OpenCode 做了一些修改。

```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```

但您發現結果不是您想要的。您**可以使用** `/undo` 指令來復原修改。

```bash frame="none"
/undo
```

OpenCode 會還原所做的修改，並重新顯示您之前的訊息。

```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```

您可以調整提示詞，讓 OpenCode 重新嘗試。

:::tip
您可以多次執行 `/undo` 來復原多次修改。
:::

您也**可以使用** `/redo` 指令來重做修改。

```bash frame="none"
/redo
```

---

## 分享

您與 OpenCode 的對話可以[與團隊分享](/docs/share)。

```bash frame="none"
/share
```

這會生成當前對話的連結並複製到剪貼簿。

:::note
對話預設不會被分享。
:::

這是一個與 OpenCode 的[範例對話](https://opencode.ai/s/4XP1fce5)。

---

## 個人化

以上就是全部內容！您現在已經是 OpenCode 的使用高手了。

要讓它更符合您的習慣，我們推薦[選擇一個主題](/docs/themes)、[自訂快捷鍵](/docs/keybinds)、[設定程式碼格式化器](/docs/formatters)、[建立自訂指令](/docs/commands)，或者探索 [OpenCode 設定](/docs/config)。