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

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

### 快速开始

首先，确保你已经 [安装了 Unsloth](/docs/zh/xin-zeng/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>

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

{% hint style="success" %}
如果没有设置任何设置/采样标志，Unsloth 会自动为该模型选择最佳/推荐设置，包括上下文长度、温度等。
{% endhint %}

```bash
unsloth start claude \
  --model unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL \
  --context-length 32768 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 20 \
  --min-p 0.0 \
  --reasoning-effort medium
```

该 `:UD-Q4_K_XL` 后缀会选择 GGUF 量化。

在默认本地地址上，传入 `--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 服务器， `unsloth start` 会自动创建或复用 API 密钥。

### 标志 + 选项

如果没有设置任何设置/采样标志，Unsloth 会自动为该模型选择最佳/推荐设置，包括上下文长度、温度等。

否则，你可以按如下方式自定义这些标志：

| 选项                                           | 作用                                                           |
| -------------------------------------------- | ------------------------------------------------------------ |
| `--model`, `-m`                              | 选择一个模型。如果不指定，则使用 Unsloth 报告的第一个模型。                           |
| `--api-key`                                  | 提供一个 Unsloth API 密钥。你也可以设置 `UNSLOTH_API_KEY`.                |
| `--launch` / `--no-launch`                   | 启动代理或打印生成的环境和命令。                                             |
| `--serve` / `--no-serve`                     | 允许或阻止自动启动本地服务器。                                              |
| `--gguf-variant`                             | 选择一种 GGUF 量化变体。                                              |
| `--reasoning`                                | 在聊天中使用推理：on、off 或 auto。auto 遵循模型的聊天模板，通常意味着 on。              |
| `--reasoning-effort`                         | 传递给模型聊天模板的推理强度，例如 medium。级别因模型而异，因此请使用该模型接受的值。不设置则保持模板自身的设置。 |
| `--context-length`, `--max-seq-length`       | 加载模型时设置请求的上下文长度。                                             |
| `--load-in-4bit` / `--no-load-in-4bit`       | 控制非 GGUF Hugging Face 模型的 4 位加载。                             |
| `--tensor-parallel` / `--no-tensor-parallel` | 为多 GPU 系统启用或禁用张量并行 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 "Continue"`               |
| Hermes 代理    | 需要。其受管理的 Hermes 主目录默认是临时的。 | `unsloth start hermes --persist --continue --oneshot "Continue"` |
| 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 "Continue"
```

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