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.
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, Go 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. Check the current official Go documentation (opens in a new tab) and Zen documentation (opens in a new tab) instead of relying on an old pricing screenshot.
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.
Sources and update date
Checked on September 14, 2026 against the official introduction (opens in a new tab), network documentation (opens in a new tab) and troubleshooting documentation (opens in a new tab). This is a community guide, not an official support service or a provider of model accounts.