OpenCode: API Key, авторизация, Astra, Grok, прокси и Web-пароль

Запросы об авторизации OpenCode часто выглядят одинаково, хотя относятся к разным уровням. API Key провайдера моделей — это не то же самое, что вход в OpenCode Go, OAuth xAI или пароль, защищающий opencode web.

В этом руководстве эти механизмы разделены. Ниже приведена рабочая настройка custom provider для BetterToken, готовый пример с gpt-6-astra, сетевые параметры для Linux и Astra Linux, прямая авторизация Grok, подключение OpenCode Go и правильная защита Web-интерфейса OpenCode.

OpenCode быстро развивается. Перед использованием в рабочей среде сверьте команды с актуальной документацией OpenCode и проверьте точный Model ID в каталоге BetterToken.

Короткий ответ

Задача	Где и как настраивать
Интерактивно сохранить API Key провайдера	Выполнить /connect внутри OpenCode
Посмотреть сохранённых провайдеров	Выполнить opencode auth list
Задать custom provider, Base URL и модели	opencode.json или opencode.jsonc
Подключить BetterToken	Base URL: https://www.bettertoken.ai/v1
Использовать GPT-6 Astra	Model ID: gpt-6-astra, если он доступен аккаунту
Войти в OpenCode Go	/connect → OpenCode Go → https://opencode.ai/auth
Авторизовать xAI/Grok напрямую	/connect → xAI → OAuth подписки или API Key
Защитить OpenCode Web	Задать OPENCODE_SERVER_PASSWORD до opencode web
Использовать региональный или корпоративный прокси	Задать HTTP_PROXY, HTTPS_PROXY и NO_PROXY

Что подготовить

Понадобятся:

• свежая версия OpenCode;
• отдельный тестовый API Key вместо общего рабочего ключа;
• точный Model ID из каталога провайдера;
• небольшой тестовый репозиторий, где агент не повредит важные файлы;
• доступ из терминала к установщику OpenCode и API endpoint.

Относитесь к API Key как к паролю. Не вставляйте настоящий ключ в промпт, скриншот, Issue, статью или Git-репозиторий.

Установка OpenCode

Для macOS и Linux используйте официальный установщик:

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

Также доступна установка через npm:

npm install -g opencode-ai

В Windows OpenCode рекомендует WSL для лучшей совместимости. В документации также указаны Chocolatey и Scoop:

choco install opencode

scoop install opencode

Проверьте установку:

opencode --version

Должен появиться номер версии. Если терминал отвечает command not found, откройте его заново и проверьте, входит ли каталог установки в PATH.

Четыре разных вида авторизации

1. API Key провайдера моделей

Этот ключ разрешает запросы к BetterToken, xAI, OpenAI или другому провайдеру. OpenCode может сохранить его через /connect либо получить из переменной окружения, указанной в конфигурации.

2. Авторизация OpenCode Go или OpenCode Zen

OpenCode Go и Zen — сервисы моделей от команды OpenCode. Их процесс открывает https://opencode.ai/auth: там нужно войти, настроить оплату, скопировать API Key и вставить его обратно в /connect.

Этот ключ не связан с ключом BetterToken.

3. Авторизация xAI/Grok

Текущий процесс OpenCode для xAI поддерживает подходящую подписку xAI через device-code OAuth либо отдельный pay-as-you-go API Key xAI. Это прямое подключение к xAI, а не к BetterToken.

4. Пароль OpenCode Web

OPENCODE_SERVER_PASSWORD защищает локальный HTTP-сервер OpenCode и браузерный интерфейс с помощью Basic Auth. Он не авторизует запросы к модели и не заменяет API Key провайдера.

Как задать API Key в OpenCode

OpenCode поддерживает JSON и JSONC. В официальных примерах часто используется opencode.json; JSONC удобен, когда нужны комментарии. Главное — понимать, что хранение credential и описание провайдера настраиваются отдельно.

Способ 1: сохранить ключ через /connect

Запустите OpenCode в безопасном тестовом каталоге:

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

В TUI выполните:

/connect

Для BetterToken:

1. Выберите Other.
2. Введите provider ID bettertoken.
3. Вставьте API Key BetterToken в поле credential.
4. После добавления конфигурации провайдера полностью перезапустите OpenCode.

Credential, добавленные через /connect, сохраняются в:

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

Проверьте регистрацию провайдера без вывода секрета:

opencode auth list

Provider ID из /connect должен точно совпадать с ID в конфигурации. Если введено bettertoken, ключ конфигурации тоже должен называться bettertoken.

Способ 2: настроить opencode.json или opencode.jsonc

Для доступа из всех проектов используйте глобальный файл:

~/.config/opencode/opencode.json

Если отдельному репозиторию нужны собственные модель или endpoint, поместите opencode.json либо opencode.jsonc в корень проекта.

Ниже — полный пример BetterToken с текущим 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"
        }
      }
    }
  }
}

Перед запуском убедитесь, что gpt-6-astra присутствует в актуальном каталоге BetterToken и доступен вашей группе доступа. Если каталог показывает другой ID, замените и bettertoken/gpt-6-astra наверху, и ключ gpt-6-astra внутри models.

Не добавляйте /chat/completions к Base URL вручную. Адаптер сам формирует путь запроса.

Переменная окружения вместо /connect

В macOS или Linux:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

В PowerShell:

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

После этого укажите переменную в 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"
        }
      }
    }
  }
}

Это безопаснее, чем записывать настоящий ключ прямо в JSON. Если переменная окружения отсутствует, OpenCode подставит пустую строку, и обычно появится ошибка 401.

Почему OpenCode игнорирует конфигурацию

OpenCode объединяет несколько источников настроек. Если одно поле задано несколько раз, более поздний источник переопределяет ранний. Для обычной установки важен такой порядок:

1. удалённые настройки организации;
2. глобальный ~/.config/opencode/opencode.json;
3. файл, указанный в OPENCODE_CONFIG;
4. проектный opencode.json или opencode.jsonc;
5. inline-конфигурация OPENCODE_CONFIG_CONTENT;
6. настройки администратора, которые могут переопределить пользовательские файлы.

Если выбирается не та модель или endpoint, не удаляйте файлы наугад. Найдите все активные источники и сравните:

• верхнее поле model;
• provider.bettertoken.options.baseURL;
• ключи моделей в provider.bettertoken.models;
• значения OPENCODE_CONFIG и OPENCODE_CONFIG_CONTENT в текущем терминале.

После изменения провайдера перезапустите OpenCode.

OpenCode Astra: модель или Astra Linux?

Запрос «OpenCode Astra» может означать две разные вещи.

GPT-6 Astra в OpenCode

Если речь о модели OpenAI, используйте точный API ID gpt-6-astra. С конфигурацией BetterToken выше выбирается:

bettertoken/gpt-6-astra

Откройте список моделей в OpenCode:

/models

Если модели нет, проверьте provider ID, объект models, группу доступа BetterToken и актуальный каталог. Не пытайтесь угадывать Model ID по отображаемому названию.

OpenCode на Astra Linux

Документация OpenCode описывает способы установки на Linux, но не даёт отдельного обещания совместимости именно с Astra Linux. Рассматривайте Astra Linux как Linux-среду и проверяйте конкретную машину и версию дистрибутива.

Проверьте архитектуру и необходимые инструменты:

uname -m
command -v curl
command -v bash

Отдельно тестируйте доступ к установщику и к API. Рабочий API моделей не означает, что также доступны скрипт установки OpenCode, npm Registry, GitHub и сервер обновлений.

Стандартная настройка прокси:

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 обязателен, потому что TUI общается с локальным HTTP-сервером OpenCode. Если отправить loopback-трафик через прокси, возможен цикл маршрутизации, зависание интерфейса или ошибка подключения.

Если организация использует собственный центр сертификации:

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

Не записывайте настоящие логины и пароли прокси в общие shell-скрипты. Используйте защищённые переменные или корпоративное хранилище секретов.

OpenCode Grok auth: прямой xAI или gateway?

Прямое подключение к xAI

Выполните:

/connect

Выберите xAI. В актуальной документации OpenCode описаны два пути:

• поддерживаемая подписка xAI через device-code OAuth;
• ручной ввод API Key из xAI Console.

После авторизации выполните:

/models

и выберите доступную модель Grok.

Grok через BetterToken или другой gateway

Custom gateway подходит только тогда, когда он действительно предоставляет актуальную модель Grok и нужный протокол. Не придумывайте ID Grok и не считайте, что каждый OpenAI-compatible gateway автоматически содержит модели xAI.

Сначала проверьте live-каталог. Если Grok там нет, используйте официальный провайдер xAI в OpenCode. Community-плагины для Grok auth — отдельный путь; до установки оцените поддержку проекта, запрашиваемые разрешения и способ хранения credential.

Что такое OpenCode Go auth

OpenCode Go — не универсальная команда для авторизации любых провайдеров, а отдельная подписка OpenCode.

Порядок подключения:

1. Выполните /connect.
2. Выберите OpenCode Go.
3. Откройте https://opencode.ai/auth.
4. Войдите, при необходимости настройте оплату и скопируйте созданный ключ.
5. Вставьте ключ обратно в OpenCode.
6. Выполните /models и выберите модель, входящую в план.

Используйте этот процесс только для OpenCode Go. Для BetterToken provider ID и ключ остаются в секции bettertoken.

Пароль OpenCode Web: используйте переменную окружения

По запросу opencode web password иногда встречается неофициальный совет использовать параметр -p. В текущей официальной документации пароль задаётся через OPENCODE_SERVER_PASSWORD.

В macOS или Linux:

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

Чтобы также изменить имя пользователя:

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

В PowerShell:

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

По умолчанию username — opencode. Для локальной работы только на 127.0.0.1 пароль можно оценивать по ситуации, но при сетевом доступе защита обязательна. Не привязывайте сервис к 0.0.0.0 и не публикуйте его через tunnel до настройки авторизации и сетевых ограничений.

Web-пароль защищает сервер OpenCode, но не спасёт аккаунт провайдера, если API Key утечёт в другом месте.

Проверка первого запроса

После изменения JSON перезапустите OpenCode:

opencode

Откройте выбор модели:

/models

Выберите bettertoken/gpt-6-astra и отправьте короткий, легко проверяемый запрос:

Верни только этот JSON и не изменяй файлы: {"tool":"opencode","sum":4}

Настройка считается подтверждённой, если:

• OpenCode вернул корректный JSON;
• файлы проекта не изменились;
• выбрана модель bettertoken/gpt-6-astra;
• соответствующий запрос появился в Dashboard BetterToken;
• модель, статус, input tokens, output tokens и списание выглядят ожидаемо.

Если ответ есть, но запроса в BetterToken нет, вероятно, конфигурация с более высоким приоритетом отправила трафик другому провайдеру.

Устранение ошибок

401 или ошибка credential

• Повторите /connect с provider ID bettertoken.
• Выполните opencode auth list.
• При использовании {env:BETTERTOKEN_API_KEY} проверяйте только наличие переменной, не выводя сам секрет.
• Убедитесь, что ключ активен и имеет достаточный баланс или разрешения.

404 или неправильный API path

Base URL BetterToken должен быть:

https://www.bettertoken.ai/v1

Не добавляйте /chat/completions вручную.

model not found

Проверьте точный текущий ID в каталоге моделей. Верхнее поле model и ключ в models должны указывать на нужные provider и model.

Используется другой endpoint или модель

Проверьте глобальную, custom, проектную, inline и managed-конфигурацию. Затем перезапустите OpenCode и снова выберите модель через /models.

OpenCode зависает с включённым прокси

Убедитесь, что loopback-адреса исключены:

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Web отвечает Unauthorized

Проверьте имя пользователя и пароль в браузере. Убедитесь, что в shell не осталось старое значение OPENCODE_SERVER_PASSWORD и что клиентский процесс не унаследовал другой пароль.

opencode: command not found

Откройте терминал заново, проверьте PATH и каталог глобальных бинарных файлов пакетного менеджера. Не устанавливайте OpenCode сразу несколькими менеджерами, пока не выясните, какой executable запускается.

FAQ

Как задать API Key в OpenCode?

Рекомендуемый интерактивный способ — /connect. Для custom provider выберите Other, введите provider ID и вставьте ключ. Сам provider и модели всё равно нужно описать в opencode.json или opencode.jsonc.

Файл называется opencode.json или opencode.jsonc?

OpenCode поддерживает оба формата. JSONC удобен для комментариев. Не держите несколько конкурирующих проектных конфигураций, если не понимаете правила их объединения.

Где OpenCode хранит API Key?

Credential, добавленные через /connect, находятся в ~/.local/share/opencode/auth.json. Не публикуйте, не синхронизируйте и не коммитьте этот файл.

Можно ли записать API Key прямо в конфигурацию?

OpenCode поддерживает options.apiKey, но настоящий секрет в отслеживаемом Git JSON-файле опасен. Предпочтительнее /connect, {env:VARIABLE_NAME} или {file:path/to/secret}.

OpenCode Go auth и авторизация провайдера — одно и то же?

Нет. OpenCode Go — отдельный сервис OpenCode. Ключи BetterToken, xAI и других провайдеров независимы.

Как задать пароль OpenCode Web?

Перед opencode web установите OPENCODE_SERVER_PASSWORD. Официальный способ использует переменную окружения, а не универсальный параметр -p.

Как авторизовать Grok в OpenCode?

Выполните /connect, выберите xAI и используйте поддерживаемый OAuth подписки либо ручной ввод API Key xAI. Gateway подходит только тогда, когда в его каталоге действительно есть Grok.

«OpenCode Astra» — это GPT-6 Astra или Astra Linux?

Возможны оба значения. Для модели используется gpt-6-astra; для Astra Linux нужно пройти Linux-установку и сетевые проверки на конкретной версии системы.

Нужен ли VPN для OpenCode в России?

Единого ответа нет: установщик, GitHub, npm, сайт OpenCode и API моделей — разные сетевые маршруты. Проверяйте их отдельно и при необходимости используйте разрешённую корпоративную или региональную сетевую конфигурацию.

Официальные источники

• Введение и установка OpenCode
• Провайдеры и custom provider в OpenCode
• Конфигурация, JSONC, приоритет и переменные
• Сеть и прокси OpenCode
• Авторизация OpenCode Web
• Авторизация OpenCode Server
• Настройка OpenCode с BetterToken