UnslothでローカルLLMをClaude Codeと連携させる方法

この記事でわかること

ローカルLLMを開発支援ワークフローへ組み込むために、モデル準備からClaude Code連携までの流れをまとめた記事です。

ローカルLLMを開発支援へ使う構成
Unsloth/GGUFモデルを扱うときの注意点
推論速度低下を切り分ける視点

おすすめ読者: Claude Codeのような開発支援をローカルLLMでも試したい人、Unslothモデルを実用ワークフローへつなげたい人。

読む前の注意: コマンド、ライブラリ、モデルの仕様は環境やバージョンで変わります。実行前に手元の環境と公式情報を確認してください。

情報確認日: 2026年8月12日（各公式ページの現行内容を確認）
固定した版: Claude Code v2.1.228、llama.cpp 9558fa44、Qwen3.5-35B-A3B 59d61f3c、Unsloth GGUF bc014a17
検証区分: Anthropic、llama.cpp、Qwen、Unslothの公式資料による机上調査です。コマンドは構成例で、この環境ではモデルのダウンロード・推論・Claude Code接続を実行していません。
未検証範囲: GGUFの個別hash、GPU/CPU別の速度と必要メモリ、tool call互換性、長時間稼働、Claude Code全機能との互換性。

UnslothのGGUFをClaude Codeへつなぐ構成

Claude Codeは、接続先をANTHROPIC_BASE_URLで変更できます。ただし、接続先が単なるOpenAI互換serverであるだけでは不十分です。Anthropic公式のgateway要件では、少なくともPOST /v1/messagesとPOST /v1/messages/count_tokensを実装し、anthropic-versionなどのheaderを扱う必要があります。

監査時のllama.cpp llama-serverはAnthropic互換の両endpointを備えています。ただし公式READMEも完全互換を強く保証していません。Claude Codeの更新でrequest形式が変わる可能性があるため、次の順番でAPI単体から確認します。

Qwen/Unsloth GGUFをllama-serverで起動する
/v1/messagesと/v1/messages/count_tokensをcurlで確認する
Claude Codeを小さなテスト用repositoryへ接続する
承認あり・読み取り中心のtaskからtool callを確認する

1. llama.cppを用意する

以下はUbuntu系LinuxでCUDA buildを作る例です。Apple SiliconではCUDA指定を外し、llama.cpp公式build資料のMetal手順を使ってください。

sudo apt-get update
sudo apt-get install -y build-essential cmake curl git libcurl4-openssl-dev
git clone https://github.com/ggml-org/llama.cpp.git

cmake -S llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON

cmake --build llama.cpp/build \
  --config Release \
  -j \
  --target llama-server

記事の監査ではllama.cpp commit 9558fa44c92746a58dd07ad1bf0c889715b938a6を参照しました。日々更新されるため、再現性が必要なら自分が検証したcommitまたはrelease tagへcheckoutして記録します。

2. Unsloth GGUFを起動する

最初はcontextを32K程度に抑え、serverが正常に起動してから増やします。量子化ごとの必要メモリはmodel fileだけで決まらず、KV cache、batch、GPU offload、vision projectorも加わるため、「24GBなら必ず動く」とは断定できません。

./llama.cpp/build/bin/llama-server \
  --hf-repo unsloth/Qwen3.5-35B-A3B-GGUF:UD-Q4_K_XL \
  --alias unsloth/Qwen3.5-35B-A3B \
  --host 127.0.0.1 \
  --port 8001 \
  --ctx-size 32768 \
  --jinja

--jinjaはAnthropic互換endpointでtool useを試すために必要です。量子化タグや取得対象はUnsloth公式GGUF repositoryで確認してください。初回は重みを取得するため、空き容量と通信量にも余裕が必要です。

thinkingをserver全体で無効化して比較する場合は、利用中のQwen chat templateが対応することを確認したうえで次を追加します。

--chat-template-kwargs '{"enable_thinking":false}'

3. Claude Codeの前にAPIを確認する

curl http://127.0.0.1:8001/health

curl http://127.0.0.1:8001/v1/messages \
  -H 'content-type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'x-api-key: local-test-only' \
  -d '{
    "model": "unsloth/Qwen3.5-35B-A3B",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Reply with only: ready"}
    ]
  }'

curl http://127.0.0.1:8001/v1/messages/count_tokens \
  -H 'content-type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'x-api-key: local-test-only' \
  -d '{
    "model": "unsloth/Qwen3.5-35B-A3B",
    "messages": [
      {"role": "user", "content": "Count this request"}
    ]
  }'

ここで失敗する場合、Claude Code側の設定を増やす前にserver log、model alias、chat template、context、tool-use対応を確認します。127.0.0.1へbindしたローカルserverだけを想定した例です。LANやInternetへ公開する場合はdummy keyのまま使わず、認証・TLS・access controlを備えたgatewayを置いてください。

4. Claude Codeを接続する

Claude Codeは公式installerを使います。実行前に公式setup資料で現行手順を確認してください。

curl -fsSL https://claude.ai/install.sh | bash

export ANTHROPIC_BASE_URL="http://127.0.0.1:8001"
export ANTHROPIC_API_KEY="local-test-only"

claude --model unsloth/Qwen3.5-35B-A3B

Windows PowerShellでは同じ2変数を現在のsessionへ設定します。

irm https://claude.ai/install.ps1 | iex

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8001"
$env:ANTHROPIC_API_KEY = "local-test-only"

claude --model unsloth/Qwen3.5-35B-A3B

~/.claude.jsonのonboarding状態やprivateな内部キーを手編集する手順は使いません。認証やmodel選択に問題がある場合は、Claude Code公式gateway資料と利用versionの挙動を確認します。

Attributionとprompt cacheを切り分ける

Claude Codeはgateway向けの短いattribution blockをsystem promptへ付けます。Anthropic公式資料では、独自gatewayがrequest body全体をcache keyにする場合に限り、CLAUDE_CODE_ATTRIBUTION_HEADER=0で省けると説明しています。「必ず90%遅くなる」「shellの環境変数では効かない」という一般化はできません。

export CLAUDE_CODE_ATTRIBUTION_HEADER=0

設定前後でserver側のcache hit、prompt processing時間、TTFTを同じ会話で測って判断します。永続化する場合は、既存の~/.claude/settings.jsonを上書きせず、公式settings schemaに従ってenvへmergeします。

安全な動作確認

使い捨ての小さなrepositoryで開始する
最初は「ファイルを読んで要約」のようなread-only taskにする
command実行とfile変更の承認を有効にしたままにする
意図しないpath、secret、network accessがないか確認する
同じtaskを複数回試し、tool name・arguments・結果の扱いを記録する

--dangerously-skip-permissionsは承認を無効化するため、通常の接続確認では使用しません。モデルをローカル実行しても、agentが実行するshell commandやfile変更まで安全になるわけではありません。

トラブルシューティング

Connection refused: curl http://127.0.0.1:8001/healthとserver logを確認
model not found: --aliasとclaude --modelの文字列を一致させる
tool callが崩れる: --jinja、chat template、context truncationを確認
Claude公式serviceへ戻す: local sessionで設定したANTHROPIC_BASE_URLとtest keyをunsetして新しいshellを開く
遅い／OOM: context、batch、GPU offload、量子化を一つずつ変更し、server指標を記録

まとめ

Unsloth GGUFとClaude Codeの間には、Anthropic Messages互換gatewayが必要です。監査時のllama.cppは必要な2 endpointを備えていますが、互換性はbest effortです。まずcurlでMessages APIを確認し、Claude Codeは承認ありの小さなtaskから試してください。

公式資料

よくある質問

ローカルLLMでコーディング支援は実用的ですか？

用途を絞れば実用的です。小さな修正、説明、補助には使いやすい一方、大規模変更ではモデルサイズとコンテキスト管理が重要です。

速度が遅いときは何を確認しますか？

モデルサイズ、量子化、コンテキスト長、GPU利用、プロンプト量、サーバーとクライアント間の通信を順に確認してください。

クラウド型AIと併用できますか？

できます。機密性の高い検証やローカル実験は手元のLLM、難しい設計相談はクラウドAIなど、役割分担が現実的です。