> 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 编码 Agent

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/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-vscode">:vscode:</i> Visual Studio Code               | `unsloth start vscode`   |
| <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 提供方。

### 代理指南

<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-zhi-shi/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-zhi-shi/codex.md">OpenAI Codex</a></td></tr><tr><td>Visual Studio Code</td><td><a href="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FsBmg9gZ062wIQDAuibJ7%2Fvscode-card.png?alt=media&amp;token=1659960f-0876-4469-a6a7-7408e7a6570a">vscode-card.png</a></td><td><a href="/docs/zh/ji-cheng/ru-he-zai-vs-code-zhong-yun-xing-ben-di-ai-mo-xing.md">Run models in VS Code</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></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 密钥。

#### 在 VS Code 中使用 Unsloth

将本地模型连接到 VS Code 的 Copilot Chat。需要 GitHub Copilot Chat 扩展；不需要 Copilot 订阅方案。

```bash
# 连接 Unsloth 已在提供服务的模型
unsloth start vscode

# 或加载一个具有 32K 上下文的模型以用于 Agent 模式
unsloth start vscode unsloth/Qwen3.5-4B-GGUF:UD-Q4_K_XL --context-length 32768
```

打开 Copilot Chat，并在下方选择你的模型 **Unsloth**。如果它缺失，请检查 **管理模型** 或者运行 **开发者：重新加载窗口**.

Agent 模式需要工具调用支持，并且至少需要 **32K 上下文**。对于不支持工具调用的模型，请使用 Ask 模式。

该命令会备份你的 VS Code 配置并保留其他模型。切换模型后，请重新运行 `unsloth start vscode` 以更新其条目。

**远程服务器：** 在没有 VS Code 用户目录的 SSH 或容器会话中，该命令会打印需要在本地添加的配置，以及连接或端口转发说明。如果在远程工作区的模型选择器中看不到该模型，请使用本地 VS Code 窗口。

### 标志 + 选项

如果没有设置采样/参数标志，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 遵循模型的聊天模板，这通常意味着开启。                  |
| `--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 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 "检查这个仓库"

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

{% endtab %}

{% tab title="Hermes Agent" %}

```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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/zh/ji-cheng/unsloth-start.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.