0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Claude CodeをOllama v0.14に直結する、--bareが鍵だった

0
Posted at

はじめに

Ollama v0.14以降でAnthropic Messages API互換エンドポイントが追加され、Claude Codeをローカルモデルに直結できるようになりました。この記事では、Ollamaのインストールから実際にClaude Codeでローカルモデルに応答させるところまでを、クラウド環境上で一通り実機検証した記録をまとめます。

この記事で学べること

  • OllamaのAnthropic互換エンドポイント（/v1/messages）の疎通確認方法
  • Claude Codeをローカルモデルへ向ける環境変数の設定
  • 素の状態では動かず、--bare オプションが必要だった理由

対象読者

Claude Codeを使っていて、API課金なしでローカルモデルとの組み合わせを試したい開発者を対象読者とします。

前提環境

  • OS: Ubuntu 24.04（クラウド実行環境・CPUのみ、GPUなし）
  • Ollama: v0.32.5（インストール時点の最新版。Anthropic互換機能はv0.14で追加）
  • Claude Code: v2.1.220

TL;DR

  • OllamaはHTTPサーバーとして /v1/messages エンドポイントを公開し、リクエスト・レスポンスともにAnthropicのMessages API形式に変換する
  • ANTHROPIC_BASE_URL と ANTHROPIC_API_KEY を差し替えるだけでClaude Codeをローカルモデルに向けられる
  • ただし通常起動だとCLAUDE.mdやツール定義を含む巨大なシステムプロンプトがローカルモデルのコンテキスト長を超え、2ターン目で500エラーになった。--bare オプションでシステムプロンプトを最小化すると安定した

背景・課題

Claude CodeはこれまでAnthropic公式のAPIかBedrock/Vertex経由での利用が基本で、ローカルLLMと組み合わせるにはLiteLLMのようなプロキシ層でAPI形式を変換する必要がありました。Ollama v0.14でAnthropic Messages API互換の /v1/messages エンドポイントが追加されたことで、この変換層を挟まずにClaude Codeから直接ローカルモデルを叩けるはずです1。実際にどこまで素直に動くのか、クラウド環境で検証しました。

やったこと

ステップ1: Ollamaのインストールと起動

クラウド環境にOllamaをインストールします。公式インストールスクリプトはzstdコマンドに依存しており、未インストールだと以下のエラーで止まります。

$ curl -fsSL https://ollama.com/install.sh -o /tmp/ollama-install.sh
$ sh /tmp/ollama-install.sh
ERROR: This version requires zstd for extraction. Please install zstd and try again:
  - Debian/Ubuntu: sudo apt-get install zstd

apt-get install -y zstd で依存を解消してから再実行すると、GPUなし環境でも問題なくインストールが完了しました。

$ apt-get install -y zstd
$ sh /tmp/ollama-install.sh
>>> The Ollama API is now available at 127.0.0.1:11434.
>>> Install complete. Run "ollama" from the command line.

サーバーを起動し、バージョンを確認します。

$ ollama serve &
$ curl -s http://127.0.0.1:11434/api/version
{"version":"0.32.5"}

ステップ2: Anthropic互換エンドポイントの疎通確認

モデルを何も落としていない状態で /v1/messages に直接POSTすると、404ではなく not_found_error というAnthropic形式のエラーJSONが返ってきました。これはエンドポイント自体はAnthropicのリクエスト形式を正しく認識しており、単にモデルが未取得なだけであることを示しています。

$ curl -s -X POST http://127.0.0.1:11434/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: ollama" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"qwen3:0.6b","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
{"type":"error","error":{"type":"not_found_error","message":"model 'qwen3:0.6b' not found"},"request_id":"req_38201b9adbd528a2b5af3c67"}

軽量モデル qwen3:0.6b（523MB）を取得してから同じリクエストを送ると、Anthropic Messages APIそのものの応答形式（id・type: "message"・content・usage.input_tokens/output_tokens）でレスポンスが返ってきました。

$ ollama pull qwen3:0.6b
$ curl -s -X POST http://127.0.0.1:11434/v1/messages \
  -H "Content-Type: application/json" -H "x-api-key: ollama" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"qwen3:0.6b","max_tokens":50,"messages":[{"role":"user","content":"1+1は何ですか？数字だけ答えて"}]}'
{"id":"msg_a6f0fa7121f3e4da4208d4e5","type":"message","role":"assistant",
 "model":"qwen3:0.6b","content":[{"type":"thinking","thinking":"..."}],
 "stop_reason":"max_tokens","usage":{"input_tokens":20,"output_tokens":50}}

content が thinking ブロックで埋まって max_tokens に達しているのは、qwen3 系がデフォルトで思考過程を出力するモデルであるためです。max_tokens を増やすか、思考をオフにするプロンプト設計が必要になる点は実運用上の注意点として控えておきます。

ステップ3: Claude Codeから接続する

いよいよClaude Code本体から接続します。Ollama公式ブログの手順どおり ANTHROPIC_BASE_URL と認証用のトークンを設定し、--model でローカルモデル名を指定します1。

最初に ANTHROPIC_AUTH_TOKEN を使う通常起動で試したところ、60秒のタイムアウトでプロセスが終了してしまいました。Ollama側のログを見ると、CLAUDE.mdやツール定義を含むシステムプロンプトが26,684トークンにも達し、モデルのコンテキスト長（既定4,096トークン）に収まらず2,050トークンへ切り詰められ、その状態で送った2回目のリクエストが500エラーになっていました。

time=... level=WARN msg="truncating input prompt" limit=2050 prompt=26684 keep=4 new=2050
[GIN] ... | 500 | 2.569362236s | POST "/v1/messages?beta=true"

そこで --bare オプション（フック・CLAUDE.md自動読み込み・プラグイン同期などを一括スキップする最小モード）に切り替え、認証も ANTHROPIC_API_KEY に変更したところ、正しく応答が返ってきました。

$ ANTHROPIC_BASE_URL="http://127.0.0.1:11434" \
  ANTHROPIC_API_KEY="ollama" \
  claude --bare -p "1+1は？数字だけ答えて" --model qwen3:0.6b
2

ハマりポイント

ポイント1: 通常モードはシステムプロンプトが大きすぎる

Claude Codeの通常起動はCLAUDE.md・ツール定義・フック情報を含む数万トークン規模のシステムプロンプトを毎回送信します。Ollamaのデフォルトコンテキスト長（4,096トークン）はこれを大きく下回るため、切り詰め後の状態でマルチターンのやり取りに入ると500エラーで落ちました。ローカルモデルと組み合わせる場合は --bare でシステムプロンプトを最小化するか、OLLAMA_CONTEXT_LENGTH でコンテキスト長を拡張する必要があります。

ポイント2: ツール呼び出しを伴う応答は極端に遅い

CPUのみの環境（15.7GB RAM）で qwen3:0.6b を動かすと、テキスト生成速度は約11〜17トークン/秒でした。単純な一問一答（max_tokens: 50）は数秒で返りましたが、コード生成のようにモデルがツール呼び出しの判断を挟む可能性のあるプロンプトでは、1ターンだけで30〜60秒かかりました。Ollama公式ブログは「最低32Kトークンのコンテキスト長を推奨」としていますが1、コンテキストを広げるほど1トークンあたりの処理時間も伸びるため、CPUのみの環境で実用速度を出すには軽量モデル選びとプロンプトの最小化が前提になります。

著者視点の発見ポイント

公式ブログの手順は「環境変数を2つ設定して claude --model xxx を叩くだけ」とシンプルに書かれていますが、実際にはClaude Code側が生成する巨大なシステムプロンプトとローカルモデルの小さいコンテキスト長がぶつかる問題が最初の一手で発生しました。--bare オプションはもともとフック・CLAUDE.md読み込みをスキップするための機能ですが、ローカルモデル接続では「システムプロンプトを小さく保つための実質的な必須オプション」として機能する、という組み合わせは実際に動かしてみるまで気づきませんでした。

まとめ

  • Ollama v0.14以降は /v1/messages でAnthropic Messages API互換を提供しており、curlで直接叩いてもAnthropic形式のレスポンスが返ってくることを確認しました
  • Claude Codeは ANTHROPIC_BASE_URL/ANTHROPIC_API_KEY の差し替えだけでローカルモデルに向けられますが、通常起動のシステムプロンプトはローカルモデルの既定コンテキスト長を簡単に超えるため --bare が実質必須でした
  • CPUのみの環境では単純な応答は数秒で返る一方、ツール呼び出しを伴う可能性のあるプロンプトは1ターン30秒以上かかることがあり、体感速度は軽量モデルでも重めです

関連記事

参考リンク

  1. Claude Code with Anthropic API compatibility - Ollama Blog（2026年時点。最低32Kトークンのコンテキスト長を推奨する旨の記載あり） ↩ ↩2 ↩3

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?