ガイド一覧へ戻る
チュートリアル·2026年10月1日·最終更新 2026年10月3日·読了8分

gooseコードエージェントの使い方：インストール、モデルソース、API設定、料金

インストール、モデルソースの選択、セッション開始の3ステップで始められます。最も多くの人がつまずくHost URL /v1の落とし穴も解説します。

gooseはApache-2.0ライセンスのオープンソースAIコーディングエージェントで、ターミナルやデスクトップアプリからファイルの読み取り、編集、コマンド実行ができます。使い始める手順は、インストール、モデルソース（provider）の選択、タスクを与えるワークセッションの開始の3つだけです。goose自体は無料で、費用は接続したモデルから発生します。このチュートリアルでは、2026年10月1日時点の公式ドキュメントに基づき、インストール、3つの課金方法、OpenAI互換エンドポイントへの接続方法（特に間違いやすい/v1の落とし穴を含む）、一般的な操作を説明します。最新バージョンは2026年9月23日にリリースされたv1.52.0です。

まず名前を整理しましょう。このページで扱うのはgoose-docs.aiのコーディングエージェントで、リポジトリはaaif-goose/gooseです。もともとはblock/gooseという名前で、2026年4月にLinux FoundationのAgentic AI Foundationへ移管されました。これはgoose.aiではありません。goose.aiは別のホスト型推論サービスで、料金も関係ありません。gooseには現在繁体字中国語のインターフェースがないため、以下のメニュー名はすべて英語原文で記載します。

インストール

公式にはデスクトップ版（goose Desktop）とコマンドライン版（goose CLI）があり、両方で同じ設定を使用します。

安裝（擇一）
# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

Windowsでは公式サイトからデスクトップ版をダウンロードできます。CLIはGit Bashで同じ1行のインストールコマンドを実行することを推奨します（PowerShellでも可能です）。Homebrewのパッケージ名はまだblock-gooseです。これは名称変更がインストールパッケージに完全には反映されていないためで、プロジェクトがまだBlockの管理下にあることを意味しません。

初回起動：モデルソースを選択

初めてgoose Desktopを開くとウェルカム画面が表示されます。CLIでは自動的に設定モードになります（後から変更する場合はgoose configureを実行できます）。インストールページにある選択肢は3つです。

  • OpenRouter Login — OpenRouterアカウントでログインし、モデルを自動設定します。
  • Tetrate Agent Router Service Login — Tetrateでログインします。ドキュメントによると、goose経由で初めて自動認証すると$10の無料クレジットを受け取れ、新規ユーザーと既存ユーザーの両方が対象です。
  • Manual Configuration — providerを自分で選び、キーを入力します。KunavoなどのOpenAI互換エンドポイントに接続する場合はこれを選びます。

3つの課金方法：先に正しく選んでから設定する

方式支払い方法注意
APIキー（OpenAI、Anthropic、OpenRouter、互換エンドポイント）トークン単位で課金最も柔軟です。料金は利用量に応じて変わります。下に試算があります。
ACPプロバイダー（Claude ACP、Codex ACP、Amp ACP、Pi ACP）既存のClaude CodeまたはChatGPT Plus/Proなどのサブスクリプションを使用します。ドキュメントでは「トークン単位のAPI料金なし」と説明されています。Node.js、npm、各社のACPアダプターが必要です。goose session resumeとforkには現在対応していません。
ローカルモデル（Ollamaなど）従量料金なし十分な性能のハードウェアが必要で、モデルもツール呼び出しに対応していなければなりません。

ACP方式の説明はgooseのACP providersドキュメントに基づいています。そこでは、ACPのセッションIDはgooseのものと異なり、テレメトリ項目が一致しない可能性があるとも注意されています。すでにサブスクリプションがあり、API料金だけを節約したい人は、まずこの方式を確認してください。

OpenAI互換エンドポイントへの接続：Host URLに/v1を付けない

ここが最も多くの人がつまずく箇所です。gooseは完全なbase URLを受け取らず、「ホスト」と「パス」の2つに分けます。providersドキュメントによると、OPENAI_HOSTは「カスタムエンドポイントURL（デフォルトはapi.openai.com）」、OPENAI_BASE_PATHは「ホストの後ろに付加されるリクエストパス（デフォルトはv1/chat/completions）」です。プロキシに接続する場合、OPENAI_HOSTには「プロキシのルートアドレス（パスなし）」を設定します。Kunavoの場合：

OpenAIプロバイダーの設定方法
# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

goose Desktop では Settings → Models → Configure providers → OpenAI にあります。CLI では goose configure → Configure Providers → OpenAI です。Organization ID と Project は OpenAI の自社アカウント用なので、空欄のままで構いません。Host URL を https://api.kunavo.com/v1 と入力すると、リクエストは /v1/v1/chat/completions になります。ドキュメントにも「404 は通常、OPENAI_BASE_PATH がプロキシに適していないことを意味する」とあります。つまりパスの誤りであり、キーの誤りではありません。一方、401「No api key passed in」が表示される場合は、キーが読み込まれていません。たとえばキーを config.yaml に記述すると、goose はそれを無視します。

もう一つ、よりすっきりした方法は、一覧に独立した provider として追加することです。goose は custom_providers フォルダ内の JSON 定義ファイルを読み込みます。Kunavo は、リアルタイムの料金表から生成したファイルを提供しています。このファイルにはツール呼び出しに対応したモデルだけが含まれ、キーそのものではなくキーの環境変数名だけが記載されています。

別の方法：Kunavoのprovider設定
# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Windows のフォルダは %APPDATA%\Block\goose\config\custom_providers\ です。配置すると、goose Desktop の Configure providers に Kunavo が表示されます。キーは環境変数ではなく、システムのキーチェーンに保存できます。goose のソースコードによると、ID が gpt-5 または gpt-6 で始まるモデルは /v1/responses を使用し、それ以外は /v1/chat/completions を使用します。Kunavo はどちらにも対応しています。手動で作成することもできます。Configure providers → Add Custom Provider を選び、タイプに OpenAI Compatible、API URL に https://api.kunavo.com/v1 を指定してください。完全な英語設定ページは goose integration guide にあります。

正直な説明：上記の設定は goose のドキュメントとソースコードを整理したものです。Kunavo は自社エンドポイントを goose で実際に実行したことがなく、作業セッション、ストリーミング、ツールの往復も検証していません。現在動作している方法は残したまま、まずはファイルを読み書きする小さなタスクで試してください。

よく使う操作

  • 作業セッションを開始：goose session（-n 名稱 で名前を付けられます）。その後は goose session --resume -n 名稱 で再開し、goose session list で履歴を一覧表示します。
  • 認証モードを切り替える：作業セッション内で /mode と入力すると、auto、approve、chat、smart_approve を選択できます。すべての手順で確認を求める場合は、approve を使用してください。
  • モデルを選択：goose configure ではカスタムモデル名を入力できません。一覧にない ID は goose Desktop に入力するか、config.yaml で GOOSE_MODEL を設定してください。
  • プロジェクト説明ファイル：goose はデフォルトで .goosehints と AGENTS.md を読み込みます（CONTEXT_FILE_NAMES で制御）。プロジェクトのルールをそこに記述しておけば、別のエージェントに移行しても引き継げます。
  • ツール呼び出しに対応していないモデルは選ばないでください：ドキュメントによると、そのようなモデルは「チャット補完しかできず」、拡張機能も無効にする必要があります。

1 回の作業セッションにかかるおおよその料金

以下は説明用の token 算術であり、実際のタスク料金でも請求上限でもありません。1 回のエージェント作業セッションで、複数のラウンドにわたり合計 400,000 個のキャッシュされていない入力 tokenを送信し、25,000 個の出力 tokenを受け取ると仮定します（エージェントは各ラウンドでコンテキストを再送するため、入力が特に多くなります）。単価は、Kunavo の料金表に掲載されたリアルタイムの 100 万 token あたりの価格を使用しています。

モデル入力 / 出力（100 万 token あたり）1 回の作業セッションの見積もり
Claude Haiku 4.5$0.70 / $3.50$0.367
Claude Sonnet 5$1.40 / $7.00$0.735
GPT-5.6 Sol$2.00 / $12.00$1.100

キャッシュについて：goose のドキュメントによると、Anthropic、Amazon Bedrock、Databricks、OpenRouter、LiteLLM の各 provider 経由で Claude を使用すると、Anthropic の cache_control マーカーが自動的に付加されます。汎用 OpenAI provider 経由の Claude はこの一覧に含まれないため、goose はこれらのマーカーを付加しません。そのため上表ではキャッシュ割引がないものと仮定しています。これは保守的な見積もりです。Kunavo の料金表の金額は請求額の下限であり、上限ではありません。上流から費用が報告された場合、請求額は「料金表の金額」と「上流費用 × 適用される上乗せ額」の高い方になります。

台湾での支払い

Kunavoは前払い残高方式で、トークン単位で課金され、月額料金はありません。最低チャージ額は$10です。決済はStripeを経由し、台湾ではクレジットカード（Visa、Mastercard、American Express、JCB、銀聯）、Apple Pay、Google Pay、Linkを利用できます。街口とLINE Payは利用可能な決済方法に含まれません。詳しくは料金の説明をご覧ください。準備ができたらアカウントを作成してキーを発行できます。その他のエージェントとの比較は、英語のgoose alternativesとgoose vs Claude Codeをご覧ください。

よくある質問

gooseとgoose.aiは同じものですか？

いいえ。これはこのキーワードで最もよくある混同です。gooseはApache-2.0ライセンスのオープンソース・コーディングエージェントで、リポジトリはaaif-goose/goose、ドキュメントはgoose-docs.aiにあります。一方、goose.aiは別のホスト型NLP推論サービスで、サイトではCoreWeaveとAnlatanの合弁事業と説明されています。このコーディングエージェントとは無関係です。goose.ai名義の従量料金は、その推論サービスの料金です。

gooseは開発停止になりましたか？

いいえ。gooseはblock/gooseからaaif-goose/gooseへ移行し、Linux Foundation傘下のAgentic AI Foundationのプロジェクトになりました。2026年10月1日の確認時点で、GitHub APIはリポジトリがアーカイブされておらず、当日もプッシュがあり、最新バージョンv1.52.0は2026年9月23日にリリースされたことを示しています。Homebrewのパッケージ名（block-goose）、VS Code拡張機能ID、Windowsの設定フォルダーには今もBlockの名前が残っています。そのため検索結果では停止したように見えることがありますが、実際には停止していません。

gooseは有料ですか？

goose自体は無料です。料金が発生するのは呼び出すモデルです。一般的な方法は3つあります。APIキーを使い、トークン単位で課金する（OpenAI、Anthropic、OpenRouter、またはOpenAI互換エンドポイント）；ACP providerで既存のClaude CodeまたはChatGPT Plus/Proサブスクリプションに接続する（公式ドキュメントでは「トークン単位のAPI料金なし」と説明）；Ollamaなどのローカルモデルを使う（従量料金なし）。インストールページには、goose経由で初めてTetrateに自動ログインすると、$10の無料クレジットを受け取れるとも記載されています。

gooseのHost URLには/v1を付ける必要がありますか？

いいえ。付けると壊れます。gooseはエンドポイントを2つに分けます。OPENAI_HOSTはホスト（デフォルトはapi.openai.com）、OPENAI_BASE_PATHは後ろに付加されるリクエストパス（デフォルトはv1/chat/completions）です。したがってHost URLにはhttps://api.kunavo.comだけを入力し、/v1はデフォルトパスで補います。https://api.kunavo.com/v1と記述すると、実際のリクエストは/v1/v1/chat/completionsになり、認証エラーではなく404が返ります。

なぜgoose configureで目的のモデルが見つからないのですか？

gooseのドキュメントには、goose configureはカスタムモデル名の入力に対応していないと明記されています。リストにないモデルIDは、goose Desktopに直接入力するか、config.yamlでGOOSE_MODELを設定してください。また、gooseはほぼすべての手順でツール呼び出し（tool calling）を使用します。ドキュメントでは、ツール呼び出しに対応しないモデルはチャット専用となり、拡張機能も無効にする必要があると注意しています。ツール対応モデルを選んでください。

2026 年 10 月 1 日確認：goose のインストール、providers、ACP providers、CLI コマンド、環境変数に関するドキュメント（aaif-goose/goose の main ブランチ）、および GitHub API のバージョンとアーカイブ状態を確認しました。Kunavo は自社エンドポイントを goose で実際に実行していません。価格はリアルタイムの料金表に基づき、金額例はすべて説明用の token 算術です。