Skip to content

Connect the OpenAI API

Goal

Route the primary Colossus model through the public OpenAI Responses API while keeping the API key outside configuration.

Prerequisites

  • OpenAI API access, API billing, and an API key available to the Colossus process.
  • A schema version 2 configuration generated by colossus config init.
  • An exact model identifier plus its context, output, tool-call, and streaming limits.

OpenAI API access is separate from a ChatGPT subscription. If you intend to use an eligible ChatGPT/Codex plan instead of API billing, follow Codex or ChatGPT subscription.

Steps

1. Inject the API credential

Set OPENAI_API_KEY with your platform's process environment or secret manager before starting Colossus. The YAML below contains only env:OPENAI_API_KEY; do not replace that reference with the secret value.

2. Configure the Responses route

Run colossus -w . config effective, edit the reported resolution.configPath, and keep its required storage block and any intended custom settings. Apply this validated overlay, then replace YOUR_OPENAI_MODEL_ID and the model limits with exact values for the selected model.

schemaVersion: 2
providers:
  profiles:
    openai-provider:
      kind: open_ai_responses
      baseUrl: https://api.openai.com/v1
      credentialReference: env:OPENAI_API_KEY
models:
  profiles:
    openai:
      providerProfile: openai-provider
      model: YOUR_OPENAI_MODEL_ID
      contextWindowTokens: 128000
      maxOutputTokens: 16000
      capabilities:
        toolCalls: true
        streaming: true
  roles:
    primary: openai
sandbox:
  networkDestinations:
    - https://api.openai.com

Colossus appends /responses and /models to the API prefix. Keep /v1 in baseUrl. The shown exact https://api.openai.com sandbox grant applies under an isolating boundary; acknowledged full access needs no duplicate grant, and adding one does not narrow ambient authority. Set model limits and capabilities from the selected model's documentation; Colossus does not infer them from the catalog.

3. Inspect routing and readiness

colossus -w . models route primary
colossus -w . provider doctor openai-provider
colossus -w . provider models openai-provider
colossus -w . models doctor openai

4. Send one bounded model turn

colossus -w . run \
  "Reply with exactly: connected"

Expected result

The primary role resolves to openai, provider and model diagnostics succeed, and the run returns connected.

Verification

Run colossus -w . config show and confirm that the output contains the credential reference but not the API key value. Under isolation, also confirm the exact sandbox origin; under full access, confirm config effective reports ambient network authority.

Failure path

  • Credential unavailable or HTTP 401: confirm OPENAI_API_KEY is present in the environment of the Colossus process, then rerun provider doctor openai-provider.
  • The model is absent or denied: run provider models openai-provider, copy an exact accessible model ID, and rerun models doctor openai.
  • The provider origin is denied under isolation: grant exactly https://api.openai.com in sandbox.networkDestinations; do not put /v1 there.
  • Generation rejects the request: verify the selected model's limits and set toolCalls or streaming to false when that model does not support the contract, then rerun models doctor openai.

Next step

Review exact field semantics in Providers and models, apply deployment guidance from Providers and routing, or continue with First repository task.