Connect Goose to NekoCloud
Goose relies on model tool-calling capabilities; receiving text is not proof of toolchain compatibility. This guide uses the officially documented OpenAI-compatible connection. NekoCloud has not individually acceptance-tested this toolchain and does not guarantee every model.1
1. Prepare
Install Goose using its official installation guide. Back up existing Goose settings and custom provider files; do not use Reset to clear previous configuration. Create a NekoCloud key, check balance and group permissions, and obtain the exact ID from the model plaza.
2. Minimal configuration: built-in OpenAI provider
Set these values in a Linux/macOS terminal and start a new session:
export OPENAI_API_KEY="REPLACE_WITH_API_KEY"
export OPENAI_HOST="https://api.nekocloud.vip"
export OPENAI_BASE_PATH="v1/chat/completions"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="REPLACE_WITH_MODEL_ID"
goose session| Field | Meaning |
|---|---|
OPENAI_HOST | Root host only, without /v1 |
OPENAI_BASE_PATH | Request path v1/chat/completions |
OPENAI_API_KEY | Actual key, without Bearer |
GOOSE_PROVIDER / GOOSE_MODEL | Provider route / exact model ID |
The resulting endpoint should be https://api.nekocloud.vip/v1/chat/completions. Unlike clients that accept a /v1 base URL, this route splits host and path. Avoid a doubled /v1, and do not store the key in ordinary config.yaml.1
3. Separate custom provider
To preserve another OpenAI connection, run goose configure → Custom Providers → Add A Custom Provider. Choose OpenAI Compatible, name it NekoCloud, require authentication and enter your actual key, and supply the real model ID. The official custom JSON example uses a complete Chat Completions endpoint in base_url; enter https://api.nekocloud.vip/v1/chat/completions for this route, not the built-in route's root host.1
On Linux/macOS, generated files live in ~/.config/goose/custom_providers/. Actual fields include name, engine, api_key_env, base_url, and models. Use the wizard rather than guessing context limits. api_key_env is not a literal key. Do not mix this route with the preceding OPENAI_* configuration.1
4. Model selection, reload, and verification
Start a new session after changes. Desktop supports model switching and custom model entry under Settings → Models. The CLI configuration wizard does not accept arbitrary custom model names; use GOOSE_MODEL where needed.1 Verify the provider and ID, send a short greeting, then allow only a file-reading extension to read README and quote it in a summary. Reject writes and command execution. Inspect the actual tool result, final answer, and unchanged files. Tests may incur charges; confirm consent first.
Compare client usage with NekoCloud records by time, model, and tokens; missing statistics do not mean zero cost. Keep keys out of Git, logs, and screenshots, and prefer hidden input. Desktop processes may not inherit terminal variables. For 401, check credentials; for 404, check paths; for tool failures, check model capabilities. Stop repeated retries.