API Keys & Provider Configuration

OpenGame is an agentic framework — it talks to several external generative-AI APIs to actually build a game. OpenGame does not ship with any default credentials. You have to supply your own keys for each capability you want to use.

There are four configurable modalities, each with an independent provider:

The main agent LLM (the brain that drives the conversation loop) is not part of this system; it uses the upstream qwen-code OpenAI-compatible flow. Configure it via OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL, or the interactive /auth command.

Supported provider families

Note. openai-compat is intentionally not wired up for video, because there is no stable OpenAI-shaped public video API today (Sora and Veo are not part of that surface). If you select it for OPENGAME_VIDEO_PROVIDER you’ll get a clear error.

Configuring with environment variables (recommended)

Each modality reads four environment variables:

OPENGAME_<MODALITY>_PROVIDER   # tongyi | doubao | openai-compat
OPENGAME_<MODALITY>_API_KEY    # Bearer token sent to the provider
OPENGAME_<MODALITY>_BASE_URL   # required for openai-compat; optional override otherwise
OPENGAME_<MODALITY>_MODEL      # required for openai-compat; optional override otherwise

Where <MODALITY> is one of REASONING, IMAGE, VIDEO, AUDIO.

Example: everything on Aliyun DashScope

export OPENGAME_REASONING_PROVIDER=tongyi
export OPENGAME_REASONING_API_KEY=sk-aliyun-key
export OPENGAME_REASONING_MODEL=deepseek-v3.2
 
export OPENGAME_IMAGE_PROVIDER=tongyi
export OPENGAME_IMAGE_API_KEY=sk-aliyun-key
export OPENGAME_IMAGE_MODEL=wan2.5-t2i-preview
 
export OPENGAME_VIDEO_PROVIDER=tongyi
export OPENGAME_VIDEO_API_KEY=sk-aliyun-key
export OPENGAME_VIDEO_MODEL=wan2.5-i2v-preview
 
export OPENGAME_AUDIO_PROVIDER=tongyi
export OPENGAME_AUDIO_API_KEY=sk-aliyun-key
export OPENGAME_AUDIO_MODEL=qwen-plus

Example: mix-and-match (OpenAI for reasoning, Doubao for image+video)

export OPENGAME_REASONING_PROVIDER=openai-compat
export OPENGAME_REASONING_API_KEY=sk-openai-key
export OPENGAME_REASONING_BASE_URL=https://api.openai.com/v1
export OPENGAME_REASONING_MODEL=gpt-4o-mini
 
export OPENGAME_IMAGE_PROVIDER=doubao
export OPENGAME_IMAGE_API_KEY=volc-key
export OPENGAME_IMAGE_MODEL=doubao-seedream-4-0-250828
 
export OPENGAME_VIDEO_PROVIDER=doubao
export OPENGAME_VIDEO_API_KEY=volc-key
export OPENGAME_VIDEO_MODEL=doubao-seedance-1-0-pro-250528
 
# Reuse OpenAI for ABC generation
export OPENGAME_AUDIO_PROVIDER=openai-compat
export OPENGAME_AUDIO_API_KEY=sk-openai-key
export OPENGAME_AUDIO_BASE_URL=https://api.openai.com/v1
export OPENGAME_AUDIO_MODEL=gpt-4o-mini

Example: an OpenAI-compatible image proxy (e.g. fal.ai)

export OPENGAME_IMAGE_PROVIDER=openai-compat
export OPENGAME_IMAGE_API_KEY=$FAL_KEY
export OPENGAME_IMAGE_BASE_URL=https://fal.run/openai/v1
export OPENGAME_IMAGE_MODEL=fal-ai/flux/dev

A copy-paste template for all variables lives at the repository root in .env.example.

Configuring via ~/.qwen/settings.json

The same fields can be persisted to your settings file. Environment variables take precedence, so settings.json is the right place for “default” choices that you can override on a per-shell basis.

{
  "openGame": {
    "providers": {
      "reasoning": {
        "provider": "openai-compat",
        "apiKey": "sk-openai-key",
        "baseUrl": "https://api.openai.com/v1",
        "model": "gpt-4o-mini"
      },
      "image": {
        "provider": "tongyi",
        "apiKey": "sk-aliyun-key",
        "model": "wan2.5-t2i-preview"
      },
      "video": {
        "provider": "doubao",
        "apiKey": "volc-key",
        "model": "doubao-seedance-1-0-pro-250528"
      },
      "audio": {
        "provider": "openai-compat",
        "apiKey": "sk-openai-key",
        "baseUrl": "https://api.openai.com/v1",
        "model": "gpt-4o-mini"
      }
    }
  }
}

When both an env var and a settings.json field are set for the same modality, the env var wins.

Resolution rules in detail

For each modality, OpenGame walks this list and uses the first non-empty value it finds:

1. OPENGAME_<MOD>_PROVIDER env var.
2. openGame.providers.<mod>.provider from settings.json.
3. If a legacy DashScope-style key is set (DASHSCOPE_API_KEY, IMAGE_MODEL_API_KEY, REASONING_MODEL_API_KEY, …), the provider is inferred to be tongyi so existing demos keep working.
4. Otherwise, OpenGame raises MissingProviderConfigError with a message that names the exact env var or settings field you should set.

The same precedence chain applies independently to _API_KEY, _BASE_URL, and _MODEL.

What if I haven’t configured anything?

The CLI will start fine and the agent will respond as usual. You’ll only see an error when the agent actually invokes one of the asset / GDD / classifier tools. The error is human-readable and tells you exactly which env var or settings field to set, e.g.:

OpenGame is missing API configuration for the "image" modality.

Set OPENGAME_IMAGE_PROVIDER to one of "tongyi", "doubao", or "openai-compat",
or add an "openGame.providers.image.provider" entry to your settings.json.

See docs/users/configuration/api-keys.md for the full list of supported variables.

Legacy environment variables

For backward compatibility with pre-OpenGame setups, the following older variables are still read as fallbacks. New configurations should prefer the OPENGAME_* names above.

These may be removed in a future major version.