# llama.cppによるローカルエージェント

コーディングエージェントをローカルで、完全に自分のハードウェア上で実行できます。複数のオープンソースのエージェントがローカルの[llama.cpp](https://llama.app/)サーバーに接続でき、Claude CodeやCodexに似た体験を提供します。ただし、すべてはあなたのマシン上で実行されます。

## 仕組み

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

1. **llama.cpp server** — モデルを`localhost`上でOpenAI互換のAPIとして提供します。
2. **エージェント** — ローカルサーバーにプロンプトを送信し、タスクについて推論し、アクションを実行します。

```shell
┌─────────┐     API calls     ┌───────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └───────────────────┘
     │
     ▼
  Your files,
  terminal, etc.
```

## llama.cppサーバーのセットアップ

### 1. ローカルハードウェアを設定する

ローカルハードウェアを設定し、お使いの環境と互換性のあるモデルを確認できるようにします。

[huggingface.co/settings/hardware](https://huggingface.co/settings/hardware) に移動して、ローカルハードウェアプロファイルを構成してください。次に、[Local Apps settings](https://huggingface.co/settings/local-apps) で `llama.cpp` を選択してください。これが使用するエンジンとなるためです。

### 2. 互換性のあるモデルを見つける

[Llama 互換の GGUF モデル](https://huggingface.co/models?apps=llama-app&sort=trending)を閲覧してください。選択後、お使いのハードウェアにモデルをダウンロードします。

インスピレーションが必要な場合は、Llama アプリがハードウェアデバイスに合ったモデルをいくつか提案します（ステップ 3 を参照）。

### 3. Llama アプリのインストール

llama.cppは、お使いのマシンに簡単にインストールできます。

- **MacおよびWindows**: システムトレイに常駐するミニマルなデスクトップアプリである[Llama app](https://llama.app)をインストールします。アプリケーションのインストール後、システムに推奨されるお気に入りのモデルを使い始めるための手順に従ってください。![llama app](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/decision/llama-app.png)
- **Linux（またはコマンドラインのみを使用する場合）**：1行のインストールコマンド：
     ```bash
     curl -LsSf https://llama.app/install.sh | sh
     ```

インストールを確認します:

```bash
llama --version
```

### 4. ルーターを起動します

デスクトップアプリをインストールした場合は、`llama serve`がすでに実行されています。[localhost:9931](http://localhost:9931/#/models)でモデルリストを閲覧することにより、確認できます。

そうではない場合は、`llama serve`を開始してください。モデルを渡すと、ルーターモードではなく単一モデルモードが開始されます。ルーターの構成については、[llama.cpp サーバーガイド](https://llama.app/docs/serve#serving-multiple-models-router-mode)を参照してください。

2つのオプションがあります：
- 自動読み込み: デフォルトでは、モデルはオンデマンドで読み込まれます。
- 手動読み込み: `--no-models-autoload` を追加し、モデルを選択する前に `/llama` を使用してモデルを読み込みます。

自動読み込みを行うには、次のように起動します:

```bash
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](https://pi.dev)は[OpenClaw](https://github.com/openclaw)の背後にあるエージェントであり、現在Hugging Faceに直接統合されています。これにより、数千の互換性のあるモデルにアクセスできます。

Piのインストール:

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

プロジェクトディレクトリでPiを開始します:

```bash
pi
```

llama.cppを設定します：

```bash
/login llama.cpp
```

`/llama` を実行してモデルを読み込み、その後 `/model` を実行して、現在のセッションでその読み込まれたモデルを選択します。

## OpenClaw

[OpenClaw](https://github.com/openclaw)はllama.cppとローカルで動作します。オンボードコマンドでモデルを設定できます。

```bash
openclaw plugins install @openclaw/llama-cpp-provider
openclaw onboard
```

### OpenClawのローカルメモリ検索

Llama.cpp を使用して、エージェントのメモリ検索にローカルの埋め込みモデルを実行できます。そのためには、node-llama-cpp がインストールされていることを確認してください。

```bash
npm i node-llama-cpp 
```

メモリ検索用に[量子化されたEmbeddingGemma-300M](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF?show_file_info=embeddinggemma-300M-Q8_0.gguf)をローカルで実行するための例を示します。OpenClawは、以下のコマンドでモデルを自動的にダウンロードしてサーブします。

```bash
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"
```

ゲートウェイを再起動して、検証してください。

```bash
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](https://hermes-agent.nousresearch.com/)はllama.cppとローカルで動作します。`~/.hermes/config.yaml`に以下を追加してください。

```yaml
custom_providers:
  - name: llama cpp (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
```

### Hermes Agent 用のローカルメモリ検索

Hermes Agent はエンドポイント経由でセマンティック検索モデルを利用します。llama.cpp やお好みの推論エンジンで、希望する埋め込みモデルをポート 8080 のエンドポイントで起動したら、`~/.hermes/config.yaml` に以下を追加してください。

```bash
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`が表示されている場合、他のメモリプラグインは使用されていないことを示しています。以下の出力は、ローカルサービングが有効であることを示しています。

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

## OpenCode

[OpenCode](https://opencode.ai)はllama.cppとローカルで動作します。`~/.config/opencode/opencode.json`を定義してください:

```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](https://github.com/gary149/llama-agent)は異なるアプローチを採用しています。[llama.cpp](https://github.com/ggerganov/llama.cpp)にエージェントループを直接組み込み、外部依存がゼロの単一のバイナリとして動作します。Node.jsもPythonも不要で、コンパイルして実行するだけです：

```bash
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モデルをローカルで使用する](./local-apps) — モデルを自分のマシンで実行する方法について詳しく学ぶ
- [llama.cpp ガイド](./gguf-llamacpp) — llama.cpp のインストールと使用方法の詳細
- [Hub上のエージェント](./agents-overview) — エージェントをHugging Faceエコシステムに接続

