Buffaly Logo
Browse docs Menu

Start here

Docs home Install Buffaly Install on Windows Install on Linux Install on Mac Quickstart How-to library

Learn Buffaly

What Buffaly is User guide Core concepts Coming from other agents Memory and skills

Build and extend

Add a prompt skill Add a ProtoScript skill Add a C# DLL tool Add a model provider Skills, services, and tools ProtoScript services

Operate

Sessions and long-running work Session anatomy Plan, Scratch, and Tasks Session artifacts Session timeline Compaction

Reference

Ontology and ProtoScript Providers and authentication Web modules and UI Diagnostics & recovery Safety rules Secrets handling SmartPatch
How-to

Use OpenAI credentials

Configure ChatGPT, OpenAI API, Codex backend, and Buffaly secret paths without mixing account types or exposing credential values.

Quick answer

There are several OpenAI-related credential paths in Buffaly, and they are not interchangeable. Start by identifying the selected provider transport before deciding which credential path matters.

What you haveWhat it is forBuffaly route to check
ChatGPT account/subscription loginAccount-based access used by Codex backend/profile flows when configured.Codex Auth Feature plus Codex Backend Feature
OpenAI API keyConventional API-key access for OpenAI API-backed features.OpenAI Feature / ApiKey and settings UI key controls
Codex backend token/profileBuffaly-managed or legacy Codex auth profile material.Codex auth/profile settings and backend route
Buffaly secretProtected value stored by Buffaly for tools, services, or providers.Secret store or DB-backed feature settings; never prompt text

If the selected provider transport is openai plus codex_backend, start with Codex auth/profile and backend settings. If the selected route is a conventional OpenAI API-key route, configure the OpenAI API key and do not confuse it with ChatGPT/Codex profile login.

What Buffaly means by OpenAI credentials

ChatGPT account or subscription

An account login that may matter for Codex backend authentication. A subscription is not itself an API key, and passwords, cookies, or receipts should never be pasted into prompts.

OpenAI API key

OpenAIFeature loads an ApiKey from the DB-backed OpenAI Feature row. Settings controls can save, delete, and show status without revealing the value.

Codex backend credentials

CodexAuthFeature and CodexBackendFeature manage profile/auth mode, token paths, backend URL, endpoint path, default model, timeouts, and backend behavior.

Before you configure anything

  1. Decide which route is in use: openai plus codex_backend, openai plus responses_api, or a provider-native module.
  2. Check the provider catalog for provider, transport, model, and reasoning availability.
  3. Keep API keys, OAuth tokens, passwords, and browser cookies out of prompts, markdown files, wiki articles, and source files.
  4. Use the settings UI, configured feature rows, or typed secret storage for credential material.
  5. Verify with status flags, masked hints, active account labels, provider rows, and smoke-test results without printing secrets.

Configure an OpenAI API key

Use this path when the feature you are using needs a conventional OpenAI API key.

  1. Open the Buffaly settings UI for the target installation.
  2. Find the OpenAI API key section.
  3. Save the API key through the settings UI or configured secret path.
  4. Confirm the UI shows key status without revealing the key.
  5. Verify the OpenAI API-backed feature with a small safe test.
Verified source details: OpenAIFeature.CreateFromSettings() loads the OpenAI Feature row; BuffalyAgentSettingsService.SaveOpenAiKey(...) persists the key; DeleteOpenAiKey(...) clears it. Do not commit the key to git or store it in prompt skills, markdown, .pts, implementation code, or provider manifests.

Configure Codex backend / ChatGPT-style credentials

Use this path when the selected OpenAI transport is codex_backend. Do not treat an OpenAI API key as a replacement for Codex profile/OAuth/backend credentials unless the selected route source says so.

  • Check Codex auth/profile status and auth mode, including buffaly_profiles or legacy_codex_file.
  • For profiles, use the settings UI profile/browser login flow when available.
  • For legacy token files, verify the configured token path exists for the target installation.
  • Confirm backend enabled state, base URL, endpoint path, default model, token file path, timeout, and user agent.
BaseUrl:      https://chatgpt.com/backend-api
EndpointPath: codex/responses
DefaultModel: gpt-5.5
UserAgent:    BuffalyCodexBackend/1.0

Configure provider, model, and reasoning selection

OpenAI credentials only solve authentication. The session still needs a valid provider/model tuple backed by the provider catalog.

  1. Use the provider/model/reasoning selector when available.
  2. Select only provider, transport, model, and reasoning values that appear in the catalog.
  3. For API verification, inspect ProviderCatalogService.GetProviderCatalog and ProviderCatalogService.GetProviderSelection(sessionKey).
  4. Use SetProviderSelection only with catalog-backed values.
Reply with exactly: openai credential smoke ok

ProviderCatalogService validates provider, transport, model, and reasoning together. Invalid tuples should fail explicitly instead of silently switching credentials or models.

How to ask Buffaly to help

Good requests name the desired operation but do not include secret values in ordinary chat unless the active UI path is explicitly collecting a secret.

Help me verify whether this Buffaly instance is using OpenAI API-key auth or Codex backend auth. Inspect the provider catalog, selected transport, OpenAI Feature, Codex Auth Feature, and Codex Backend Feature. Do not print any secret values.
Store my OpenAI API key using the configured Buffaly settings/secret path. Do not echo it, write it to docs, remember it as normal memory, or commit it.
Diagnose why OpenAI completion fails for this session. Check the selected provider/transport/model/reasoning tuple, Codex auth/profile status, OpenAI API-key status, provider catalog errors, and logs. Report only non-secret evidence.

Verification checklist

  • The provider catalog includes openai.
  • The selected transport is intended: codex_backend or responses_api.
  • The selected model appears under that transport and the reasoning level is supported or omitted.
  • OpenAI API-key status is present for API-key routes; Codex auth/profile/account status is healthy for codex_backend.
  • Codex Backend Feature points at the expected backend URL, endpoint path, and default model for the target instance.
  • A safe completion prompt succeeds and logs contain no auth, missing-key, provider catalog, provider selection, or unsupported-model errors.

Common failures

ChatGPT Plus is not enough

A ChatGPT subscription is not an OpenAI API key. Configure the OpenAI key path or Codex auth path depending on the selected route.

API key saved, Codex still fails

codex_backend uses Codex auth/profile and backend settings. Check auth mode, token/root paths, backend URL, endpoint path, and logs.

Model selection fails

Provider selection is catalog-driven. Verify the model exists for the selected transport and the reasoning level is declared by that model.

A secret was pasted

Move it into the configured settings/secret path, avoid repeating it, and do not commit prompts, transcripts, or markdown containing the value.

Next

Providers and authentication Add a model provider Add or remove provider models Secrets handling Buffaly user guide Use Codex with Buffaly