Hugging Face's logo

Hub documentation

使用 llama.cpp 的本地代理

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

使用 llama.cpp 的本地代理

您可以完全在自己的硬件上运行编码智能体。多个开源智能体可以连接到本地的 llama.cpp 服务器，为您提供类似 Claude Code 或 Codex 的体验——但所有操作都在您的机器上运行。

入门

1. 设置您的本地硬件

设置您的本地硬件，以便查看哪些模型与您的配置兼容。

前往 huggingface.co/settings/hardware 并配置您的本地硬件配置。然后在 本地应用设置 中选择 llama.cpp，因为这将是你使用的引擎。

2. 查找兼容的模型

浏览与 Llama.cpp 兼容的模型。

3. 启动 llama.cpp 服务器

在模型页面，点击 “使用此模型” 按钮并选择 llama.cpp。它会显示适用于你环境的准确命令。第一步是启动一个 llama.cpp 服务器，例如

llama-server -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

这将下载模型并在您的机器上启动一个兼容 OpenAI 的 API 服务器。有关安装说明，请参阅 llama.cpp 指南。

4. 连接您的 Agent

选择以下其中一个智能体，并按照设置说明进行操作。

Pi

Pi 是 OpenClaw 背后的智能体，现已直接集成到 Hugging Face 中，为您提供数千个兼容模型。

安装 Pi：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

然后，将您的本地模型添加到 Pi 位于 ~/.pi/agent/models.json 的配置文件：

{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "ggml-org-gemma-4-26b-4b-gguf"
        }
      ]
    }
  }
}

在您的项目目录中启动 Pi：

pi

Pi 连接到您本地的 llama.cpp 服务器，并为您提供一个交互式智能体会话。

Demo

启用视觉支持

对于支持视觉的模型，请在 ~/.pi/agent/models.json 中的模型条目里添加 "input": ["text", "image"]：

"models": [
  {
    "id": "unsloth/Qwen3.6-35B-A3B-GGUF:Q4_K_XL",
    "input": ["text", "image"]
  }
]

浏览与 Pi 兼容的视觉语言模型。

OpenClaw

OpenClaw 可在本地与 llama.cpp 配合使用。您可以通过内置命令设置模型：

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "http://127.0.0.1:8080/v1" \
  --custom-model-id "ggml-org-gemma-4-26b-a4b-gguf" \
  --custom-api-key "llama.cpp" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --accept-risk

您也可以交互式地运行 openclaw onboard，选择 custom-compatibility 并指定 openai，然后传入相同的配置。

OpenClaw 的本地内存搜索

您可以使用 Llama.cpp 运行本地嵌入模型，用于智能体的记忆搜索。为此，请确保已安装 node-llama-cpp。

npm i node-llama-cpp

以下是一个示例代码片段，用于在本地运行量化后的 EmbeddingGemma-300M 以进行内存搜索。OpenClaw 会自动下载模型，并通过以下命令提供服务。

openclaw config set agents.defaults.memorySearch.provider local
openclaw config set agents.defaults.memorySearch.local.modelPath "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"

重启网关并验证。

openclaw gateway restart
openclaw memory status
# Memory Search (main)
# Provider: local (requested: local)
# Model: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf

Hermes Agent

Hermes Agent 可在本地与 llama.cpp 配合使用。将默认配置定义为：

model:
  provider: custom
  default: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M
  base_url: http://127.0.0.1:8080/v1
  api_key: llama.cpp

custom_providers:
  - name: Local (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
    api_key: llama.cpp
    model: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M

### Hermes Agent 的本地内存搜索

Hermes Agent 通过端点使用语义搜索模型。一旦你使用 llama.cpp 或你选择的推理引擎将首选的嵌入模型部署到 8080 端点，请将以下内容添加到 ~/.hermes/config.yaml。

auxiliary:
  session_search:
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "no-key-required"
    model: "local-llama" # your model alias
    timeout: 90
    max_concurrency: 1

检查此操作是否有效，none - built-in only 表示未使用其他内存插件。以下输出表明本地服务已处于活动状态。

$ hermes memory status
# Memory status
#────────────────────────────────────────
#  Built-in:  always active
#  Provider:  (none — built-in only)

OpenCode

OpenCode 可配合 llama.cpp 在本地运行。请定义一个 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "gemma-4-26b-4b-it": {
          "name": "Gemma 4 (local)",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  }
}

工作原理

该设置包含两个在本地运行的组件：

  1. llama.cpp 服务器 — 在 localhost 上以兼容 OpenAI 的 API 形式提供模型服务。
  2. 您的智能体 — 负责向本地服务器发送提示、对任务进行推理并执行操作的智能体进程。
┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

替代方案：llama-agent

llama-agent 采用了不同的方法——它将智能体循环直接构建到 llama.cpp 中，作为一个零外部依赖的单一二进制文件。无需 Node.js，无需 Python，只需编译并运行：

git clone https://github.com/gary149/llama-agent.git
cd llama-agent

# Build
cmake -B build
cmake --build build --target llama-agent

# Run (downloads the model automatically)
./build/bin/llama-agent -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

由于工具调用在进程内执行，而非通过 HTTP 进行，模型与智能体之间不存在网络开销。它还支持子智能体、MCP 服务器以及 HTTP API 服务器模式。

后续步骤

Update on GitHub

←使用 HF SDK 构建智能体 Agent 库→