如何将 Unsloth 作为 API 终端节点使用

你可以运行 本地 LLM 配合如下工具： Claude Code 和 Codex ，只需将这些工具连接到 Unsloth 的 兼容 OpenAI 的 API 端点。这让你可以本地运行如下模型： Qwen 和 Gemma ，用于智能代理式编程。Unsloth 还具备一些有益功能，例如自愈式 工具调用, 代码执行，以及 网页搜索.

Unsloth 让你很容易部署一个快速的 API 推理端点，提供：

• 自愈式工具调用，可将损坏或格式错误的工具调用减少 50%

• 代码执行 支持，可进行 Bash 和 Python 执行，从而获得更准确的代码输出。

• 高级 网页搜索 会访问并实际读取网页，以收集深入信息。

• 自动推理 设置 适用于 GGUF 模型（temp、top-k 等）

在 Unsloth 中加载的模型（包括 GGUF）会以 已认证 API 的形式通过 llama-server 暴露。出于安全考虑，会生成一个较长的 API 密钥，就像 OpenAI 提供的一样。

你的 本地模型 随后可直接在你偏好的 AI Agent、SDK 或聊天客户端中使用。Unsloth 在同一个端口上提供两种接口格式。两者都支持流式输出、工具调用（OpenAI 工具 / Anthropic 工具），以及视觉输入：

无论你的模型是通过 Unsloth 的推理运行，还是通过你自己的远程兼容 OpenAI 的端点运行，你都可以让它使用 Unsloth 的完整工具集，包括网页搜索、代码执行、深度研究等。

• 兼容 Anthropic 的 /v1/messages ，适用于 Claude Code、OpenClaw、Anthropic SDK，以及任何期望 Messages API 的客户端。

• 兼容 OpenAI 的 /v1/chat/completions 和 /v1/responses ，适用于 OpenAI SDK、OpenCode、Cursor、Continue、Cline、Open WebUI、SillyTavern，以及任何兼容 OpenAI 的工具。

⚡ 快速开始

1

下载 Unsloth

最简单的开始方式是安装 Unsloth Desktop 应用。它支持 MacOS、Linux、 Windows, NVIDIA, AMD、Intel 和 CPU 配置。

下载 Unsloth

• 下载 macOS 版

• 下载 Windows 版

• 下载 Linux 版

或者，如果你更喜欢手动安装：

MacOS、Linux、WSL：

复制

curl -fsSL https://unsloth.ai/install.sh | sh

Windows PowerShell：

复制

irm https://unsloth.ai/install.ps1 | iex

2

安装

1. 打开 Unsloth 安装程序（.dmg, .exe 文件）

2. 在 Mac 上将 Unsloth 拖到 Applications，或在 Windows 上完成安装。

3. 启动应用并等待安装完成

3

选择模型

打开顶部的“选择模型”下拉菜单或“Model hub”标签页，选择适合你设备的模型和量化方案，然后下载。完成后即可开始聊天——无需额外设置。

4

Unsloth 现在已准备就绪

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

• 创建 API 密钥。 点击左下角的 Unsloth 头像 → 设置 → API → 输入密钥名称 → 创建。复制出现的 sk-unsloth-… 值。Unsloth 只会显示一次。

• 将你的客户端指向 Unsloth。 使用 http://localhost:PORT 作为 base URL，并使用你的 sk-unsloth-… 密钥进行认证。请跳到下方对应工具的教程。

🔑 创建 API 密钥

1. 打开侧边栏，点击左下角的 Unsloth 头像。

2. 前往 设置 → API （地球 🌐 图标）。

3. 输入一个友好的名称（例如 claude-code-macbook）。设置过期时间（可选）

4. 点击 创建.

5. 复制密钥。 Unsloth 只存储哈希值，你将无法再次查看它。

所有密钥都以 sk-unsloth- 前缀开头。你可以随时在同一页面撤销某个密钥。使用已撤销密钥的请求将失败，并返回 401 未授权.

⏳ 模型加载

1

选择模型

在使用 API 之前，请先从 Chat 页面左上角的 选择模型 下拉菜单中加载一个模型。

在本指南中，我们将使用：

unsloth/gemma-4-26B-A4B-it-GGUF 以及推荐的 UD-Q4_K_XL 量化。

2

测试模型

在使用客户端之前，先发送一条简短消息：

这可以确认模型已正确加载并准备响应。

3

Unsloth API 密钥

在 Unsloth 中，打开 设置 → API 即可查看或创建你的 API 密钥。

请将你的 API 密钥视为密码，避免在截图或仓库中暴露它。

Unsloth 运行命令

1. 安装或更新 Unsloth Studio。 早期版本不暴露外部 API。请参见安装。

2. 加载 GGUF 模型。 使用运行命令加载 GGUF 模型。这也会在默认端口上加载 UI。端点 URL 和 API Key 会打印到控制台，供你直接在所选客户端中使用。

按需调整设置。

通过 CLI 加载模型

你可以使用 unsloth CLI 工具加载模型，并自动为你创建 API 密钥。模型加载完成后，端点 URL 和 API key 会打印到控制台。将它们复制到你选择的客户端中，就可以开始了。

开始之前

请确保你使用的是较新的 Unsloth Studio 版本，因为早期版本不暴露外部 API。参见 安装.

快捷方式

打开终端并加载一个 GGUF 模型：

这会在默认端口启动服务器、加载 UI，并打印你的端点 URL 和 API key。

模型名称的工作方式

你可以通过几种不同方式指定模型。选择你觉得最简单的一种：

调整运行参数（可选）

基础加载时你不需要这些，但 unsloth run 支持许多 llama-server 运行时参数，用于自定义性能、内存使用、上下文长度、生成行为、网络和工具访问。

额外参数会直接传递给底层推理服务器，你的值会覆盖 Unsloth 的默认值。如果没有设置 settings/sampling 参数，Unsloth 会自动为模型选择最佳/推荐设置，包括上下文长度、temperature 等。

控制推理行为

某些具备推理能力的模型支持额外参数，用于控制思考和推理行为。

推理强度和参数取决于模型所支持的内容。

调整生成行为

采样设置决定模型在生成时的创造性、聚焦程度或确定性。

较低的 temperature 通常会产生更稳定的输出，而 top-p、top-k、min-p 和 repeat penalty 设置则进一步控制 token 选择和重复。

增加上下文长度和 CPU 线程数

当你处理大型项目、长对话或需要更多内存的 agent 工作流时，这很有用。

在本地网络上暴露 API

默认情况下，Unsloth 仅在你的机器本地运行。你可以通过绑定到以下地址，将 API 暴露给网络中的其他设备： 0.0.0.0.

启用或禁用服务器端工具

控制像网页搜索和代码执行这样的工具是否由推理服务器暴露。

Unsloth 支持大多数 llama-server 运行时参数，包括上下文大小、GPU 层数、线程、采样、网络和工具配置。

请参见 llama-server 文档以获取受支持运行时参数的完整列表。

服务器端工具策略

unsloth run 控制服务器端工具（网页搜索、代码执行等）是否由推理服务器暴露。默认值基于绑定地址：

• 127.0.0.1 （localhost） — 工具 开启 ，默认开启。只有你的机器可以访问该服务器。

• 0.0.0.0 或任何非回环地址 — 工具 关闭 ，默认关闭。在网络暴露的服务器上泄露 API 密钥，意味着主机上可被任意代码执行。

参数：

• --enable-tools / --disable-tools — 强制开启或关闭。开启 0.0.0.0, --enable-tools 会显示一个 y/N 安全提示。

• --yes / -y — 跳过提示（用于自动化）。

已解析的策略是进程级的硬性覆盖——单个请求不能通过 enable_tools=true 在请求体中绕过它。

🌐 端点

Unsloth 会在其启动的任意端口上暴露这些端点（通常是 http://localhost:8000 或 http://localhost:8888):

使用一个 Authorization: Bearer sk-unsloth-… 头部进行每次请求的认证。

🖇️ 连接你的客户端

Unsloth 让你可以通过大多数框架运行本地 LLM，包括 Claude Code, Codex, OpenClaw, OpenCode 等更多工具。点击下方的具体工具查看指南：

要从另一台机器访问此端点，请使用 unsloth studio --secure启动。Unsloth 会保持绑定到 localhost，并通过一个免费的 Cloudflare HTTPS URL 对外发布；请使用该 URL 代替 http://127.0.0.1:8888 作为你客户端的 base URL。请注意，服务器发送事件无法通过 Cloudflare quick tunnel 保持连接，因此当通过该隧道调用时，请设置 stream: false 。

🧰 工具调用

两个端点都支持其原生格式的函数/工具调用，另外还提供了一个针对 Unsloth 内置工具的 Unsloth 专用简写。

OpenAI 风格的工具： 发送 工具 和 tool_choice 到 /v1/chat/completions ，就像你使用 OpenAI 时那样。Claude Code（通过 /v1/messages） 、opencode、Cursor、Continue 和 Cline 都能开箱即用。

Anthropic 风格的工具： 发送 工具 （使用 input_schema）以及 tool_choice 到 /v1/messages ，就像你使用 Claude 时那样。

Unsloth 服务端工具：Unsloth 可以在 服务器端 执行 Python、网页搜索和 bash，并将结果以 tool_result 事件流式返回。通过向任一端点添加以下额外字段即可启用：

模型会在下一轮看到每个工具的输出。关于更深入的覆盖（schema、流式事件、链式调用），请参见。

📈 API 监控

通过此端点的每一次调用都会实时列在 Studio 中，分布在两个位置：

一旦有 API key 流量到达，API 监控侧边栏就会自动在角落打开。它会汇总当前活动模型、实时请求、错误和平均延迟。

点击“展开为完整监控”或前往 设置 > API Monitor 进入完整 API 页面，其中会显示模型加载、提示词、响应、token 数、首 token 耗时、吞吐量和错误信息。

❔ 故障排查

401 未授权 ： 要么 Authorization 头缺失，要么密钥错误。密钥必须以 Authorization: Bearer sk-unsloth-…的形式传入。如果你丢失了密钥，请从 设置 → API。 Unsloth 在创建后不会显示旧密钥。

与模型服务器的连接丢失 ：Unsloth 无法连接到底层的 llama.cpp 服务器。通常是模型已完成加载但崩溃了，或者在 Unsloth 中关闭了模型标签页。从 新聊天 ，然后重试。

Claude Code 显示的是默认的 Anthropic 模型，而不是我的本地模型 ：检查这三个环境变量都已在 同一个 运行 claude:

然后运行 /model 在 Claude Code 中确认。在 Windows PowerShell 中使用 $env:ANTHROPIC_BASE_URL 等等。

流式：true 返回单个 JSON 数据块，而不是 SSE ：确保你命中了正确的路径（/v1/messages 或 /v1/chat/completions）并且你的 HTTP 客户端确实是以流的方式消费响应，而不是把它缓冲起来。

我找不到要添加到 opencode（或 OpenClaw / 任何其他客户端）中的模型名称 ：直接询问 Unsloth。 GET /v1/models 返回你需要填入客户端“模型 ID”字段的确切模型 ID：

你会收到如下形式的 JSON 负载 {"data": [{"id": "gemma-4-26B-A4B-it-GGUF", ...}]}。复制出现的 标识符 值，这就是 opencode 的字符串 模型 ID 字段（左列）以及 OpenClaw 的 models[].id 所期望的。右侧的显示名称则是你希望用户看到的内容。

工具调用未执行 ：模型需要支持工具调用，才能使用客户端工具（工具 / tool_choice）。对于 Unsloth 的内置工具，记得设置 enable_tools: true 和 在 enabled_tools （例如 ["python", "web_search"]).

• 我的客户端报告连接错误。 打开 API 监视器。如果该调用没有对应的行，说明它从未到达 Unsloth，请将你的客户端基础 URL 与 基础 URL 该页面顶部显示的内容。

• 回复被截断了。 检查 使用的上下文 在 API 监视器中的该请求上。接近 100%，或停止原因是 长度，表示是上下文窗口已满，而不是模型失败。