> 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** 更改为 [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="/pages/124bfded8d8412a9fbc1614fa7467985c0af22da#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** 应用图标拖到 **Applications** 图标上，如图所示。

#### 步骤 3：启动 OpenCode

找到并双击 **OpenCode** 图标放到 **Applications** 文件夹下。

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

<div data-with-frame="true"><figure><img src="/files/5db448663137d8e72fcf5f9f4841d144f8df6c81" 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` 在你的下载文件夹中，双击它。然后按照安装程序窗口中的提示完成安装。

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

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

<div data-with-frame="true"><figure><img src="/files/760ac7b0d6e772ef31c394bdc3a904a26c753f9f" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Linux" %}

#### **步骤 1：下载适用于 Linux 的 OpenCode 安装程序**

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

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

打开你的下载文件夹并找到 **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 Studio，以便 OpenCode 能够提供服务并对本地模型进行推理。

1. **安装或更新 Unsloth Studio。** 较早版本不暴露外部 API。参见安装。
2. **启动 Unsloth。** 注意它启动时使用的端口通常是 `8000` 或 `8888`。你会在终端输出以及浏览器 URL 中看到它（`http://localhost:PORT`).
3. **加载模型。** 点击 **新建聊天**，选择或搜索一个模型（GGUF），并等待其加载完成。
4. **连接 OpenCode。** 运行 `unsloth start opencode`。它会生成一个 API 密钥、写入配置，并让 OpenCode 针对你已加载的模型启动。

### 🔑 创建 API 密钥

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

<figure><img src="/files/3432517ab3e4dadf17eb7ea5f319b43cc5902dd2" 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="/files/2779654a45c4d534115ba62d44b4baaaec772800" alt="" width="563"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/c03296bb966bfe1b83334515ba0311686a24546b" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/459def9562f964e3d090f072737cead09f375b08" 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="/files/d253ef4a250447ed9c050d48becacf7b1b467f5e" alt="" width="375"><figcaption></figcaption></figure></div>

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

<figure><img src="/files/0321559dac6be2a82c213fe64e4cf549c080a8d7" 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="/files/433502c37d351cd5ade2d80c9b72d57e37f71f92" 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 Studio 尚未运行，你可以用一条命令启动临时服务器并加载模型：

```bash
unsloth start opencode --model unsloth/gemma-4-26B-A4B-it-GGUF
```

<div data-with-frame="true"><figure><img src="/files/23e958dc51cb4ce33184b35074592c03264caf3d" alt="" width="563"><figcaption></figcaption></figure></div>

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

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

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

<div align="center" data-with-frame="true"><figure><img src="/files/bb5f08c86fee42150c661af6859bc5004eb5049a" alt="" width="563"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/b35cc90c2e7da3adde73488387ff4ebf22509c56" 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 服务器和高级选项的参考。&#x20;

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

`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.