OpenAI integration

Ahena works with your OpenAI account: it checks your key and that your configured model is available and not about to be shut down, and generates an adapter behind the common ahena.ai interface using the Responses API. Your app calls OpenAI directly. Ahena is never in the inference path.

Live verifiedLive verified: key validation, model discovery and DoctorFull OpenAI docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at OpenAI.

Whether the key is accepted, and whether it's project-scoped.
The models the key can see (ahena inspect openai), and your configured model with its shutdown date.

Nothing to configure

OpenAI has nothing to plan or apply. Ahena gives you Doctor, model discovery and a generated adapter behind the common ahena.ai interface, so each environment can use a different AI provider. See AI providers.

Generated code: src/ahena/ai/providers/openai.ts behind ahena.ai.generate(), on the official openai SDK; ahena.ai.raw is the client.

How Ahena verifies

There's nothing to read back: Ahena changes nothing in your account, so there's no plan, apply or VERIFIED state. Doctor runs read-only checks and records PASS, INFO, WARNING or FAIL findings.

Checks use only the free model-list endpoints. Ahena never runs a completion on your account.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the OpenAI docs.

Check	What it means
`openai.key`	Key accepted.
`openai.key_kind`	Not a project-scoped key (INFO).
`openai.model`	Model available; WARNING more than 30 days before its shutdown date, FAIL within 30 days or after.

More on findings, health and continuous checks: Doctor.

Approvals

There's nothing to approve: connecting, Doctor, ahena inspect and ahena generate change nothing in your OpenAI account. Generated code is written to your repository, where you review it like any other change.

Manual steps

Ahena can't do these for you:

Create a project and a project key in the OpenAI platform.
Set a usage limit for the project.
Set OPENAI_API_KEY (and AI_PROVIDER=openai if several adapters exist) where your app runs.

Credentials and permissions

Name	Secret	Notes
`OPENAI_API_KEY`	Yes	Use a project key (`sk-proj-…`). User keys get an INFO note.

Least privilege

Ahena only lists and reads models: a project key with Models: Read is enough.
Give your app its own key with the permissions it needs, ideally in a separate project with a budget.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, then generate. There's no plan or apply step for an AI provider.

OPENAI_API_KEY=sk-proj-… ahena connect openai -e production

Connect a project key.

```
ahena doctor -e production
```
Check the key and the configured model.
```
ahena inspect openai -e production
```
List the models this key can see.
```
ahena generate -e production
```
Write the ahena.ai adapter for this environment's provider.

Verification status

Live verified

Live verified: key validation, model discovery and Doctor

Verified against the real provider API for the capabilities listed. Its other capabilities are validated by Ahena's automated provider contract and conformance tests.

How OpenAI is tested

Verified against the real OpenAI API, read-only, on 2026-10-04, using only the Models API with a restricted service-account key (Models: Read).
Covered: key validation with a valid and a deliberately wrong key, model discovery, retrieving the configured model, Doctor and disconnect. No completion was sent: the test harness refuses every non-GET request.
The generated adapter is typechecked against the openai SDK, not run.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

The common interface covers text generation. Tools, structured outputs, streaming and images use ahena.ai.raw, which is OpenAI-specific.
Usage limits and billing are managed in OpenAI.
There's no drift tracking for AI providers.

Disconnecting

ahena disconnect openai removes the stored key (revoke it in the OpenAI platform); nothing in your OpenAI account is changed.