> 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/unsloth-start.md).

# 使用 Unsloth Start 运行本地 LLM 驱动的编码代理

Unsloth 可让你连接 [Claude Code](/docs/zh/ji-chu/claude-code.md), [Codex](/docs/zh/ji-chu/codex.md)、Hermes、OpenCode、Pi 以及其他编码代理，通过 `unsloth start` 命令连接到本地模型。整个工作流可以在你自己的硬件上离线运行。 [Unsloth](/docs/zh/desktop.md) 会在每次启动时自动配置端点、API 密钥、提供方、模型和上下文长度，因此你无需修改它们即可使用你偏好的代理。本指南将向你展示如何从命令行启动模型以供离线使用，并连接到 Unsloth。

{% columns %}
{% column width="58.333333333333336%" %}

### 快速入门

首先，确保你已安装 [Unsloth](/docs/zh/xin/studio/install.md)。然后打开 Unsloth，加载一个模型，进入你的项目文件夹，并在终端中运行命令：

```bash
unsloth start claude
```

你可以将 `claude` 替换为下面的任意代理：
{% endcolumn %}

{% column width="41.666666666666664%" %}

<figure><img src="/files/86e035acbaafcca2b57e4bb3f4191ad68bf30547" alt=""><figcaption><p>Claude Code 在本地使用 Qwen3.5 运行。</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

| 代理                                                                 | 命令                       |
| ------------------------------------------------------------------ | ------------------------ |
| <i class="fa-claude">:claude:</i> Claude Code                      | `unsloth start claude`   |
| <i class="fa-openai">:openai:</i> OpenAI Codex                     | `unsloth start codex`    |
| <i class="fa-caduceus">:caduceus:</i> Hermes 代理                    | `unsloth start hermes`   |
| <i class="fa-lobster">:lobster:</i> OpenClaw                       | `unsloth start openclaw` |
| <i class="fa-rectangle-vertical">:rectangle-vertical:</i> OpenCode | `unsloth start opencode` |

Unsloth 使用临时或会话范围内的提供方配置。它不会把 Unsloth 提供方添加到代理的常规配置文件中。

{% hint style="info" %}
Codex 目前需要通过 `llama-server` 后端提供的 GGUF 模型。
{% endhint %}

### 代理指南

<table data-column-title-hidden data-view="cards"><thead><tr><th>标题</th><th data-hidden data-card-cover data-type="image">封面图</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Claude Code</td><td><a href="/files/96110ae2bcda143dd4b91e9c5b67c6e995010e7a">/files/96110ae2bcda143dd4b91e9c5b67c6e995010e7a</a></td><td><a href="/pages/1a707991086189a8e5cd8374f3ce1b81915bc159">/pages/1a707991086189a8e5cd8374f3ce1b81915bc159</a></td></tr><tr><td>Codex</td><td><a href="/files/b51578bd533811ab0e3630dfa8fc7a5e32df1659">/files/b51578bd533811ab0e3630dfa8fc7a5e32df1659</a></td><td><a href="/pages/b71ddea7924324c058a771e5e831c3cb6fc75b18">/pages/b71ddea7924324c058a771e5e831c3cb6fc75b18</a></td></tr><tr><td>Hermes 代理</td><td><a href="/files/62ea1254c3afcf0dab9983869b9871e674980b36">/files/62ea1254c3afcf0dab9983869b9871e674980b36</a></td><td><a href="/pages/8567c077a06708926cb64d39a91077f5abf44625">/pages/8567c077a06708926cb64d39a91077f5abf44625</a></td></tr><tr><td>OpenClaw</td><td><a href="/files/bbe51e82c63315b774853db61b53659642d98312">/files/bbe51e82c63315b774853db61b53659642d98312</a></td><td><a href="/pages/f1eb04d9bdae8f6dbb3d9ed5d64e060dac5a68ff">/pages/f1eb04d9bdae8f6dbb3d9ed5d64e060dac5a68ff</a></td></tr><tr><td>OpenCode</td><td><a href="/files/a1306faf72d1856a3dc7e06dda9f53ed10c14ac7">/files/a1306faf72d1856a3dc7e06dda9f53ed10c14ac7</a></td><td><a href="/pages/124bfded8d8412a9fbc1614fa7467985c0af22da">/pages/124bfded8d8412a9fbc1614fa7467985c0af22da</a></td></tr><tr><td>Unsloth API</td><td><a href="/files/8107f7256aad887cf1f43626598f906531e54a78">/files/8107f7256aad887cf1f43626598f906531e54a78</a></td><td><a href="/pages/2c2bb53a273009e389791ded9e28dd4769a55051">/pages/2c2bb53a273009e389791ded9e28dd4769a55051</a></td></tr></tbody></table>

### 从命令行加载模型

<div align="center"><figure><img src="/files/68d487f2947b7f21e3d210b4493a3c1196252200" alt="unsloth start launching Codex with a local GGUF model in Unsloth Studio" width="563"><figcaption><p>Unsloth start 会查找或加载模型，配置编码代理，并从当前项目中启动它。</p></figcaption></figure></div>

你可以在启动代理时选择并加载模型：

{% tabs %}
{% tab title="带量化后缀" %}

```bash
unsloth start codex \
  --model unsloth/gemma-4-E2B-it-GGUF:UD-Q4_K_XL \
  --context-length 32768
```

该 `:UD-Q4_K_XL` 后缀用于选择 GGUF 量化版本。
{% endtab %}

{% tab title="使用 `--gguf-variant`" %}

```bash
unsloth start codex \
  --model unsloth/gemma-4-E2B-it-GGUF \
  --gguf-variant UD-Q4_K_XL \
  --context-length 32768
```

显式的 `--gguf-variant` 会覆盖写在模型名称后面的量化版本。
{% endtab %}
{% endtabs %}

在默认的本地地址上，传入 `--model` 可让 `unsloth start` 在 Unsloth Studio 尚未运行时启动一个临时服务器。临时服务器会在代理退出时停止。如果 Unsloth 已经在运行，该命令会连接到它并保持其运行。

下面是代理连接到本地 LLM 的示例：

{% columns %}
{% column width="50%" %}

<div align="left"><figure><img src="/files/ba113c2c9d012b86b54e26911342b1b41ec303d1" alt=""><figcaption><p>OpenCode</p></figcaption></figure></div>
{% endcolumn %}

{% column width="50%" %}

<div align="left"><figure><img src="/files/487daac6b83528be633e075e37e7d78bcd5e6b24" alt=""><figcaption><p>Hermes</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="33.33333333333333%" %}

<figure><img src="/files/ba5ea0951f50173ca4d82ee0919b69fad55007e1" alt=""><figcaption><p>Claude Code</p></figcaption></figure>
{% endcolumn %}

{% column width="33.33333333333333%" %}

<figure><img src="/files/be79f6a2937e966d83cac74f16c2a75606af1395" alt=""><figcaption><p>Codex</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/2e1027a97063d719f2de87511ff8cac6d9fa3177" alt=""><figcaption><p>Openclaw</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

### 连接到远程 Unsloth 服务器

在启动代理之前设置 Unsloth URL 和 API 密钥：

```bash
export UNSLOTH_STUDIO_URL=https://studio.example.com
export UNSLOTH_API_KEY=sk-unsloth-...
unsloth start claude
```

你也可以使用 `--api-key`传入密钥。对于经过 `unsloth start` 会自动创建或复用 API 密钥。

### 选项

| 选项                                           | 作用                                          |
| -------------------------------------------- | ------------------------------------------- |
| `--model`, `-m`                              | 选择一个模型。不指定时，使用 Unsloth 报告的第一个模型。            |
| `--api-key`                                  | 提供 Unsloth API 密钥。你也可以设置 `UNSLOTH_API_KEY`. |
| `--launch` / `--no-launch`                   | 启动代理或打印生成的环境和命令。                            |
| `--serve` / `--no-serve`                     | 允许或阻止自动启动本地服务器。                             |
| `--gguf-variant`                             | 选择一个 GGUF 量化变体。                             |
| `--context-length`, `--max-seq-length`       | 在加载模型时设置请求的上下文长度。                           |
| `--load-in-4bit` / `--no-load-in-4bit`       | 控制非 GGUF 的 Hugging Face 模型的 4 位加载。          |
| `--tensor-parallel` / `--no-tensor-parallel` | 为多 GPU 系统启用或禁用 tensor-parallel GGUF 加载。     |
| `--persist` / `--no-persist`                 | 在适用时保留由 Unsloth 管理的代理主目录。                   |
| `--yolo`                                     | 使用所选代理的非提示或信任模式。                            |
| `-h`, `--help`                               | 显示命令帮助。                                     |

当 Unsloth 需要加载或协调所请求的模型时，会使用加载选项。

### 向代理传递普通命令

不是 Unsloth 选项的参数会传递给所选代理：

```bash
unsloth start claude --continue
unsloth start codex --persist resume --last
unsloth start opencode run --continue "继续之前的任务"
unsloth start pi --persist --continue
```

请使用代理自己的帮助命令查看其完整的原生选项列表。

### 会话和 `--persist`

`--persist` 会保留受管存储。它不会自行恢复对话；还要传入代理的常规恢复命令。

| 代理           | 你需要 `--persist`?          | 恢复示例                                                       |
| ------------ | ------------------------- | ---------------------------------------------------------- |
| Claude Code  | 不需要。Claude 使用其常规会话存储。     | `unsloth start claude --continue`                          |
| OpenAI Codex | 需要。其受管的 Codex 主目录默认是临时的。  | `unsloth start codex --persist resume --last`              |
| OpenClaw     | 需要。受管配置、工作区和会话默认都是临时的。    | 使用 `--persist` 以及相同的原生会话 ID。                               |
| OpenCode     | 不需要。OpenCode 使用其常规会话存储。   | `unsloth start opencode run --continue "继续"`               |
| Hermes 代理    | 需要。其受管的 Hermes 主目录默认是临时的。 | `unsloth start hermes --persist --continue --oneshot "继续"` |
| Pi 编码代理      | 需要。其受管的 Pi 主目录默认是临时的。     | `unsloth start pi --persist --continue`                    |

对于 Codex、OpenClaw、Hermes 和 Pi，使用 `--persist` 在首次启动时，以及返回会话时再次使用。

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

```bash
unsloth start codex --persist
unsloth start codex --persist resume --last
```

{% endtab %}

{% tab title="OpenClaw" %}
为命名会话使用稳定的会话 ID：

```bash
unsloth start openclaw --persist \
  agent --local --session-id my-session --message "检查这个仓库"

unsloth start openclaw --persist \
  agent --local --session-id my-session --message "继续"
```

{% endtab %}

{% tab title="Hermes 代理" %}

```bash
unsloth start hermes --persist --oneshot "检查这个仓库"
unsloth start hermes --persist --continue --oneshot "继续"
```

{% endtab %}

{% tab title="Pi 编码代理" %}

```bash
unsloth start pi --persist --print "检查这个仓库"
unsloth start pi --persist --continue --print "继续"
```

{% endtab %}
{% endtabs %}

#### 打印启动命令而不执行它

```bash
unsloth start claude --no-launch
```

这会打印生成的环境和命令。输出可能包含连接凭据，因此不要在日志或截图中公开它。

### 绕过权限模式

`--yolo` 映射到所选代理的信任模式或非提示模式。它可以减少审批提示，并允许代理在未先询问的情况下运行命令。

{% hint style="warning" %}
仅在允许代理无限制执行操作的环境中使用它。
{% endhint %}

#### 常见问题

<details>

<summary>未找到 Unsloth 服务器</summary>

启动 Unsloth 并加载模型，或者传入 \`--model\`，这样 Unsloth 就能启动一个临时本地服务器。

</details>

<details>

<summary>Codex 无法连接</summary>

请使用通过 \`llama-server\` 运行的 GGUF 模型。当前 Codex 集成不使用 Unsloth transformers 后端。

</details>

<details>

<summary>会话未恢复</summary>

对于 Codex、OpenClaw、Hermes 和 Pi，请在首次及后续启动时使用 \`--persist\`，然后传入代理原生的恢复选项。

</details>


---

# 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/unsloth-start.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.