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 に移動し、ローカルハードウェアプロファイルを構成してください。次に、Local Apps settings で 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. エージェントを接続する

以下のエージェントから1つを選択し、セットアップ手順に従ってください。

Pi

PiはOpenClawの背後にあるエージェントであり、現在Hugging Faceに直接統合されています。これにより、数千の互換性のあるモデルにアクセスできます。

Piのインストール:

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

次に、ローカルモデルを~/.pi/agent/models.jsonにあるPiの設定ファイルに追加します:

{
  "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
          }
        }
      }
    }
  }
}

仕組み

セットアップには、ローカルで実行される2つのコンポーネントがあります。

  1. llama.cpp server — モデルを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 を用いたエージェントの構築 エージェントライブラリ→