Sakana Fugu の使い方｜Codex 連携と API 設定の手順

はじめに

Sakana Fugu は、複数のフロンティアモデルを束ねるオーケストレーションシステムですが、利用する側から見れば通常の LLM API とほぼ同じ手順で導入できます。OpenAI 互換のインターフェースを備えており、既存のクライアントやコーディングツールの接続先を切り替えるだけで試せる設計になっているためです。

一方で、実際に使い始めると、モデル ID とバージョンの対応、推論レベルの指定可否、プロバイダー除外をどこで設定するのかといった、公式ドキュメントを読み込まないと分かりにくい部分があります。この記事では、API キーの発行から Codex・Claude Code への導入、独自スクリプトからの呼び出しまでを、公式ドキュメントで確認した手順に沿って整理します。

結論を先に述べると、導入自体は API キーを発行してエンドポイントを https://api.sakana.ai/v1 に向けるだけで完了し、SDK の移行は不要です。Codex と Claude Code についてはワンラインインストールが用意されていますが、対応 OS は Ubuntu と macOS のため、Windows 環境では手動セットアップが必要になります。また、複数エージェントが動作する分だけ応答に時間がかかるため、クライアント側のタイムアウト設定が実質的な必須の調整項目になります。

なお、Sakana Fugu がどのような仕組みで動いているか、性能や料金の位置づけについては、関連記事『Sakana Fugu とは｜Opus 4.8 を超える国産 AI の実力を検証』で整理しています。本記事は導入手順に絞って解説します。

Sakana Fugu の API の基本

導入作業に入る前に、接続先と選べるモデルを把握しておくと、後の設定でつまずきにくくなります。

エンドポイントと 2 種類の API

すべての API エンドポイントは https://api.sakana.ai で提供されます。Chat Completions と Responses の 2 種類に対応しており、公式は Responses API のほうが最近のツールや連携先との互換性が広いと説明しています。

参考: Get Started（Sakana AI Console）
“The API supports both Chat Completions and Responses endpoints”
（この API は Chat Completions と Responses の両エンドポイントに対応している）
https://console.sakana.ai/get-started

使い分けの考え方はシンプルです。既存のコードが Chat Completions 前提で書かれている場合は、base_urlとモデル名の変更だけで移行できます。これから新規に組む場合や、エージェント系のツールと連携させる場合は Responses API を選んでおくと、後の互換性で困りにくくなります。

4 つのモデル ID と推論レベル

指定できるモデル ID と、それぞれが受け付ける推論レベル（reasoning.effort）は次のとおりです。

押さえておきたいのは、maxを指定できるのがfugu-ultra-v1.1だけである点です。 他のモデルでも max は互換性のために受理されますが、内部的には xhigh として扱われます。指定した推論レベルがそのまま適用されると考えていると、想定と挙動が食い違う可能性があります。なお、上記以外の値を指定した場合はエラーになります。

各モデルのコンテキストウィンドウはいずれも 100 万トークンで、入力はテキストと画像に対応しています。並列でのツール呼び出しにも対応しており、Web 検索などの組み込みツールを利用する構成も選択できます。

モデルの選択方針としては、日常的なコーディングやレビューは fugu、時間をかけてよい難易度の高いタスクは fugu-ultra-v1.1 を xhigh 以上で、という組み合わせが出発点になります。推論レベルを上げるほどトークン消費が増えるため、常用する設定は控えめにしておき、必要な場面だけ引き上げる運用が費用面では無難です。

API キーの作成とエージェント除外の設定

導入の最初のステップは API キーの発行です。この段階で、後から変更しにくい設定を 1 つ決める必要があるため、順に確認します。

API キーの発行と疎通確認

API キーは Sakana AI コンソールのキー管理画面（https://console.sakana.ai/api-keys）から作成します。生成されたキーは 1 度しか表示されないため、ダイアログを閉じる前に安全な場所へ保管しておくことをおすすめします。 再表示はできず、紛失した場合は新しいキーを発行し直すことになります。

発行後、キーが有効かどうかは次のコマンドで確認できます。

export SAKANA_API_KEY={your api key}

curl -X POST https://api.sakana.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKANA_API_KEY" \
  -d '{"model":"fugu","messages":[{"role":"user","content":"How many r in word strawberry"}]}'

応答が返ってくれば、API 側の準備は完了です。キーをシェルの履歴に残したくない場合は、環境変数を設定ファイル側に置くか、シークレット管理の仕組みを利用する方法が現実的です。当然ながら、キーをリポジトリにコミットしない運用は前提になります。

プロバイダー除外はキー単位で設定する

エージェントプールから特定のプロバイダーを除外したい場合、設定はキーの作成時または編集時に行います。ダイアログで「Fugu custom model pool」を有効にし、利用を許可したいプロバイダーだけを残す形です。設定をオフのままにすると、既定の全プールが使われます。

注意したいのは、この除外設定がアカウント全体ではなく API キー単位で適用される点です。 用途ごとにキーを分ける運用と相性がよく、たとえば「社外秘データを扱うワークフロー用に、特定プロバイダーを除外したキー」と「制限のない検証用キー」を使い分ける構成が組めます。逆に、既存のキーをそのまま使い回していると、意図した制限がかかっていない可能性があるため、業務利用の前に設定状態の確認をおすすめします。

なお、除外設定が適用されるのは fugu のルーティングです。fugu-ultra は全プールを使用する設計のため、この設定の対象外です。

Codex と Claude Code への導入手順

Sakana Fugu は、プロバイダー設定を追加することで Codex CLI と Claude Code から利用できます。導入方法はワンラインインストールと手動セットアップの 2 通りです。

ワンラインインストールで導入する

対応環境であれば、次のコマンドで導入できます。

curl -fsSL https://sakana.ai/fugu/install | bash

インストール後は、Codex を使う場合は codex-fugu、Claude Code を使う場合は claude-fugu で起動します。

参考: SakanaAI/fugu（GitHub 公式リポジトリ）
“The one-line install supports Ubuntu and macOS.”
（ワンラインインストールは Ubuntu と macOS に対応している）
https://github.com/SakanaAI/fugu

Windows 環境は対象外である点に注意が必要です。 WSL 上の Ubuntu であれば動作しますが、Windows ネイティブの環境や、インストールが途中で失敗する場合は、後述の手動セットアップに切り替えることになります。

このスクリプトは、リポジトリを ~/.fugu にクローンし、~/.fugu/scripts/install.sh を実行して Codex のバージョン固定、設定の配置、API キーの保存を行います。パイプで受け取ったスクリプトをそのまま実行する形式に抵抗がある場合は、公式が同等の手順を提示しているので、内容を確認してから実行できます。

( git clone https://github.com/SakanaAI/fugu.git ~/.fugu && bash ~/.fugu/scripts/install.sh )

インストーラーには、非対話実行や事前確認に使えるフラグが用意されています。実務でよく使うものを挙げます。

CI 環境などで非対話に導入する場合は、次の形になります。

SAKANA_API_KEY=your_key bash ~/.fugu/scripts/install.sh --yes

起動用の codex-fugu は、実体としては codex -p fugu を実行するラッパーです。1 日 1 回程度、設定の更新有無を確認して適用を提案しますが、起動を妨げることはありません。更新確認を止めたい場合は --no-update を付けるか、CODEX_FUGU_NO_UPDATE=1 を設定します。導入状態を確認したいときは codex-fugu --status が使えます。

ランチャー独自のフラグは先頭に置いた場合のみ解釈され、それ以降の引数は Codex にそのまま渡されます。したがって、次のような使い方ができます。

codex-fugu resume                  # codex -p fugu resume として実行される
codex-fugu "fix the failing test"  # プロンプトを渡して新規セッションを開始
codex-fugu --no-update resume      # 更新確認を省略してから再開

Codex を手動でセットアップする（Windows 環境向け）

インストーラーが使えない環境や、配置される内容を自分で把握しておきたい場合は、同じ構成を手動で作成できます。手順は次の 4 ステップです。

model = "fugu"
model_reasoning_effort = "high"
model_provider = "sakana"
model_catalog_json = "~/.codex/fugu.json"

[features]
image_generation = false apps = false

[model_providers.sakana]
name = "Sakana API"
base_url = "https://api.sakana.ai/v1"
env_key = "SAKANA_API_KEY"
wire_api = "responses"

stream_idle_timeout_ms = 7200000
stream_max_retries = 5
request_max_retries = 4

SAKANA_API_KEY={your api key} codex -p fugu

Claude Code から利用する

Claude Code の場合、専用のランチャーを使わずに環境変数だけで接続先を切り替えられます。設定するのは ANTHROPIC_* 系の変数です。

export ANTHROPIC_BASE_URL="https://api.sakana.ai"
export ANTHROPIC_AUTH_TOKEN="fish_..."                  # Sakana の API キー
export ANTHROPIC_DEFAULT_OPUS_MODEL="fugu-ultra[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="fugu[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="fugu[1m]"
export ANTHROPIC_DEFAULT_FABLE_MODEL="fugu-cyber[1m]"   # 任意（アクセス制限あり）
export CLAUDE_CODE_SUBAGENT_MODEL="fugu[1m]"

claude

間違えやすいのは、ANTHROPIC_API_KEYではなくANTHROPIC_AUTH_TOKENを使う点です。 前者を設定しても認証が通らないため、切り替えがうまくいかない場合はここを確認することをおすすめします。なお、この設定は実行中のシェルセッション内でのみ有効です。

モデルの対応関係は、Opus ティアが fugu-ultra[1m]、Sonnet と Haiku が fugu[1m]、Fable ティアが fugu-cyber[1m] となり、サブエージェントは fugu[1m] を使用します。ここで登場する Fable ティアは Anthropic の Mythos クラスに属するモデルで、その位置づけと提供状況については関連記事『Claude Fable 5 はなぜ使えない｜米政府ディレクティブの経緯と復旧の行方』で整理しています。

Claude Code はクローズドソースであるため、公式ドキュメントでも表示上の差異が生じることが明記されています。いずれも動作そのものには影響しない範囲とされていますが、把握しておくと混乱を避けられます。

• 推論の強度スライダー: Claude Code 側は 6 段階を表示しますが、Sakana Fugu 側の実体は high と xhigh の 2 段階です。同じグループ内の目盛りは同じ挙動になります
• モデルピッカー: Sonnet と Haiku がどちらも fugu[1m] に解決されるため、同じ内容の行が 2 つ表示されます
• セッションヘッダー: 課金やティアの表示は API トークンの利用実績を反映したものになります

また、claude-fugu ランチャーは自動更新を行いません。新しい Fugu モデルへの対応など、最新の状態を反映するには公式の Get Started ページを確認して手動で更新する必要があります。

独自ワークフローからの利用（OpenAI SDK）

コーディングツール経由ではなく、自作のスクリプトや自動化基盤から呼び出す場合も、標準の OpenAI SDK をそのまま利用できます。

Python からの基本的な呼び出し

公式が提示している Responses API のサンプルは次のとおりです。変更が必要なのは base_url と model だけで、SDK 自体の入れ替えは不要です。

from openai import OpenAI

api_key = "YOUR_API_KEY"

client = OpenAI(
    base_url="https://api.sakana.ai/v1",
    api_key=api_key
)

response = client.responses.create(
    model="fugu-ultra",
    input="Write a concise explanation of how TLS works",
    timeout=120.0,
)

print(response.output_text)

この例で見落とされやすいのが、末尾のtimeout=120.0です。 公式も、fugu-ultra や fugu-cyber を使う複雑なタスクではクライアント側のタイムアウトを延ばす必要があると注記しています。複数エージェントが順に動作する構造上、単体モデルへの直接呼び出しと同じ感覚で既定値のまま実行すると、処理の完了前にクライアント側が切断してしまう可能性があります。

推論レベルを指定する場合は、reasoning.effort パラメーターを使用します。前述のとおり、max を実際に適用できるのは fugu-ultra-v1.1 のみで、他のモデルでは xhigh として扱われます。指定できない値を渡した場合はエラーになるため、モデルとレベルの組み合わせは事前に確認しておくと安全です。

推論レベルを上げるほどトークン消費が増える点は、他社モデルと同様です。定常処理は既定寄りの設定で回し、難易度の高いタスクだけ引き上げるという考え方については、関連記事『GPT-5.6 リリース｜Sol・Terra・Luna の違いとインフラ業務での使い分け』でも整理しているので参考にしてください。

既存コードからの移行と組み込みツール

すでに Chat Completions 形式で書かれた資産がある場合は、エンドポイントとモデル名の変更だけで移行できます。新規に組む場合や、エージェント系のツールと組み合わせる場合は Responses API を選んでおくと、対応範囲の広さで有利です。

Web 検索などの組み込みツールを利用する構成にも対応しています。ツール呼び出しの並列実行にも対応しているため、複数の情報源を参照させるワークフローも構築できます。詳細なパラメーターはコンソールのモデルドキュメントに記載されています。

運用上の注意点とつまずきやすい箇所

導入後に問題となりやすい点を、公式ドキュメントの記載をもとに整理します。

既存の Codex 設定は自動でバックアップされる

インストーラーは、Codex のバージョンを切り替える前や config.toml を初めて編集する前に、既存の設定を ~/.codex-backups/codex-config-<タイムスタンプ>/ へ保存します。

参考: Command reference（SakanaAI/fugu）
“so a backup survives even a full rm -rf ~/.codex”
（そのため、~/.codex を完全に削除してもバックアップは残る）
https://github.com/SakanaAI/fugu/blob/main/docs/commands_details.md

保存対象には config.toml、auth.json、各種 JSON・Markdown ファイル、セッションインデックスの .sqlite ファイルに加えて、検証用の MANIFEST.txt と SHA256SUMS が含まれます。保持されるのは最新 10 件で、件数と保存先は CODEX_BACKUP_KEEP と CODEX_BACKUP_ROOT で変更できます。バックアップ自体を行わない場合は --no-backup を指定します。

復元する場合は、バックアップを設定ディレクトリへ戻したうえで、設定ファイルが正しく解釈されるかを確認します。

rsync -a --exclude MANIFEST.txt --exclude SHA256SUMS ~/.codex-backups/codex-config-<timestamp>/ ~/.codex/
codex doctor   # config.toml parse: ok と表示されれば正常

なお、Sakana Fugu が追加するプロバイダー設定は config.toml 内の管理用マーカーで囲まれており、再配置時に置き換わるのはそのブロックだけです。編集後にはインストーラーが codex doctor で再解析し、解釈できない状態になった場合は自動的に変更を巻き戻す仕組みになっています。保存される auth.json のパーミッションは 0600 に設定されます。

バージョン切り替えでセッション一覧が変わる

Sakana Fugu の設定は特定の Codex バージョンで検証されているため、導入済みバージョンが一致しない場合、インストーラーやランチャーが切り替えを提案します。切り替えは同意した場合、または --force を指定した場合にのみ実行されます。

ここで戸惑いやすいのが、切り替え後にcodex resumeで表示される過去セッションの一覧が変わる点です。 Codex はバージョンごとにセッションインデックスを保持しているためで、~/.codex/sessions 配下の記録そのものが削除されるわけではありません。以前の一覧を戻したい場合は、元のバージョンで実行するか、バックアップからインデックスを復元します。

cp -p ~/.codex-backups/codex-config-<timestamp>/*.sqlite* ~/.codex/

つまずきやすい箇所のまとめ

導入時に確認したいポイントを整理します。

不具合や不明点については、公式のサポート窓口（https://fugu.sakana.ai）が案内されています。

まとめ

Sakana Fugu の導入は、OpenAI 互換 API としてエンドポイントを切り替えるだけで完了し、既存の SDK やコード資産をそのまま活かせます。一方で、複数エージェントが動作する構造に由来して、タイムアウトやストリーム維持の設定が実質的な調整項目になる点が、単体モデルの API との違いです。Codex と Claude Code への導入経路も用意されているため、まずは手元のワークフローで並走比較するところから始めるのが現実的です。

• 接続先は https://api.sakana.ai、Chat Completions と Responses に対応
• max を指定できるのは fugu-ultra-v1.1 のみで、他は xhigh にマップ
• プロバイダー除外は API キー単位の設定で、対象は fugu のルーティング
• ワンラインインストールの対応 OS は Ubuntu と macOS の 2 つ
• Windows 環境では設定ファイル 3 つを配置する手動セットアップ
• Claude Code は ANTHROPIC_AUTH_TOKEN を使う点が間違えやすい箇所
• 長時間タスクではクライアント側のタイムアウト延長が前提になる

以上、最後までお読みいただきありがとうございました。