OpenCode API Key & Auth: Astra, Grok and Proxy Setup

Most OpenCode authentication questions look similar, but they refer to different layers. An LLM provider API key is not the same thing as an OpenCode Go login, an xAI OAuth flow, or the password that protects opencode web.

This guide separates those layers and gives you a working custom-provider setup for BetterToken, including a copy-ready example for gpt-6-astra, regional network settings for Linux and Astra Linux environments, direct Grok authentication, and the correct way to secure the OpenCode Web interface.

OpenCode changes quickly. Before production use, compare the commands below with the current OpenCode documentation and confirm the exact model ID in the BetterToken model catalog.

Quick answer

What you want to do	Correct place or command
Save a provider API key interactively	Run `/connect` inside OpenCode
See saved providers	Run `opencode auth list`
Define a custom provider, Base URL, and models	`opencode.json` or `opencode.jsonc`
Use BetterToken	Base URL: `https://www.bettertoken.ai/v1`
Use GPT-6 Astra	Model ID: `gpt-6-astra`, if currently available to your account
Sign in to OpenCode Go	`/connect` → OpenCode Go → `https://opencode.ai/auth`
Authenticate directly with xAI/Grok	`/connect` → xAI → OAuth subscription or API key
Protect OpenCode Web	Set `OPENCODE_SERVER_PASSWORD` before `opencode web`
Use a regional or corporate proxy	Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`

Before you start

Prepare the following:

a recent OpenCode installation;
a separate API key for testing rather than a shared production key;
the exact model ID shown in the provider catalog;
a small test repository where the agent can be prevented from changing important files;
terminal access to the OpenCode installer and the API endpoint.

Treat an API key like a password. Do not paste a real key into a prompt, screenshot, issue, article, or Git repository.

Install OpenCode

The official installer works on macOS and Linux:

curl -fsSL https://opencode.ai/install | bash

You can also install through npm:

npm install -g opencode-ai

On Windows, OpenCode recommends WSL for the best compatibility. Chocolatey and Scoop are also documented options:

choco install opencode

scoop install opencode

Check the installation:

opencode --version

A version number should be printed. If the shell says command not found, reopen the terminal and verify that the installation directory is included in PATH.

Understand the four authentication layers

1. Provider API key

This key authorizes calls to BetterToken, xAI, OpenAI, or another model provider. OpenCode can save it through /connect, or read it from an environment variable referenced by the config file.

2. OpenCode Go or OpenCode Zen authentication

OpenCode Go and Zen are OpenCode-operated model services. Their flow opens https://opencode.ai/auth, where you sign in, complete billing setup, copy an API key, and paste it back into /connect.

This key is unrelated to your BetterToken key.

3. xAI/Grok authentication

The current OpenCode provider flow supports either a qualifying xAI subscription through device-code OAuth or a pay-as-you-go xAI API key. This is a direct xAI connection, not a BetterToken connection.

4. OpenCode Web password

OPENCODE_SERVER_PASSWORD protects the local OpenCode HTTP server and browser interface with basic authentication. It does not authorize model requests and cannot replace a provider API key.

How to set an API key in OpenCode

OpenCode supports JSON and JSONC. The official examples commonly use opencode.json; JSONC is useful when you need comments. The important point is that credentials and provider definitions are separate.

Method 1: save the key with `/connect`

Start OpenCode in a safe test directory:

mkdir opencode-first-test
cd opencode-first-test
opencode

Inside the TUI, run:

/connect

For BetterToken:

Choose Other.
Enter the provider ID bettertoken.
Paste your BetterToken API key into the credential field.
Exit or restart OpenCode after adding the provider config.

OpenCode stores credentials added through /connect in:

~/.local/share/opencode/auth.json

Check that the provider is registered without printing the secret:

opencode auth list

The provider ID used in /connect must exactly match the provider ID in your config. If you entered bettertoken, the config key must also be bettertoken.

Method 2: configure `opencode.json` or `opencode.jsonc`

Use the global file when the provider should be available in every project:

~/.config/opencode/opencode.json

Use a project-level opencode.json or opencode.jsonc when one repository needs its own model or endpoint.

The following example uses BetterToken and the current API model ID gpt-6-astra:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

Before using it, confirm that gpt-6-astra appears in your current BetterToken catalog and access group. If the catalog shows another model ID, replace both bettertoken/gpt-6-astra and the gpt-6-astra key under models.

Do not append /chat/completions to the Base URL. The adapter builds the request path itself.

Use an environment variable instead of `/connect`

On macOS or Linux:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

On PowerShell:

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

Then reference the variable in the provider options:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

This is safer than writing a literal secret into the JSON file. If the environment variable is missing, OpenCode substitutes an empty string, which normally results in a 401 error.

Why OpenCode may ignore your config

OpenCode merges configuration sources. Later sources override earlier ones when the same field conflicts. The most relevant order is:

organization remote defaults;
global config in ~/.config/opencode/opencode.json;
a custom file pointed to by OPENCODE_CONFIG;
project opencode.json or opencode.jsonc;
inline OPENCODE_CONFIG_CONTENT;
administrator-managed settings, which can override user files.

If OpenCode chooses the wrong model or endpoint, do not delete files at random. Search for every active config and compare:

the top-level model value;
provider.bettertoken.options.baseURL;
the model keys under provider.bettertoken.models;
OPENCODE_CONFIG and OPENCODE_CONFIG_CONTENT in the current shell.

Restart OpenCode after changing provider settings.

OpenCode Astra: model name or Astra Linux?

The query “OpenCode Astra” can refer to two different things.

Use GPT-6 Astra in OpenCode

If you mean the OpenAI model, use the exact API ID gpt-6-astra. With the BetterToken provider above, select:

bettertoken/gpt-6-astra

Open the model picker inside OpenCode:

/models

If the model does not appear, check the provider ID, the models map, your BetterToken access group, and the current catalog. Do not guess a model ID from a display name.

Run OpenCode on Astra Linux

OpenCode’s documentation lists Linux installation methods but does not publish a separate Astra Linux-specific support promise. Treat Astra Linux as a Linux environment and verify the actual machine rather than assuming compatibility.

Check the architecture and required tools:

uname -m
command -v curl
command -v bash

Then test the installer and API routes separately. A reachable model API does not guarantee that the OpenCode installer, npm registry, GitHub, or update server is also reachable.

For a standard proxy:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXY is important because the TUI communicates with a local OpenCode HTTP server. Sending loopback traffic through the proxy can cause connection loops or an apparently frozen interface.

If your organization uses a private certificate authority:

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

Do not hardcode real proxy credentials in shared shell scripts. Use your organization’s secret manager or protected environment configuration.

OpenCode Grok auth: direct xAI or a gateway?

Direct xAI connection

Run:

/connect

Choose xAI. Current OpenCode documentation presents two authentication paths:

a supported xAI subscription through device-code OAuth;
a manually entered xAI API key from the xAI console.

After authorization, run:

/models

and select an available Grok model.

Grok through BetterToken or another gateway

A custom gateway works only if that gateway currently exposes a valid Grok model and protocol. Do not invent a Grok model ID or assume that every OpenAI-compatible gateway carries xAI models.

Check the live provider catalog first. If Grok is not listed, use OpenCode’s direct xAI provider instead. Community plugins such as Grok auth extensions are separate from the official provider flow and should be evaluated for maintenance, permissions, and credential handling before installation.

OpenCode Go auth

OpenCode Go is not a command that authenticates every provider. It is an OpenCode subscription service.

To connect it:

Run /connect.
Choose OpenCode Go.
Open https://opencode.ai/auth.
Sign in, complete billing if required, and copy the generated key.
Paste the key back into OpenCode.
Run /models to choose one of the models included in the plan.

Use this flow only when you intend to use OpenCode Go. For BetterToken, keep the provider ID and key under bettertoken.

OpenCode Web password: use the environment variable

A common search is opencode web password, and some examples incorrectly suggest a -p password flag. The documented method is the OPENCODE_SERVER_PASSWORD environment variable.

On macOS or Linux:

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

To set a custom username as well:

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

On PowerShell:

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

The username defaults to opencode. Without a password, local-only use on 127.0.0.1 may be acceptable, but network access should be protected. Do not bind the service to 0.0.0.0 or expose it through a tunnel before authentication and network controls are in place.

The Web password protects the OpenCode server. It does not protect your provider account if the provider key is leaked elsewhere.

Verify the first request

Restart OpenCode after editing JSON:

opencode

Open the model selector:

/models

Choose bettertoken/gpt-6-astra, then send a small, easy-to-check prompt:

Return only this JSON and do not modify any files: {"tool":"opencode","sum":4}

A successful setup should satisfy all of these checks:

OpenCode returns valid JSON;
no project file is changed;
the selected model is bettertoken/gpt-6-astra;
a corresponding request appears in the BetterToken dashboard;
the model, status, input tokens, output tokens, and charge look reasonable.

If OpenCode responds but no BetterToken request appears, a higher-priority config may be routing the request to another provider.

Troubleshooting

`401` or credential error

Run /connect again and use provider ID bettertoken.
Run opencode auth list.
If using {env:BETTERTOKEN_API_KEY}, print only whether the variable exists, not the secret itself.
Confirm that the key is active and has sufficient balance or permissions.

`404` or API path error

The BetterToken Base URL should be:

https://www.bettertoken.ai/v1

Do not append /chat/completions manually.

`model not found`

Confirm the exact current ID in the model catalog. The top-level model value and the key under models must match the provider and model you intend to call.

The wrong endpoint or model is used

Check global, custom, project, inline, and managed configs. Then restart OpenCode and select the model again with /models.

OpenCode hangs when a proxy is enabled

Ensure loopback addresses are excluded:

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Web returns `Unauthorized`

Confirm that the browser uses the configured username and password. Also check whether an old OPENCODE_SERVER_PASSWORD remains in the shell environment and whether a client process inherited a different value.

`opencode: command not found`

Reopen the terminal, check PATH, and run the package manager’s global binary-location command. Avoid installing the same binary through several package managers until you know which executable is active.

FAQ

How do I set an API key in OpenCode?

The recommended interactive method is /connect. For a custom provider, choose Other, enter the provider ID, and paste the key. You must still define the custom provider and models in opencode.json or opencode.jsonc.

Is the file called `opencode.json` or `opencode.jsonc`?

OpenCode supports both JSON and JSONC. Use JSONC when you need comments. Keep only one active project config unless you deliberately understand how multiple sources merge.

Where does OpenCode store API keys?

Credentials added through /connect are stored in ~/.local/share/opencode/auth.json. Avoid publishing, syncing, or committing that file.

Can I put the API key directly in the config?

OpenCode supports options.apiKey, but a literal secret in a tracked JSON file is risky. Prefer /connect, {env:VARIABLE_NAME}, or {file:path/to/secret}.

Is OpenCode Go auth the same as provider auth?

No. OpenCode Go is a separate OpenCode service. A BetterToken, xAI, or other provider key remains independent.

How do I set an OpenCode Web password?

Set OPENCODE_SERVER_PASSWORD before running opencode web. The documented method is an environment variable, not a generic -p password flag.

How do I authenticate Grok in OpenCode?

Use /connect, choose xAI, and select either the supported OAuth subscription flow or manual API-key entry. A gateway route is valid only when that gateway actually lists a Grok model.

Does “OpenCode Astra” mean GPT-6 Astra or Astra Linux?

It can mean either. For the model, use gpt-6-astra. For Astra Linux, follow the Linux installation and network checks and validate the specific distribution build.

Do I need a VPN to use OpenCode from Russia?

There is no single answer because installation downloads, GitHub, npm, the OpenCode website, and the model API are separate network paths. Test each path independently and use compliant corporate or regional network configuration where needed.