> 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 以及其他编码代理，通过 `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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FpXE6kCHjh8qOEaggf94M%2FScreenshot_20260718_122426.png?alt=media&amp;token=a59e4c8c-efdb-451b-b1f8-621955564f6d" alt=""><figcaption><p>在本地使用 Qwen3.5 运行 Claude Code。</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-deepseek">:deepseek:</i> DeepSeek Harness             | `unsloth start dsh`      |
| <i class="fa-rectangle-vertical">:rectangle-vertical:</i> OpenCode | `unsloth start opencode` |
| <i class="fa-caduceus">:caduceus:</i> Hermes Agent                 | `unsloth start hermes`   |
| <i class="fa-lobster">:lobster:</i> OpenClaw                       | `unsloth start openclaw` |
| <i class="fa-pi">:pi:</i> Pi Agent                                 | `unsloth start pi`       |

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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FT8nv3UJzIrcxmjSn8OfW%2Fclaude-code.webp?alt=media&amp;token=811f9635-7321-427c-a11e-29a40e49e376">claude-code.webp</a></td><td><a href="/docs/zh/ji-chu/claude-code.md">Claude Code</a></td></tr><tr><td>Codex</td><td><a href="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FLxRuVHEBYywquhRGBYu0%2Fcodex%20only%20logo.png?alt=media&amp;token=7faa9cbd-090a-45dc-9d5e-acb1a9591f27">codex only logo.png</a></td><td><a href="/docs/zh/ji-chu/codex.md">OpenAI Codex</a></td></tr><tr><td>Hermes Agent</td><td><a href="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F6ysPTzsXIO5diu4vOTCh%2Fimages.jpeg?alt=media&amp;token=5cc58141-69eb-4450-8214-7a8421fbe2a5">images.jpeg</a></td><td><a href="/docs/zh/ji-cheng/hermes-agent.md">Hermes Agent</a></td></tr><tr><td>OpenClaw</td><td><a href="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FAd5uo6LjavtBrrKZfwZ3%2Fopenclaw-hero-light.png?alt=media&amp;token=3097e40f-e80c-4c9c-8efc-02ecf5530ef6">openclaw-hero-light.png</a></td><td><a href="/docs/zh/ji-cheng/openclaw.md">OpenClaw</a></td></tr><tr><td>OpenCode</td><td><a href="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FlCi6Ab4f2qLlNj2EWGL0%2Fopencodelogo.png?alt=media&amp;token=6118773e-5392-4718-a431-a50157a34cbe">opencodelogo.png</a></td><td><a href="/docs/zh/ji-cheng/opencode.md">OpenCode</a></td></tr><tr><td>Unsloth API</td><td><a href="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FoRer1Vbuh9wSPTawz0ey%2Funsloth%20api%20long%20logo.png?alt=media&amp;token=860a8143-9d59-466b-abed-6ea7d67e51fd">unsloth api long logo.png</a></td><td><a href="/docs/zh/ji-chu/api.md">Unsloth API</a></td></tr></tbody></table>

### 从命令行加载模型

<div align="center"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FAOqECGHODYPDGeYDpXOz%2Fwasim%20unslothstart.png?alt=media&amp;token=a7a1bf5e-d964-4bd4-a0d0-f86753e9f5a8" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fmhay2zcaqL5mNNBeYwKv%2FScreenshot_20260717_163314.png?alt=media&amp;token=5a1e2f04-92b1-42f1-adac-9494fb43613a" alt=""><figcaption><p>OpenCode</p></figcaption></figure></div>

{% endcolumn %}

{% column width="50%" %}

<div align="left"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnrT2lJtpD4uwMkn5HAhO%2FScreenshot_20260717_163427.png?alt=media&amp;token=ffe77a32-05a9-439e-845f-5a7a4b034464" alt=""><figcaption><p>Hermes</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

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

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FfKxk4eUVf0tZB1IFtava%2FScreenshot_20260717_161638.png?alt=media&amp;token=b709f099-704e-4d97-947e-d75cbf43cd8a" alt=""><figcaption><p>Claude Code</p></figcaption></figure>
{% endcolumn %}

{% column width="33.33333333333333%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FxPckgHYLacJK1jpwXHOR%2FScreenshot_20260717_163145.png?alt=media&amp;token=e61f7404-341e-474b-bc08-59adc66ce274" alt=""><figcaption><p>Codex</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fy5QNC3RaSkCIr1KFBrMd%2FScreenshot_20260717_163831.png?alt=media&amp;token=e1501dbe-6a2b-4a4d-96df-92a3e8f2f3df" 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 "Continue the previous task"
unsloth start pi --persist --continue
```

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

### 会话和 `--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 Agent | 需要。其受管理的 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 "Inspect this repository"

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

{% endtab %}

{% tab title="Hermes Agent" %}

```bash
unsloth start hermes --persist --oneshot "Inspect this repository"
unsloth start hermes --persist --continue --oneshot "Continue"
```

{% endtab %}

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

```bash
unsloth start pi --persist --print "Inspect this repository"
unsloth start pi --persist --continue --print "Continue"
```

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