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

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

完成设置后，OpenCode 会连接到 Unsloth，在那里你可以选择一个已加载的模型并将其用作 **编码代理**.

<a href="https://sites.gitbook.com/preview/site_mXXTe/~/revisions/S6OVzFPYN3gcF4rziUb5/integrations/opencode?theme=light#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 Desktop

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

{% endtab %}

{% tab title="MacOS" %}
**步骤 1：下载适用于 Mac 的 OpenCode 安装程序**

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

<figure><img src="/files/1051a2c42b488f1511d35eedbaafe1e98ab8a254" alt=""><figcaption></figcaption></figure>

会弹出一个窗口，询问你想将 open code 安装程序保存到哪里。选择默认设置也可以。点击 **保存。** 这会将 **OpenCode** 安装程序保存到你的 `下载` 文件夹中。

<figure><img src="/files/87ccc6d20ac0f7176ffa08a984359a7ac2a9f94b" alt=""><figcaption></figcaption></figure>

#### 步骤 2：安装 OpenCode

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

<figure><img src="/files/6348b59e516bf1b3f19213802da0d45a565a5134" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/bc5da4683dac5bc3c071de1e0d34df138b001162" alt=""><figcaption></figcaption></figure>

#### 步骤 3：启动 OpenCode

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

<figure><img src="/files/176d904a1c28440365c79208b63b2ef79f776005" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/5db448663137d8e72fcf5f9f4841d144f8df6c81" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Linux/WSL" %}

{% endtab %}
{% endtabs %}

## 安装 Unsloth

### ⚡ 快速入门

安装 OpenCode 后，我们还需要安装 Unsloth Studio，以便 OpenCode 能够提供并运行本地模型推理。

1. **安装或更新 Unsloth Studio。** 较早版本不会暴露外部 API。请参阅安装。
2. **启动 Unsloth。** 注意它启动时所使用的端口通常是 `8000` 或 `8888`。你会在终端输出和浏览器 URL 中看到它（`http://localhost:PORT`).
3. **加载一个模型。** 点击 **新聊天**，选择或搜索一个模型（GGUF），并等待其加载完成。
4. **创建一个 API 密钥。** 在 Unsloth 中，点击你的 **Unsloth** 左下角的头像 → **设置** → **API** → 输入一个密钥名称 → **创建**。复制出现的 `sk-unsloth-…` 值。Unsloth 只会显示一次。
5. **将你的客户端指向 Unsloth。** 使用 `http://localhost:PORT` 作为基础 URL，并使用你的 `sk-unsloth-…` 密钥进行身份验证。下面直接跳到你的工具对应的配置步骤。

### 🔑 创建 API 密钥

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

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

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

{% hint style="warning" %}
请像对待密码一样对待你的 API 密钥。任何拥有该密钥且能访问你的 Unsloth 实例网络的人，都可以向你加载的模型发送请求。
{% endhint %}

## 🖇️ 将 Unsloth 连接到 OpenCode Desktop

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

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

<div data-with-frame="true"><figure><img src="/files/2779654a45c4d534115ba62d44b4baaaec772800" alt=""><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` *（Studio 中显示的模型准确名称）* | `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。


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.