Emacs の gptel から Ollama が動かないときの切り分け手順

gptel から Ollama を利用できないときは、「ローカル LLM が動かない」という一つの問題として調べるのではなく、次の順番で失敗箇所を狭めます。

1. Ollama API へ接続できるか
2. gptel に指定したモデルが Ollama に存在するか
3. Ollama API へ直接要求すると生成できるか
4. gptel が同じ接続先とモデルを使っているか

gptel はモデルを実行するプログラムではなく、Emacs から接続先へ HTTP 要求を送り、返答をバッファへ戻すクライアントです[1]。Ollama は標準設定では http://localhost:11434/api で API を提供します[2]。

この二つを一体として確認すると、接続設定、Ollama の起動状態、モデルの読み込み、回答品質を混同します。Emacs と gptel、Ollama API、ローカルモデル、会話バッファを別の層として扱うと、最初に失敗した境界を修正対象として特定できます[3]。

対象とする環境

この記事は、次の状態を対象とします。

• Emacs に gptel を導入している
• Ollama を同じ端末、または Emacs から到達可能な別ホストで動かしている
• gptel から Ollama へ送信すると、接続エラー、モデルエラー、無応答のいずれかが発生する
• Ollama の導入とモデル選定は完了している

最初に、調査時点のバージョンを記録します。

$ emacs --version | head -n 1
$ ollama --version

gptel のバージョンは、M-x package-list-packages で gptel の行を確認します。Git リポジトリから導入している場合は、使用中のタグまたはコミットを記録します。

以降の例では Ollama を localhost:11434 で動かしています。Emacs がコンテナ、仮想マシン、SSH 接続先で動いている場合、localhost は Emacs プロセスが動作する環境を指します。

/api/version で Ollama API への接続を確認する

モデルを実行する前に、Ollama API 自体へ到達できるか確認します。GET /api/version は、Ollama のバージョンを JSON で返します[4]。

$ curl -sS -w '\nHTTP %{http_code}\n' \
    http://localhost:11434/api/version
{"version":"0.x.y"}
HTTP 200

HTTP 200 と version が返れば、少なくとも指定したホストとポートで Ollama API が応答しています。

結果ごとの確認対象は次のとおりです。

結果	確認対象
HTTP 200	モデル一覧の確認へ進む
Connection refused	Ollama の起動状態、ホスト名、ポート番号
Could not resolve host	ホスト名の誤り、名前解決
タイムアウト	コンテナや別ホストとの通信経路、ファイアウォール
HTTP 400 以上	応答本文の error と Ollama 側のログ

Ollama API は、失敗時に HTTP 状態コードと {"error":"..."} 形式の本文を返します[5]。/api/version へ接続できない段階では、gptel のモデル名や生成品質を調べても原因には届きません。

/api/tags で利用可能なモデル名を確認する

API が応答したら、Ollama が管理しているモデル一覧を取得します。GET /api/tags は、利用可能なモデル名と形式、パラメーター規模、量子化情報を返します[6]。

$ curl -sS http://localhost:11434/api/tags
{
  "models": [
    {
      "name": "mistral:latest",
      "model": "mistral:latest"
    }
  ]
}

gptel に設定する名前は、name または model に返された文字列と完全に一致させます。タグを省略した名前や、別の量子化モデルの名前を推測して指定しません。

たとえば、一覧に mistral:latest がある場合、後続の確認でも同じ名前を使います。

$ MODEL_NAME='mistral:latest'

一覧に目的のモデルがない場合は、gptel の設定変更へ進まず、Ollama 側でモデルを利用できる状態にします。

/api/chat へ直接要求してモデル実行を確認する

モデル名を確定したら、Emacs と gptel を介さずに Ollama へ直接要求します。POST /api/chat は、モデル名と会話履歴を受け取り、生成結果を返します[7]。

$ MODEL_NAME='mistral:latest'

$ curl -sS -w '\nHTTP %{http_code}\n' \
    http://localhost:11434/api/chat \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"$MODEL_NAME\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": \"Reply only: OK\"
        }
      ],
      \"stream\": false
    }"

切り分けでは stream を false にし、応答を一つの JSON として確認します。正常時には、少なくとも次の項目が返ります。

{
  "model": "mistral:latest",
  "message": {
    "role": "assistant",
    "content": "OK"
  },
  "done": true,
  "done_reason": "stop"
}

確認する項目は次のとおりです。

項目	正常時の判断
HTTP 状態コード	200
model	指定したモデル名と一致する
message.content	空ではない
done	true
done_reason	通常は stop
load_duration	初回読み込みに時間がかかった場合の判断材料
total_duration	要求全体の所要時間

この要求が失敗する場合、gptel より手前に原因があります。

結果	判断
モデルが存在しないというエラー	/api/tags のモデル名と要求内の model を再確認する
モデル読み込み中に失敗	モデル形式、メモリー容量、Ollama のログを確認する
HTTP 応答が返らない	Ollama プロセスまたは通信経路を確認する
生成は完了するが内容が不十分	接続障害ではなく、入力またはモデル能力の問題として扱う

/api/ps でモデルの読み込み状態を確認する

/api/chat を実行した直後に、現在読み込まれているモデルを確認します。GET /api/ps は、実行中のモデル、VRAM 上のサイズ、コンテキスト長、解放予定時刻を返します[8]。

$ curl -sS http://localhost:11434/api/ps

応答例は次のとおりです。

{
  "models": [
    {
      "name": "mistral:latest",
      "context_length": 4096,
      "expires_at": "<ISO 8601 timestamp>"
    }
  ]
}

/api/chat が成功し、/api/ps に対象モデルが表示される場合、Ollama とモデルは動作しています。この状態で gptel だけが失敗するなら、確認対象を Emacs 側へ移します。

size と size_vram の値は環境によって異なります。数値の大小だけで異常と判断せず、対象モデルが一覧に存在するか、要求の直後に読み込まれているかを確認します。

gptel-make-ollama の接続先とモデル名を合わせる

Ollama API への直接要求が成功した後で、gptel の設定を確認します。公式の設定例では、gptel-make-ollama にホスト、ストリームの有無、モデル一覧を指定します[1]。

(setq
 gptel-model 'mistral:latest
 gptel-backend
 (gptel-make-ollama "Ollama"
   :host "localhost:11434"
   :stream t
   :models '(mistral:latest)))

mistral:latest は例です。/api/tags に表示されたモデル名へ置き換えます。

ここでは、次の二点を取り違えないようにします。

• curl では http://localhost:11434/api/... を指定する
• gptel-make-ollama の :host には公式例どおり localhost:11434 を指定する

:host に /api や /api/chat まで含めると、gptel が組み立てる要求先と一致しません。

Emacs 上で現在値を確認するには、次の変数を表示します。

C-h v gptel-model RET
C-h v gptel-backend RET

gptel-model が /api/tags に存在し、gptel-backend が意図した Ollama バックエンドを指していることを確認します。

新しい gptel バッファで最小要求を送る

既存の会話履歴やバッファ固有の設定を除外するため、新しい会話バッファを作ります。

M-x gptel RET

次の一文だけを入力します。

Reply only: OK

送信します。

M-x gptel-send RET

専用の gptel バッファでは、C-c RET でも送信できます[1]。

結果によって確認対象を分けます。

結果	判断
新しいバッファでは成功する	既存バッファの会話履歴、モデル、バックエンド、局所変数を確認する
新しいバッファでも失敗する	gptel の接続先、モデル名、実際の要求内容を確認する
回答は返るが遅い	Ollama の load_duration、total_duration、端末資源を確認する
回答は返るが指示に従わない	通信ではなく、モデル能力または入力内容を確認する

*gptel-log* で応答内容を確認する

直接の /api/chat は成功するのに gptel から失敗する場合、gptel のログを有効にします。

(setq gptel-log-level 'debug)

設定後に要求を再送し、次のバッファを開きます。

C-x b *gptel-log* RET

gptel は gptel-log-level を info または debug にすると、完全な応答を *gptel-log* へ記録します[1]。

ログでは次の項目を確認します。

• 接続先のホストとポート
• 送信したモデル名
• HTTP 状態コード
• Ollama が返した error
• ストリーム受信中の失敗

HTTP 404 とモデル不存在のエラーがある場合はモデル名を直します。接続拒否なら :host を確認します。Ollama が HTTP 500 を返している場合は、gptel の表示処理ではなく Ollama 側の失敗として扱います。

dry run で gptel の要求を cURL と比較する

ログだけでは差が分からない場合、gptel が送信する要求を送信前に確認します。

(setq gptel-expert-commands t)

M-x gptel-menu を開き、dry run の項目を選択します。gptel は要求本文を専用バッファへ出力し、対応する cURL コマンドもコピーできます[1]。

取得した cURL コマンドをシェルで実行し、先に成功した /api/chat の要求と比較します。

比較対象	確認内容
ホスト	localhost:11434 か、実際に成功した別ホスト
API パス	Ollama のチャット要求先になっている
モデル名	/api/tags の値と完全一致している
JSON 本文	model と messages が含まれている
ストリーム	通常利用では有効、単純比較では無効化して差を確認できる

gptel が生成した cURL も失敗する場合は、接続設定または要求本文に差があります。cURL は成功するのに Emacs 内だけで失敗する場合は、gptel のバージョン、ストリーム処理、バッファ状態を確認します。

確認結果から修正対象を決める

各段階の結果は、次の表に集約できます。

/api/version	/api/tags	/api/chat	gptel	修正対象
失敗	未確認	未確認	失敗	Ollama の起動状態、ホスト、ポート、通信経路
成功	対象モデルなし	未実行	失敗	Ollama 側のモデル導入またはモデル名
成功	対象モデルあり	失敗	失敗	モデル読み込み、端末資源、Ollama のログ
成功	対象モデルあり	成功	失敗	gptel の :host、gptel-model、要求内容
成功	対象モデルあり	成功	新規バッファでは成功	既存バッファの履歴または局所設定
成功	対象モデルあり	成功	成功するが内容が不十分	入力範囲、指示、モデル能力
成功	対象モデルあり	成功	成功	接続経路に異常なし

gptel から Ollama が動かないときは、最初から Emacs の設定全体を書き換えないようにします。/api/version、/api/tags、/api/chat、gptel の順に確認し、最初に失敗した境界だけを修正します。

参考文献

1. gptel, gptel: A simple LLM client for Emacs. https://github.com/karthink/gptel
2. Ollama, Introduction. https://docs.ollama.com/api/introduction
3. id774, Emacs で AI を使う利点と欠点（2026-08-05）. https://blog.id774.net/entry/2026/08/05/5464/
4. Ollama, Get version. https://docs.ollama.com/api-reference/get-version
5. Ollama, Errors. https://docs.ollama.com/api/errors
6. Ollama, List models. https://docs.ollama.com/api/tags
7. Ollama, Generate a chat message. https://docs.ollama.com/api/chat
8. Ollama, List running models. https://docs.ollama.com/api/ps