> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/ji-cheng/opencode.md).

# 如何使用 OpenCode 运行本地 AI 模型

在本地设备上将开源 LLM 连接到 OpenCode 的指南。

本指南将带你连接 **OpenCode** 到 [Unsloth](https://github.com/unslothai/unsloth) 以运行开源 LLM **完全在本地。** OpenCode 是一个 **开源 AI 编码代理** 它会通过连接的模型读取、修改并执行你项目中的代码。这适用于任何 **本地模型** ，通过 Unsloth 的 **OpenAI 兼容 API**公开，包括：DeepSeek、Qwen、Gemma 等。

OpenCode 作为客户端，而 Unsloth 通过本地 API 加载并提供模型服务。完成设置后，OpenCode 会连接到 Unsloth，在那里你可以选择一个已加载的模型，并将其用作 **编码代理**.

本指南涵盖两种设置方式：

* **OpenCode 桌面版：** 将 Unsloth Studio 手动添加为自定义的 OpenAI 兼容提供方。
* **OpenCode CLI：** 用 `unsloth start opencode` 启动，并自动连接到你的本地模型。

<a href="https://unsloth.ai/docs/integrations/opencode#installing-opencode-desktop" class="button primary">OpenCode 设置</a><a href="/docs/zh/ji-cheng/opencode.md#quickstart" class="button primary">快速开始</a>

{% hint style="info" %}
在本教程中，我们将使用 `unsloth/Qwen3.6-27B-GGUF` 在 Unsloth 中加载，并直接在 OpenCode 中访问它。想用别的模型？只需在 Unsloth 中加载其他模型即可。
{% endhint %}

### 安装 OpenCode 桌面版

{% tabs %}
{% tab title="macOS" %}

#### **步骤 1：下载 Mac 版 OpenCode 安装程序**

打开 `opencode.ai/download` ，在你常用的浏览器中。滚动到 **OpenCode Desktop（Beta）** ，然后点击 `下载` 按钮，位于与你的 Mac 架构（Apple Silicon 或 Intel）对应的 macOS 镜像名称旁边。

#### 步骤 2：安装 OpenCode

找到并双击 `OpenCode Desktop.dmg` 下载文件夹中的安装文件。

安装程序窗口将打开。使用鼠标将 **OpenCode** 应用图标拖到 **应用程序** 图标上，如图所示。

#### 步骤 3：启动 OpenCode

找到并双击 **OpenCode** 文件夹下的 **应用程序** 图标。

这个 **OpenCode** 桌面应用将打开，现在已准备好执行你的下一步操作。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FZNP4G1c2hmHyBzNbGH5x%2Fopencode_interface.png?alt=media&amp;token=5af679cb-504d-4299-a40e-0d8310289a90" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Windows" %}

#### **步骤 1：下载 Windows 版 OpenCode 安装程序**

打开 `opencode.ai/download` 在你的浏览器中。滚动到 **OpenCode Desktop（Beta）**，然后点击 **下载** 按钮，位于 Windows (x64) 安装程序旁边。

#### **步骤 2：安装 OpenCode**

找到 `OpenCode Desktop Installer.exe` 在你的 Downloads 文件夹中并双击它。然后按照安装程序窗口中的提示完成安装。

#### **步骤 3：启动 OpenCode**

打开 Windows 开始菜单并搜索 **OpenCode**.\n\n点击 OpenCode 应用图标以启动它。OpenCode 桌面应用将打开，现在已准备好执行你的下一步操作

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FLECAvpw6DMNCcuFclzoy%2Fimage.png?alt=media&amp;token=7a628b56-3e0c-4d00-8054-ab8b9317e4f9" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Linux" %}

#### **步骤 1：下载 Linux 版 OpenCode 安装程序**

前往 `opencode.ai/download` ，并使用你偏好的网页浏览器。找到 **OpenCode Desktop（Beta）** 部分，然后为你的系统选择 Linux 下载选项。

#### **步骤 2：安装 OpenCode**

打开你的 Downloads 文件夹并找到 **OpenCode** 你刚刚下载的安装程序。

对于 AppImage 下载，右键单击该文件，打开 **属性**，并启用允许该文件作为程序运行的选项。然后双击 AppImage 以启动 **OpenCode**.

或者，如果你更喜欢使用终端，请运行：

```
chmod +x OpenCode*.AppImage
./OpenCode*.AppImage
```

如果你下载了 `.deb` 文件，请使用以下命令安装：

```
sudo apt install ./OpenCode*.deb
```

如果你下载了 `.rpm` 文件，请使用以下命令安装：

```
sudo dnf install ./OpenCode*.rpm
```

#### **步骤 3：启动 OpenCode**

打开你的 Linux 应用启动器并搜索 **OpenCode**.

点击 OpenCode 应用图标以启动它。OpenCode 桌面应用将打开，现在已准备好执行你的下一步操作。
{% endtab %}
{% endtabs %}

### ⚡ 快速开始

安装 OpenCode 之后，我们需要安装 [Unsloth 桌面版](/docs/zh/desktop.md) 以便让 OpenCode 能够提供并运行本地模型的推理。

{% stepper %}
{% step %}

#### 下载 Unsloth

最简单的入门方式是安装 Unsloth 桌面应用。它支持 [macOS](/docs/zh/kai-shi-shi-yong/install/mac.md)、Linux、 [Windows](/docs/zh/kai-shi-shi-yong/install/windows-installation.md), [NVIDIA](/docs/zh/kai-shi-shi-yong/install/pip-install.md), [AMD](/docs/zh/kai-shi-shi-yong/install/amd.md)、Intel 和 CPU 配置。

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

* <i class="fa-apple">:apple:</i> [下载 macOS 版](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载 Windows 版](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载 Linux 版](https://unsloth.ai/download/linux)

或者，如果你更喜欢手动安装：

**MacOS, Linux, WSL:**

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

**Windows PowerShell:**

```bash
irm https://unsloth.ai/install.ps1 | iex
```

{% endstep %}

{% step %}

#### 安装

1. 打开 Unsloth 安装程序（`.dmg`, `.exe` 文件）
2. 在 Mac 上将 Unsloth 拖到 Applications，或者完成 Windows 的设置。
3. 启动应用并等待安装完成
   {% endstep %}

{% step %}

#### 选择一个模型

打开顶部的“选择模型”下拉菜单或“模型中心”标签页，选择适合你的设备的模型和量化方式，然后下载。完成后即可开始聊天——无需设置。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FNCEVgKLJI0goPqjgcg9B%2Fmodel%20hub%20models.png?alt=media&amp;token=533b5e3c-a901-4b33-963e-4a703cc9d5a6" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Unsloth 现在已准备就绪

要开始聊天，请输入消息并按 Enter。

**连接 OpenCode。** 运行 `unsloth start opencode`. 它会生成 API 密钥、写入配置，并使用你已加载的模型启动 OpenCode。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FpAGvwjGD0iVMZKBoyu7m%2Fgreeennn.png?alt=media&amp;token=d17a5528-8375-444c-9aff-f9e9f7903bcd" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### 🔑 创建 API 密钥

1. 打开侧边栏，点击左下角的 **Unsloth** 头像。
2. 前往 **设置** → **API**.
3. 输入一个友好的名称（例如 `claude-code-macbook`).
4. *（可选）* 设置过期时间。
5. 点击 **创建**.
6. **立即复制密钥。** Unsloth 只会存储哈希值，你将无法再次查看它。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FrWnqY5PgvZdbWK8pmlD5%2Fimage.png?alt=media&amp;token=3507e7d7-b552-447f-b503-2418802b8f6e" alt="" width="375"><figcaption></figcaption></figure>

所有密钥都以 `sk-unsloth-` 前缀开头。你可以随时在同一页面吊销密钥。使用已吊销密钥发出的请求会返回 `401 未授权`.

## 🖇️ 将 Unsloth 连接到 OpenCode 桌面版

**OpenCode** 支持任何 OpenAI 兼容提供方，因此你可以将 Unsloth 作为 **自定义** 提供方接入。该设置是 opencode 的 **连接提供方** 对话框中的一次性流程。

**1. 打开提供方选择器。** 在 opencode 中，输入 `/model` （或点击输入框底部的模型选择器）。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fl59D1AVRI57fQBJqgp8t%2Fslash-model.png?alt=media&amp;token=9434f804-6a9e-4b76-ab7e-75cd745fe9c2" alt="" width="563"><figcaption></figcaption></figure></div>

然后点击 **连接提供方** 选择模型对话框右上角的

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fi9VOd4yRAmLnqZ1D4tBm%2Fconnect%20provider.png?alt=media&amp;token=cb28387a-9cc3-4c5f-928e-82a56edd86df" alt="" width="375"><figcaption></figcaption></figure></div>

**2. 选择“自定义”。** 在提供方列表中，滚动到 **其他** 并选择 **自定义**.

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FWyltmg0o9YtyydUSLvcn%2Fcustom%20highlighted.png?alt=media&amp;token=5cc89686-dfae-4ebd-8beb-e6dc78088b4b" alt="" width="375"><figcaption></figcaption></figure></div>

**3. 填写自定义提供方表单：**

| 字段         | 值                                                                       |
| ---------- | ----------------------------------------------------------------------- |
| **提供方 ID** | `unsloth-studio` *（小写，允许连字符）*                                           |
| **显示名称**   | `Unsloth Studio`                                                        |
| **基础 URL** | `http://localhost:8888/v1/` *（替换 `8888` 为你的* Unsloth *端口；保留结尾的 `/v1/`)* |
| **API 密钥** | 你的 `sk-unsloth-…` 密钥                                                    |

在 **模型** 部分中，为你想暴露的每个模型添加一行。左侧字段是 Unsloth 提供服务时的模型 ID；右侧字段是 opencode 将显示的内容：

| 模型 ID（左侧）                                           | 显示名称（右侧）                                      |
| --------------------------------------------------- | --------------------------------------------- |
| `unsloth/Qwen3.6-27B-GGUF` *（Unsloth 中显示的该模型的准确名称）* | `unsloth/Qwen3.6-27B-GGUF` *（在 opencode 中显示）* |

留空 **标头** 为空，除非你正通过需要自定义标头的身份验证层代理 Unsloth。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FjGU2OaOKRtqCwmO34BuN%2Fopencode_custom_provider_config.png?alt=media&amp;token=6ef67ecf-23e6-4913-bc02-c26701f5aea0" alt="" width="375"><figcaption></figcaption></figure></div>

**4. 点击提交。** 你应该会看到一条 *“Unsloth Studio 已连接。现在可以使用 Unsloth 模型了”* 提示气泡。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FuCOOOJhO8brhEwwIsiUC%2Fopencode_model_available_toast.png?alt=media&amp;token=a463bb0c-724a-4809-9ddb-b7bff094b255" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="warning" %}
**添加提供方后重启 opencode。** 新的提供方只有在重启后才会变为可选。
{% endhint %}

**5. 选择你的 Unsloth 模型。** 一旦 opencode 重新启动，输入 `/model`，搜索 `unsloth`，并选择 **Unsloth Studio** 组下的模型。它会在你的下一条消息中生效。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FFRNofXnF7r7CKlHjLMwv%2Fopencode_unsloth_model_usage.png?alt=media&amp;token=4c882e8f-6ac5-4f9b-8f59-5e86e312851b" alt="" width="375"><figcaption></figcaption></figure></div>

Unsloth 同时支持 OpenAI 和 Anthropic 的 Python SDK。

### ⚙️ **OpenCode CLI**

OpenCode CLI 可以连接到已在 Unsloth Studio 中运行的模型，或者在 Unsloth 未运行时自动启动一个模型。

#### 如果 Unsloth Studio 已经在运行

在 Unsloth Studio 中加载了模型后，打开你的项目文件夹并运行：

```bash
unsloth start opencode
```

使用此命令会在当前加载于 Unsloth 的模型下启动 OpenCode，而不会更改你现有的 OpenCode 设置。

#### 自动启动模型

如果 Unsloth 尚未运行，你可以用一条命令启动临时服务器并加载模型：

若要直接使用模型启动 OpenCode，请运行：

```bash
unsloth start opencode \\
    --model unsloth/qwen3.8-27B-GGUF-GGUF:UD-Q4_K_XL
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 20 \\
    --min-p 0.0 \\
    --reasoning-effort medium
```

Unsloth 会自动选择正确的参数，但你仍然可以修改它。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fom5iWH1f42GZ69utVSyf%2Fimage.png?alt=media&amp;token=815a0458-b252-4c96-a341-e345842bd248" alt="" width="563"><figcaption></figcaption></figure></div>

一旦 **OpenCode** 打开它，请给它一个任务，例如：

```
创建一个类似 Flash 风格的 Python 2D 游戏，带有跳跃、冲刺和两个关卡。
```

它可以检查项目、创建文件、编辑代码，并使用本地模型运行命令。

<div align="center" data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FOA6dENYOpJdGa3zwS8Ei%2Fimage.png?alt=media&amp;token=266a85f8-ec80-4a7d-bd58-e82d9ff0b864" alt="" width="563"><figcaption></figcaption></figure></div>

在这个示例中，模型创建了一个双关卡平台游戏。让我们打开看看效果如何。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FHqFv9FyPsM0poo5c6WNb%2Fezgif-68bd7a9b463725d0.gif?alt=media&amp;token=abafdfef-6e13-430b-bccb-140f29ee6d13" alt="" width="563"><figcaption></figcaption></figure></div>

#### 恢复你的工作

OpenCode 会自动保留你的会话历史，因此你不需要 `--persist`。若要从上次离开的地方继续，即使 Unsloth 不再运行，也请使用：

```bash
unsloth start opencode \\
  --model unsloth/Qwen3.6-27B-GGUF \\
  --continue
```

如果你想改为打开某个特定会话，请使用 `--session <session-id>`.

查看完整的 [unsloth start](/docs/zh/ji-cheng/unsloth-start.md) 参考文档，了解模型加载、远程 Unsloth 服务器以及高级选项。

### 可选：配置服务器访问

`unsloth run` 会启动本地 API 服务器并加载一个供 OpenCode 连接的模型。你也可以在启动时自定义服务器的行为。

```bash
# 在端口 8888 上运行 API（--disable-tools 会透传 OpenCode 自身的工具）
unsloth run \\
  --model unsloth/gemma-4-26B-A4B-it-GGUF \\
  --disable-tools \\
  -p 8888
```

{% hint style="warning" %}
使用 `--disable-tools` 在驱动 OpenCode（或任何外部编码代理）时。默认情况下，Unsloth Studio 会运行它自己的服务端工具，这会吞掉代理的工具调用，因此 OpenCode 会给出回答却从不编辑文件。 `--disable-tools` 会切换为透传模式，因此会使用 OpenCode 自己的工具。
{% endhint %}

使用 `-p` 来更改服务器运行的端口。

```bash
# 允许网络上的其他设备连接
unsloth run \\
  --model unsloth/gemma-4-26B-A4B-it-GGUF \\
  -H 0.0.0.0 \\
  --disable-tools \\
  -p 8888
```

这会在 `0.0.0.0:8888`上启动服务器，从而允许本地网络上的其他设备连接。

有关更高级的运行时配置，请参阅主 [API 调优](https://unsloth.ai/docs/basics/api#unsloth-run-command) 部分。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unsloth.ai/docs/zh/ji-cheng/opencode.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
