> 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 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="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="/files/5db448663137d8e72fcf5f9f4841d144f8df6c81" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

### ⚡ 快速开始

安装 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 只会存储哈希值，你将无法再次查看它。

<figure><img src="/files/3432517ab3e4dadf17eb7ea5f319b43cc5902dd2" alt="" width="375"><figcaption></figcaption></figure>

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

{% 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="" 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` *（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。

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

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