Hub documentation
llama.cppによるローカルエージェント
llama.cppによるローカルエージェント
コーディングエージェントをローカルで、完全に自分のハードウェア上で実行できます。複数のオープンソースのエージェントがローカルのllama.cppサーバーに接続でき、Claude CodeやCodexに似た体験を提供します。ただし、すべてはあなたのマシン上で実行されます。
仕組み
セットアップには、ローカルで実行される2つのコンポーネントがあります。
- llama.cpp server — モデルを
localhost上でOpenAI互換のAPIとして提供します。 - エージェント — ローカルサーバーにプロンプトを送信し、タスクについて推論し、アクションを実行します。
┌─────────┐ API calls ┌───────────────────┐
│ Agent │ ───────────────▶ │ llama.cpp server │
│ │ ◀─────────────── │ (local model) │
└─────────┘ responses └───────────────────┘
│
▼
Your files,
terminal, etc.llama.cppサーバーのセットアップ
1. ローカルハードウェアを設定する
ローカルハードウェアを設定し、お使いの環境と互換性のあるモデルを確認できるようにします。
huggingface.co/settings/hardware に移動し、ローカルハードウェアプロファイルを構成してください。次に、Local Apps settings で llama.cpp を選択してください。これが使用するエンジンとなるためです。
2. 互換性のあるモデルを見つける
Llama 互換の GGUF モデルを閲覧してください。選択後、お使いのハードウェアにモデルをダウンロードします。
インスピレーションが必要な場合は、Llama アプリがハードウェアデバイスに合ったモデルをいくつか提案します(ステップ 3 を参照)。
3. Llama アプリのインストール
llama.cppは、お使いのマシンに簡単にインストールできます。
- MacおよびWindows: システムトレイに常駐するミニマルなデスクトップアプリであるLlama appをインストールします。
アプリケーションのインストール後、システムに推奨されるお気に入りのモデルを使い始めるための手順に従ってください。

- Linux (or if you only want the command line): 1行のインストールコマンド:
curl -LsSf https://llama.app/install.sh | sh
インストールを確認します:
llama --version
4. ルーターを起動します
デスクトップアプリをインストールした場合は、llama serveがすでに実行されています。localhost:9931でモデルリストを閲覧することにより、確認できます。
そうではない場合は、llama serveを開始してください。モデルを渡すと、ルーターモードではなく単一モデルモードが開始されます。ルーターの構成については、llama.cpp サーバーガイドを参照してください。
2つのオプションがあります:
- 自動読み込み: デフォルトでは、モデルはオンデマンドで読み込まれます。
- 手動読み込み:
--no-models-autoloadを追加し、モデルを選択する前に/llamaを使用してモデルを読み込みます。
自動読み込みを行うには、次のように起動します:
llama serve
ほとんどの場合、デフォルト値が適切に設定されているため、追加のフラグは不要です。高度な利用を想定した場合、以下に、関心を持つ可能性のあるフラグの例を示します。
-ngl allはすべてのレイヤーを GPU にオフロードします。自動 GPU オフロードを使用する場合は、このオプションを省略してください。-c 32768はトークン単位のコンテキストサイズを設定します。モデルのフルコンテキストウィンドウを使用するには-c 0を使用してください。これにより、大幅に多くのメモリが必要になる場合があります。コンテキストは並列サーバーのスロット間で共有されます。--models-dir ~/modelsは、カスタムのローカルディレクトリからローカルの GGUF ファイルを検出します。
上記のコマンドだけで十分ですが、llama serveでよく使われるフラグをいくつか紹介します。
| フラグ | 機能 |
|---|---|
-ngl all | すべてのレイヤーをGPUにオフロードします |
-c 32768 | トークン単位のコンテキストサイズを設定します |
--models-dir ~/models | カスタムローカルディレクトリからローカルGGUFファイルを検出します |
5. エージェントを接続する
以下のエージェントから1つを選択し、セットアップ手順に従ってください。
Pi
PiはOpenClawの背後にあるエージェントであり、現在Hugging Faceに直接統合されています。これにより、数千の互換性のあるモデルにアクセスできます。
Piのインストール:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
プロジェクトディレクトリでPiを開始します:
pi
llama.cppを設定します:
/login llama.cpp
/llama を実行してモデルを読み込み、その後 /model を実行して、現在のセッションでその読み込まれたモデルを選択します。
OpenClaw
OpenClawはllama.cppとローカルで動作します。オンボードコマンドでモデルを設定できます。
openclaw plugins install @openclaw/llama-cpp-provider openclaw onboard
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.ggufHermes Agent
Hermes Agentはllama.cppとローカルで動作します。~/.hermes/config.yamlに以下を追加してください。
custom_providers:
- name: llama cpp (127.0.0.1:8080)
base_url: http://127.0.0.1:8080/v1Hermes 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
}
}
}
}
}
}代替案: 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 サーバーモードにも対応しています。
次のステップ
- AIモデルをローカルで使用する — モデルを自分のマシンで実行する方法について詳しく学ぶ
- llama.cpp ガイド — llama.cpp のインストールと使用方法の詳細
- Hub上のエージェント — エージェントをHugging Faceエコシステムに接続