Unsloth Desktop からエージェントに繋ぐ

URL: https://unsloth.ai/docs/jp/desktop 

こちらからダウンロード出来ます。

Hugging Face トークンを入れないとggufはダウンロードは出来ない。→トークン作成

設定から Access Tokens

・Token name:  unsloth-desktop-20260812

チェックするのは2つ
・Read contents of your repos
・Read contents of public gated repos you can access

パーミッションは設定できるもの

Unsloth Desktop
モデルハブでggufをダウンロードするにはhuggingface トークンが必要

入力して保存したらUnsloth Desktopは再起動

スクショを撮る前に ─ `--no-launch` の出力にはAPIキーが入る

`--no-launch` は、エージェントを起動せず生成された環境とコマンドを印字するオプション。中身を読むには一番早く、公式はそこに釘を刺している。

「The output can contain connection credentials, so do not publish it in logs or screenshots.」キーは `sk-unsloth-` で始まり、ローカルサーバー相手なら `unsloth start` が自動で発行または再利用するので、作った覚えがなくても載る。

`unsloth start` はエージェントの設定ファイルを触らない

公式の説明は「It does not add an Unsloth provider to the agent's normal configuration files.」。`~/.claude` や Codex の設定に書き足さず、セッション限りのプロバイダ設定で済ませる。合わなければ叩くのをやめれば戻る。

コマンドは3つに分かれる。`unsloth studio` がアプリ(UI+サーバー)を立てる。`unsloth run` はその別名で、モデルを指定してサーバーを起こしURLとAPIキーを印字するヘッドレス向け。`unsloth start <agent>` は、どちらかが動いている前提でエージェント側を組み立てるラッパ。

ドロップダウン3つが決めているもの

量子化が `Q4_K_M` だった理由ははっきりした。ヘルプに「Defaults to `UD-Q4_K_XL` for `unsloth/*` GGUF repos, else `Q4_K_M`.」とある。選んだモデルが公式GGUFリポジトリではなかった、それだけ。サーバー側の推奨順も `UD-Q4_K_XL, UD-Q4_K_L, UD-Q5_K_XL` と並んでから `Q4_K_M` に降りる。

UD は Unsloth Dynamic。2.0 は「every possible layer」の量子化タイプを動的に決め、レイヤごとにもモデルごとにも組み合わせが変わる。評価は KL Divergence で、Gemma 3 27B の Q4_K_XL なら 0.024916 が 0.023701 に下がる。容量を少し積んで誤差を削る形だ。「VRAM ○GB ならこの量子化」という汎用の対応表は公式に無い。

モデルは何から始めるか

公式チュートリアルが挙げるのは Gemma 4 と Qwen3.5 で、「works on 24GB RAM/unified mem device」の注記つき。ガイド本文は `unsloth/gemma-4-26B-A4B-it-GGUF` に `UD-Q4_K_XL` を合わせ、「best size/accuracy balance」と書いている。

Qwen3.5 の推論メモリ(RAM+VRAM合計)は 9B が4bitで 6.5GB、27B が 17GB、35B-A3B が 22GB。

Codex だけ条件が厳しく、GGUF を llama-server で配信していないと通らない。理由は文書に無く、実装のコメントに一行あった。「Codex always streams, and Unsloth only streams /v1/responses from llama-server.」ストリーミング専用の Codex に対し、`/v1/responses` をストリームで返せるのが llama-server だけ、という噛み合わせ。他のエージェントは transformers でもいい。

ダウンロードが出来たら起動してみる。

ダウンロード出来たら Runを押す。

停止の場合
Ejectを押す。

右上にもEjectがあるのでここでも良い。

新規チャットで開始

あとはchatGPT, Claude, Geminiなどと同じように利用できます。

起動方法はコマンドなどでもできます。
こちらは設定→エージェントに行くと起動方法が記載されています。

動作確認は6段で降りる

いきなり本命を叩かない。転んだときに原因が1つに絞れる形で降りる。

1段目: 何も起動せずに中身を見る

unsloth start claude --no-launch

環境変数と実際に叩かれるコマンドが出るだけ。サーバーの自動起動も走らない。`ANTHROPIC_BASE_URL` の指す先とモデルIDを目で見る。キーが載るので、この段は撮らない。

2段目: 素の `unsloth start` を通す

先に `unsloth studio` を立ててモデルをロードし、オプション無しで叩く。

unsloth start claude

素のこの形は `http://127.0.0.1:8888` だけを探す。実装のコメントいわく「`localhost` can resolve to `::1` (and `::1` is never probed)」。ポートを変えた人は `UNSLOTH_STUDIO_URL` を明示する。

3段目: `--model` を付ける

サーバーが無い状態で `--model` を渡すと、ループバック接続に限って内部で起こす。裏で走るのは実質これ。

unsloth run -H <host> -p <port> --disable-tools --no-cloudflare --model <model>

`--disable-tools` が最初から入っているのが要点。サーバー側ツールを止め、エージェント自身のツール呼び出しを通すため。

4段目: エージェント側で `/model` を見る

繋がったつもりで本家のモデルを叩いていた、が一番痛い。公式の Common issues にも「Claude Code shows the default Anthropic model, not my local one」がある。3つの環境変数が `claude` と同じシェルで export されているかを見る。

(スクショ6: `unsloth start claude` から立ち上がった Claude Code で `/model` を叩いた画面。ローカルモデルのIDが選択中として出ているところ。ここで初めて「繋がった」と言える区切りを見せたい)

5段目: サブエージェントを試す

unsloth start claude --as-subagent

`Unsloth is available as a local agent. Ask Claude to spawn an Unsloth or local agent.` と出る。この文言どおりに頼まないと呼ばれない。

6段目: Codex に広げる

GGUF必須に加えて `--persist` が要る。ここまで通っていれば、転んでも原因は Codex 固有に絞れる。

`--as-subagent` は親をローカルに向けない

通常の起動は親ごとローカルに向ける。`--as-subagent` は逆で、ヘルプの言い方だと「Keep the coding agent's current model and add Unsloth as a local subagent.」。親はクラウドのまま、重い作業だけ下に投げる。

実体はサブエージェント定義ファイルではなく MCP + プラグインだった。`unsloth-local-agent` というプラグインを書き出して stdio の MCPサーバーを繋ぐだけで、`ANTHROPIC_BASE_URL` は書き換わらない。呼ばれると子プロセスとして別の `claude` が `--model <ローカルモデルID>` 付きで走る。タイムアウトは1800秒。

トリガー条件が「Use when the user asks to spawn an Unsloth or local agent.」なので、頼むときに「Unslothエージェント」か「ローカルエージェント」の語を入れる。日本語UIの既定プロンプトも「ローカルエージェントを起動して、この関数を実装してください。」。

OpenCode だけ作りが違い、ネイティブのサブエージェント機構を使う。起動メッセージが `Unsloth is available as @unsloth and in /models.` なので、呼び出しは `@unsloth <指示>`。

効いてくるオプション

(スクショ2: 主なオプション一覧。--model から --yolo までの表)

`--persist` は Codex / OpenClaw / Hermes / Pi で毎回要る。この4つはホームごと使い捨ての一時ディレクトリに移され、終了時に消えるからだ。公式も「use `--persist` on the first and later launches」と書く。Claude Code と OpenCode は自分のストアに持つので不要。

`--serve` は既定ON。自動起動が発動するのは、`--serve` と `--launch` と `--model` が揃い、接続先が `http://` のループバックのとき。コンテキスト長は `--context-length`。`--yolo` は承認バイパスに直結し、claude なら `--dangerously-skip-permissions` に化ける。

ヘルプにしか無い一群もある。`--disable-tools` / `--enable-tools`(既定off)、`--reasoning`(on/off/auto、既定off、理由は「tool calls stay in the structured tool channel」)、`--temperature` などのサンプリング指定。ただし走っているサーバーにアタッチした場合、サンプリングと `--reasoning` は効かず、`unsloth studio stop` して入れ直せと警告が出る。

(スクショ3: リモートStudio接続、引数の受け渡し、起動せずに内容を確認する の3節)

先に知っておく落とし穴

いちばん大きいのが attribution header。公式に「Fixing 90% slower inference in Claude Code」という見出しがあって、システムプロンプト先頭に付く属性ヘッダが毎回変わるためプレフィックスがKVキャッシュを外し続け、推論が90%遅くなる。

手で `ANTHROPIC_BASE_URL` を張るなら、自分で `CLAUDE_CODE_ATTRIBUTION_HEADER` を `0` にする必要がある。`unsloth start claude` なら実装が自動で入れる。ただし Claude Code が 2.1.98 未満だと未知のフラグを拒否するので、`--exclude-dynamic-system-prompt-sections` のような最適化は付かない。最新に保つ理由がここ。

`ANTHROPIC_BASE_URL` に `/v1` を付けない、Codex の `base_url` には付ける。この非対称は間違えやすい。

手で `unsloth run` するなら `--disable-tools` を忘れない。付けないと Studio 側のサーバーツールがツール呼び出しを飲み込み、公式の表現だと「Claude Code answers but never edits files」。答えは返るのにファイルが変わらない、という気づきにくい壊れ方をする。

おまけ

Unsloth Desktop からCodeRouterに接続するにはカスタムで以下の設定。
設定後、チャットから利用できるようになります。

CodeRouterのLauncherで該当のggufを起動してから

Models → Reloard models で呼び出しをします。
正しく呼び出せればエラーは出ません。

通ったら、次は学習に戻る

エージェント接続は足場だと思っている。ローカルモデルにコードを書かせれば、遅い・雑・ツールを呼ばないが見えてくる。その差分が、学習で埋める対象になる。

まず `unsloth/gemma-4-26B-A4B-it-GGUF` の `UD-Q4_K_XL` を素のまま使い倒し、どこで力尽きるかを記録する。学習編はそこから。

聞きたいのは、ローカルモデルをコーディングエージェントに繋いだ人がどのくらいのサイズで実用にしているか。24GB で 27B クラスが現実的なのか、35B-A3B のような MoE のほうが体感がいいのか。「親はクラウド、重いところだけローカル」で回している人がいたら、その線引きもいちばん聞きたいです。コメントで教えてください。

#Unsloth #UnslothDesktop #ClaudeCode #Codex #ローカルLLM #LLM #GGUF #llamacpp #コーディングエージェント #MCP #量子化