Connect OpenCode to NekoCloud
This guide adapts the tool’s official third-party provider documentation for NekoCloud. It does not imply official certification of this service. NekoCloud has not individually tested the toolchains described here. These are configuration references and acceptance steps for you to perform; no paid requests were made while preparing this guide. Install the tool, create a NekoCloud API key, and confirm the model is available in the model plaza and your key’s group. Replace REPLACE_WITH_MODEL_ID with the exact model ID, not its display name.
Configuration entry point and minimal example
Open opencode.json in the project root. The official global configuration location, ~/.config/opencode/opencode.json, is another option, but this guide uses project configuration. Read and back up the existing file, then merge nekocloud into its existing provider object. Do not redeclare the whole provider object or remove existing providers. This standalone structure illustrates the fields; extract only the relevant entries when editing an existing file:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"nekocloud": {
"npm": "@ai-sdk/openai-compatible",
"name": "NekoCloud",
"options": {
"baseURL": "https://api.nekocloud.vip/v1",
"apiKey": "{env:NEKOCLOUD_API_KEY}"
},
"models": {
"REPLACE_WITH_MODEL_ID": {
"name": "NekoCloud model"
}
}
}
}
}The key inside models is the exact request model ID; name is only a display label. This example does not guess context limits, output limits, image support, or tool capabilities. Securely provide NEKOCLOUD_API_KEY to the process that starts OpenCode, not merely to a different terminal. {env:...} is OpenCode’s interpolation syntax, not the shell’s $... syntax.
Alternatively, remove options.apiKey and use the TUI command /connect → Other → provider ID nekocloud, then enter your own key through the interactive prompt. The ID must match the configuration. /connect stores a credential; it does not create the model configuration. The official credential location is ~/.local/share/opencode/auth.json. Do not share that file or mix multiple authentication sources.
Save, exit, and restart OpenCode to reload both configuration and the startup environment. Run /models, select NekoCloud / your model, and start a new conversation. If the model is missing, check the configuration file, JSON syntax, provider ID, and model key before considering any changes to credentials.
Chat, Responses, and Anthropic are distinct protocols
The example uses @ai-sdk/openai-compatible for /v1/chat/completions. If you have confirmed that your selected route uses /v1/responses, change this provider’s npm to @ai-sdk/openai while retaining https://api.nekocloud.vip/v1 as its base URL. These packages are not interchangeable “OpenAI compatible” switches. Do not append /chat/completions or /responses to baseURL.
Anthropic Messages is a separate protocol. NekoCloud’s Anthropic root is https://api.nekocloud.vip, not a replacement value for the OpenAI configuration above. An Anthropic SDK may require a versioned base URL; check that SDK’s documentation separately. This page does not provide an unverified Anthropic configuration or promise that every model supports both OpenAI routes.
Acceptance: reply, usage record, and a read-only tool round trip
These steps send model requests and may incur charges. Run them only with your consent. Disable automatic approval, automatic command execution, and unnecessary background requests first. Use a small workspace without sensitive information.
- Start a new conversation, confirm the active provider and model, and send “Reply only OK; do not call tools.” After a normal reply, check the NekoCloud dashboard’s usage records for matching request time, model, and usage/token information. Client cost estimates are not the NekoCloud bill.
- Send “Use only a file-reading tool to read the first few lines of the existing README.md. Return its first line and a one-sentence summary. Do not edit files, run commands, or access the network.” If there is no README.md, choose another existing non-sensitive text file and change the prompt’s path; do not ask the agent to create a file.
- Manually approve that read-only call. Confirm the task trace contains an actual tool name, arguments, and file-reading result, followed by a model answer based on that result. A reply merely claiming to have read the file is not a pass. Check usage records again and verify that the workspace was not modified.
A text reply proves only the chat connection. Matching usage records confirm the request reached the intended account. The tool invocation, tool result, and subsequent model answer must all complete to pass this read-only round trip. If a step fails, stop retrying and retain the request time, model, error code, and redacted request ID rather than repeatedly starting long tasks.
Safety and troubleshooting
Back up existing configuration and merge only the new provider or model entries. Do not replace the whole file or remove other models, rules, tools, or login information. Enter the key itself without a Bearer prefix; REPLACE_WITH_API_KEY is only a placeholder. Never commit real keys, authorization headers, secret-bearing configurations, or sensitive source code to Git, include them in screenshots, or send them to support. Protect local configuration and backup copies too.
For 401 errors, check the active configuration, key, and authentication source. For missing models, check the exact ID and key-group permissions. For 404 errors, check the URL and protocol; avoid duplicate /v1 segments or using a full request path as the base URL. For 429 errors, reduce request frequency according to the response and usage records rather than retrying indefinitely. Do not disable TLS verification, expand execution permissions, or change system network settings to troubleshoot. With Remote SSH, WSL, or containers, ensure configuration and environment variables belong to the host actually running the extension, not just your local terminal.