> 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（测试版），** 然后点击 `下载` 与你的 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（测试版）**，然后点击 **下载** Windows（x64）安装程序旁边的按钮。

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

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

#### **步骤 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（测试版）** 部分，然后为你的系统选择 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 %}

### ⚡ 快速开始

安装 OpenClaw 后，我们还需要安装 [Unsloth Desktop](/docs/zh/desktop.md) 以启用 OpenClaw 提供本地模型服务并进行推理。

{% stepper %}
{% step %}

#### 下载 Unsloth

最简单的入门方式是安装 Unsloth 桌面应用。它支持 [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="/files/ee716919ab359455030e8acd4d55b5ec13ca328d" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Unsloth 已准备就绪

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

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

<figure><img src="/files/b0dfb852351654c29812a5aa23885913432eaa10" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### 🔑 创建 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. 选择“Custom”。** 在提供方列表中，滚动到 **其他** 并选择 **自定义**.

<div data-with-frame="true"><figure><img src="/files/459def9562f964e3d090f072737cead09f375b08" 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="/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 尚未运行，你可以用一条命令启动临时服务器并加载一个模型：

要直接用某个模型启动 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 \
    --chat-template-kwargs '{"reasoning_effort":"medium"}'
```

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

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