> 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 模型

了解如何在本地设备上使用 OpenCode 连接开源 LLM。

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

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

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

* **OpenCode Desktop：** 手动将 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 Desktop

{% 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**。\
\
点击 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 Desktop](/docs/zh/desktop.md) 以便让 OpenCode 为本地模型提供服务并进行推理。

{% stepper %}
{% step %}

#### 下载 Unsloth

最简单的入门方式是安装 Unsloth Desktop 应用。它支持 [MacOS](/docs/zh/kuai-su-kai-shi/install/mac.md)、Linux、 [Windows](/docs/zh/kuai-su-kai-shi/install/windows-installation.md), [NVIDIA](/docs/zh/kuai-su-kai-shi/install/pip-install.md), [AMD](/docs/zh/kuai-su-kai-shi/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 Unauthorized`.

## 🖇️ 将 Unsloth 连接到 OpenCode Desktop

**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`                                                        |
| **Base 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
