goose Coding Agent Tutorial: Installation, Model Sources, API Settings, and Costs

goose is an open-source (Apache-2.0) AI coding agent that can read and edit files and run commands from a terminal or desktop app. Getting started takes three steps: install it, choose a model provider, and open a session to give it a task. goose itself is free; costs come from the model you connect. This guide follows the official documentation as of October 1, 2026, and explains installation, the three payment options, connecting an OpenAI-compatible endpoint (including the common /v1 pitfall), and common operations. The latest version is v1.52.0, released September 23, 2026.

First, a clarification on the name. This page covers the coding agent at goose-docs.ai, whose repository is aaif-goose/goose, formerly block/goose, which moved in April 2026 under the Linux Foundation's Agentic AI Foundation. It is not goose.ai, a separate hosted inference service whose pricing is unrelated. goose currently has no Traditional Chinese interface, so menu names below are given in their original English.

Installation

The official distribution includes a desktop version (goose Desktop) and a command-line version (goose CLI); both use the same configuration.

# 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

On Windows, download the desktop version from the official website. For the CLI, it's recommended to run the same installation command in Git Bash (PowerShell also works). The Homebrew package is still named block-goose, because the rename hasn't fully propagated to the installation package; this doesn't mean the project is still owned by Block.

First launch: choose a model provider

The first time you open goose Desktop, you'll see a welcome screen; the CLI automatically enters configuration mode (to change settings later, run goose configure). The installation page lists three options:

• OpenRouter Login — Sign in with an OpenRouter account to configure a model automatically.
• Tetrate Agent Router Service Login — Sign in with Tetrate. The documentation says your first automatic authentication through goose gives you $10 in free credit, for both new and existing users.
• Manual Configuration — Choose a provider and enter a key yourself. Use this option to connect an OpenAI-compatible endpoint (such as Kunavo).

Choose from three payment options before configuring

The ACP route details come from goose's ACP providers documentation, which also notes that ACP session IDs differ from goose's, so telemetry fields may not match. If you already have a subscription and just want to save on API costs, consider this option first.

Connecting an OpenAI-compatible endpoint: don't add /v1 to the Host URL

This is where most people get stuck. goose doesn't take a full base URL; it splits it into “host” and “path.” According to the providers documentation, OPENAI_HOST is the “custom endpoint URL (default api.openai.com),” and OPENAI_BASE_PATH is the “request path appended to the host (default v1/chat/completions)”. When connecting a proxy, set OPENAI_HOST to “the proxy's root address (without a path).” For Kunavo, use:

# 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

In goose Desktop, go to Settings → Models → Configure providers → OpenAI; in the CLI, use goose configure → Configure Providers → OpenAI. Leave Organization ID and Project blank; those are for OpenAI accounts. If the Host URL is https://api.kunavo.com/v1, the request becomes /v1/v1/chat/completions. The documentation also says that “404 usually means OPENAI_BASE_PATH is wrong for your proxy”—it's a path error, not a key error. Conversely, a 401 “No api key passed in” means the key wasn't read, for example because it was entered in config.yaml, which goose ignores.

A cleaner alternative is to make it a separate provider in the list. goose reads JSON definition files from the custom_providers folder. Kunavo provides a file generated from its live pricing list, containing only models that support tool calling and only the key's environment variable name, not the key itself:

# 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

On Windows, the folder is %APPDATA%\Block\goose\config\custom_providers\. Once the file is in place, Configure providers in goose Desktop will show Kunavo. The key can be stored in the system keychain instead of an environment variable. According to the goose source code, model IDs starting with gpt-5 or gpt-6 use /v1/responses, while the others use /v1/chat/completions; Kunavo provides both. You can also configure it manually: Configure providers → Add Custom Provider, choose OpenAI Compatible as the type, and set the API URL to https://api.kunavo.com/v1. The full English setup page is the goose integration guide.

To be transparent: the settings above are compiled from the goose documentation and source code. Kunavo has not run its own endpoint through goose—not in a session, with streaming, or in tool-call round trips. Keep your current working option available and try a small task that reads and writes files first.

Common operations

• Start a session: goose session (optionally name it with -n 名稱), then resume it with goose session --resume -n 名稱; goose session list lists history.
• Switch permission modes: Enter /mode during a session to choose auto, approve, chat, or smart_approve. To have it ask you before every step, use approve.
• Choose a model: goose configure doesn't accept custom model names. For IDs that aren't in the list, enter them in goose Desktop or set GOOSE_MODEL in config.yaml.
• Project instruction files: By default, goose reads .goosehints and AGENTS.md (controlled by CONTEXT_FILE_NAMES). Put project rules in these files so they carry over when you switch to another agent.
• Don't choose a model without tool-calling support: the documentation says such models “can only do chat completions,” and extensions must also be disabled.

How much does one session cost?

The following is illustrative token arithmetic, not a measured task cost or a cap on your bill. Assume an agent session sends a total of 400,000 uncached input tokens and receives 25,000 output tokens across multiple rounds (the agent resends context on every turn, so input usage is particularly high). Unit prices are the live per-million-token rates from the Kunavo pricing list.

Regarding caching: goose's documentation says that when using Claude through the Anthropic, Amazon Bedrock, Databricks, OpenRouter, or LiteLLM providers, Anthropic's cache_control marker is added automatically. Claude through the generic OpenAI provider isn't on that list, so goose won't add these markers; the table above therefore assumes no cache discount, a conservative estimate. The amounts on Kunavo's pricing list are billing floors, not ceilings: when the upstream reports a cost, the bill uses whichever is higher: the listed price or the upstream cost × the applicable markup.

Paying from Taiwan

Kunavo uses prepaid top-ups and charges per token, with no monthly fee. The minimum top-up is $10; checkout is through Stripe, with Taiwanese cards (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay, and Link available in Taiwan; JKoPay and LINE Pay are not on the available list. See billing details; when ready, create an account and generate a key. To compare other agents, see the English goose alternatives and goose vs Claude Code.

Frequently asked questions

Verified on October 1, 2026 against goose's installation, providers, ACP providers, CLI commands, and environment variable documentation (the aaif-goose/goose main branch), as well as the GitHub API's release and archive status. Kunavo has not run its endpoint through goose; prices come from the live pricing list, and all example amounts are illustrative token arithmetic.