Skip to main content
OpenAI is the GPT provider package: Chat Completions for complete and stream, with loader-owned retries and heuristic token estimates for countTokens.

Why

Use OpenAI when you need GPT-family models in the same app as Claude or Gemini. Enable the openai block in tools.ai and route with model ids such as gpt-4o — no separate client enum like mailer.

Setup

  1. Confirm apps/backend/package.json includes "tooling-ai-openai": "workspace:*".
  2. Run make deps-install after dependency changes.
  3. Add openai under tools.ai in apps/backend/src/configuration/development.ts:
You can combine this with anthropic and google blocks in the same tools.ai object — see AI tooling overview.
  1. No compose.yml changes are required for OpenAI.
  2. Add to .env.development:
  1. Verify:

Local observability

OpenAI requests surface through Refract’s ai logger feature and ai.request.* metrics, not the OpenAI dashboard from this stack. Check backend logs for tokenEstimate: true on count operations.

Adding a new model id

  1. Add the model id to tools.ai.openai.models in environment config.
  2. Update defaultModel if it should become the OpenAI default when params.model is omitted and OpenAI is the primary provider.
  3. Expose the id to callers only after it appears in getAvailableModels output.
  4. Run make test module=tooling-ai-openai.

Gotchas

  • countTokens ignores the chat tokenizer API — estimates use joined message length ÷ 4; do not use for production billing without replacing the adapter.
  • Unknown params.model values throw AiValidationError before OpenAI is called.
  • Streaming chunks may report zero usage until the final yield; instrumentation picks up usage from the last chunk that includes token counts.

What’s next?