Troubleshoot an OpenCode model connection

If OpenCode opens but a message fails, identify which part of the connection failed before reinstalling. Reinstallation usually does not fix credentials, model permissions, or account limits. This checklist follows official documentation; error codes can differ between providers.

中文版

Identify the failing step

Symptom	Check first	Reference
`opencode` command not found	Installation and terminal PATH	Install · Windows / WSL
Authentication failure, 401 or 403	Provider, credentials and account permissions; 403 can also indicate a network policy	Providers
Timeout or certificate error	Proxy, local connection bypass and corporate CA	Network
Model not found or unavailable	Provider model list, exact model ID and access	Models
429, exhausted allowance or insufficient balance	Provider rate limits and billing account	Zen · provider console
Configuration changes have no effect	Configuration location and project/global precedence	Configuration

1. Test a minimal connection

In the TUI, use /connect to connect a provider, then /models to select a model from that provider. Send a simple question before adding optional plugins or MCP services, so failures are easier to isolate.

Check that the API key belongs to the selected provider.
Confirm in the provider console that the key is valid, the model is permitted, and billing requirements are met.
For a custom OpenAI-compatible service, use its documented endpoint and exact model ID.
Never include a complete API key in a public issue or shared configuration.

Fix the error you received

Error	Change first	A successful check
401 / invalid API key	Reconnect the selected provider with its own key; check the environment used to launch OpenCode	A small prompt returns and the same account records usage
403 / access denied	Check model access and organization/network restrictions; a new key alone may not change these	The permitted model works from the intended network
404 / model not found	Match provider prefix, exact model ID and endpoint protocol; avoid duplicating `/v1` in a custom base URL	The selected model accepts a request at the configured endpoint
429 / rate limit	Distinguish a per-minute limit from exhausted credit; reduce parallel requests or resolve the account limit	A request succeeds after the stated reset or account correction
TLS / certificate error	Supply the corporate CA with `NODE_EXTRA_CA_CERTS` and restart from that environment	HTTPS works without disabling certificate verification

For a custom gateway, the API configuration template shows where the endpoint, key and model ID belong. Keep the request and model fixed while changing one setting at a time.

2. Check proxies and certificates

OpenCode supports standard proxy environment variables. Its TUI also communicates with a local server, which should bypass the proxy. The following is a macOS/Linux shell example; substitute your actual proxy address. On Windows, use the environment-variable syntax for your shell.

# 设置实际代理，并保留已有的其他绕过项。
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1${NO_PROXY:+,$NO_PROXY}

Start OpenCode from that terminal. An already-running desktop application may not inherit the terminal environment.

For a corporate CA, configure NODE_EXTRA_CA_CERTS using the certificate supplied by your administrator. Follow the network guide; do not disable TLS verification to hide certificate errors.

3. Separate software cost from model usage

The OpenCode client is free to install. Model usage may be billed separately. Zen and other providers can have different allowances, free models and billing rules.

Before changing providers, identify the current provider, account and model, then inspect its console. Changing clients does not reset a provider's limits. For Zen, use the model prices and spending controls. For another provider, inspect that account’s usage and rate-limit settings.

4. Collect useful diagnostics

Record the time, operating system, OpenCode version, provider, model ID, error code and whether a proxy is involved. Use the troubleshooting guide to locate logs. Remove credentials, personal information and project content before sharing them.

If the connection succeeds but the agent behaves unexpectedly, review AGENTS.md rules and tool permissions separately.