Goose on Codex Pooler

Goose is an open-source AI agent for coding and other tasks on your computer. Its desktop app and CLI can work with files and tools to carry out multi-step workflows. Connect Goose to Codex Pooler to use your Pool’s models in those sessions.

Before you start

• Install Goose using the official instructions for your operating system.
• Have a Codex Pooler URL reachable from the client.
• Create a Pool API key and choose a model available to that Pool.

Configure the connection

Use the commands for the terminal that starts the client. Environment-variable assignments below apply to that terminal; desktop apps and services need the variables in their own launch environment.

Config file path

Put persistent Goose provider and extension settings in config.yaml:

OS	Config file
macOS	~/.config/goose/config.yaml
Linux	~/.config/goose/config.yaml
Windows	%APPDATA%\Block\goose\config\config.yaml

These are the default locations. On Windows, paste the %USERPROFILE%, %APPDATA% or %LOCALAPPDATA% path into File Explorer’s address bar. For a client installed inside WSL, use the Linux paths and commands inside WSL. Keep any custom configuration folder or profile you already use.

If you set GOOSE_PATH_ROOT, the configuration folder is its config subfolder.

Goose also keeps related files in the same config area: permission.yaml for tool permission levels, secrets.yaml when file-based secret storage is used, permissions/tool_permissions.json for runtime permission decisions, and prompts/ for prompt templates. Direct edits usually require restarting existing Goose sessions; goose info -v shows the active settings.

You can also manage settings from Goose Desktop Settings or by running goose configure in Goose CLI. Environment variables have higher precedence than the config file, so OPENAI_API_KEY can stay outside YAML.

Set CODEX_POOLER_API_KEY to your Pool API key, then export OPENAI_API_KEY in the shell that starts Goose, or use Goose’s secret storage:

macOS / Linux / WSL

export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"

Windows PowerShell

$env:OPENAI_API_KEY = "$env:CODEX_POOLER_API_KEY"

Add the provider settings to config.yaml:

config.yaml

GOOSE_PROVIDER: openai
GOOSE_MODEL: gpt-6-sol
OPENAI_HOST: https://codex-pooler.example.com
OPENAI_BASE_PATH: v1/responses
GOOSE_CONTEXT_LIMIT: 828400
GOOSE_MAX_TOKENS: 128000
GOOSE_AUTO_COMPACT_THRESHOLD: 0.95

For local setup, change OPENAI_HOST to http://localhost:4000.

Choose a model

Set GOOSE_MODEL to a model available to your Pool.

Goose reads GOOSE_CONTEXT_LIMIT and GOOSE_MAX_TOKENS into its model config. The 828400 value above is a long-profile example for a model whose selected Pool catalog source reports an 872000-token raw ceiling. Provider accounts can temporarily report different ceilings for the same model; a selected 272000-token profile exposes 258400 instead. Use /v1/models.context_length as the authoritative GOOSE_CONTEXT_LIMIT, not the raw ceiling. For the long-profile example, Goose’s 0.95 auto-compaction threshold starts compaction at 786980 tokens.

Verify the connection

Check the headless CLI path with tool access enabled:

macOS / Linux / WSL

export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
goose run \
  --no-session \
  --provider openai \
  --model gpt-6-sol \
  --with-builtin developer \
  --text 'Use your developer tool to create goose-ok.txt containing exactly: goose ok. Then reply with exactly: goose ok'

Windows PowerShell

$env:OPENAI_API_KEY = "$env:CODEX_POOLER_API_KEY"
goose run --no-session --provider openai --model gpt-6-sol --with-builtin developer --text 'Use your developer tool to create goose-ok.txt containing exactly: goose ok. Then reply with exactly: goose ok'

Confirm that goose-ok.txt contains the expected text. In Codex Pooler’s request logs, match the request time, API key, model, and final status to your test. A reply alone does not confirm that the client used your Pooler instance.

Operator MCP (optional)

For optional operator MCP metadata access, add a remote Streamable HTTP extension. Codex Pooler model use does not require this. Goose stores remote extension headers in its config, so use a dedicated MCP token.

config.yaml

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
extensions:
  codex_pooler:
    enabled: true
    type: streamable_http
    name: codex_pooler
    uri: https://codex-pooler.example.com/mcp
    headers:
      Authorization: "Bearer <operator-mcp-token>"
    timeout: 300
    bundled: null
    available_tools: []

For local MCP setup, change the extension uri to http://localhost:4000/mcp.

Use a Pool API key for OpenAI-compatible model requests and an operator MCP token for /mcp. Do not reuse the Pool API key for MCP.

Compatibility notes

This client uses Codex Pooler’s narrow OpenAI-compatible /v1 surface. For shared route support and limits, see OpenAI-compatible SDKs.