Setting up OpenAI
GPT models from OpenAI, with an API key and prepaid credits.
On this page
OpenAI makes the GPT models. This guide covers getting an OpenAI API key, adding credit, and connecting it to Aldwin.
What OpenAI is#
OpenAI's API gives you its GPT models, billed per use. It is separate from a ChatGPT subscription: a ChatGPT plan does not include API use, and API keys are made on the developer platform.
When Aldwin uses OpenAI, your prompts and the files Aldwin reads for you go to OpenAI over the internet. If you want everything to stay on your computer, use Ollama or LM Studio instead.
What you need#
- An OpenAI developer account and API key
- Credit on the account (the API is prepaid)
- Aldwin installed (
uv tool install aldwin)
You buy credits up front and each request uses some. See OpenAI pricing.
Get a key#
- Sign in at the OpenAI platform.
- Open API keys and create a new secret key.
- Copy the key now; OpenAI shows it only once. Treat it like a password.
- Add credit under Billing if you haven't already.
Connect Aldwin#
In the web app#
- Open Settings from the bottom of the sidebar and choose Models.
- Find OpenAI under Providers and select Add key.
- Paste your key and select Connect. Aldwin checks the key with OpenAI before saving it. If it does not work, Aldwin says why and saves nothing.
- Under Model in use, pick a OpenAI model. You can also switch models from the message box in any chat.
Setting up Aldwin for the first time? On the Connect a model page, pick Paste an API key, choose OpenAI, and paste the key.
To change or remove the key later, use Replace key or Disconnect on the same row.
In the terminal#
- Start Aldwin and type
/model. - Pick Add a provider… and press
Enter. It lists the cloud providers that don't have a key yet. - Pick OpenAI, then paste your key at
OpenAI API key:(the input is hidden) and pressEnter. - Aldwin checks the key with OpenAI before saving it. When it works you see
✓ Saved key for OpenAI.If not, Aldwin says why and saves nothing. - OpenAI now appears under Available providers. Pick it, then pick a model. You see
✓ Switched to <model> (OpenAI).
Aldwin's key check lists your models, which works even with no credit left. If the key connects but every message fails with a rate limit, add credit.
On first launch, aldwin offers the same choice: choose to use a cloud provider, pick OpenAI, and paste the key. You can rerun this any time with aldwin setup.
Choosing a model#
The list in /model shows OpenAI's current chat models first; type /model all to see every model your key can use. Newer GPT models all use tools. A smaller, cheaper model (names ending in mini, nano or luna) is fine for everyday tasks.
To switch straight to a model by name, type /model openai/<model-name>.
Update or remove the key#
Type /model, choose Manage keys…, and pick OpenAI. Update key checks and saves a new key. Disconnect removes the saved key; switch to another model first if OpenAI runs the current one.
Other ways to add the key#
These skip the check, so use them only if you prefer files or environment variables.
Secrets file. Add this line to ~/.aldwin/secrets.yaml (create the file if it does not exist, and keep any lines already in it):
openai_api_key: your-key-hereEnvironment variable, for one terminal session or in your shell profile (~/.zshrc or ~/.bashrc):
export OPENAI_API_KEY=your-key-hereAn environment variable wins over a saved key.
Try it#
aldwinAsk something that uses a tool:
List the files in this folder.
You should see a list_dir step and then the answer. The status line at the bottom shows your model and OpenAI.
Privacy notes#
- OpenAI does not use API data to train its models unless you opt in. It may keep requests for up to 30 days to check for abuse. See Your data.
- Aldwin keeps the key only in
~/.aldwin/secrets.yaml(or your environment), and removes it from any error message it shows. - Details: Privacy.
Troubleshooting#
Messages from /model appear right after you paste a key. Messages during a chat appear after ✗ in place of an answer.
| What Aldwin says | Fix |
|---|---|
Your OpenAI key was rejected. Check the key and try again. | The key is wrong, revoked, or was pasted with extra characters. Copy it again from OpenAI. |
Could not reach OpenAI to verify the key. | Check your internet connection and try again. If it keeps happening, the account may be blocked or out of credit; check it on the provider's site. |
OpenAI runs the current model. Switch to another model first. | You can't disconnect the provider you are using. Switch model with /model, then disconnect OpenAI. |
OpenAI's key comes from OPENAI_API_KEY in your environment. ... | Disconnect can't remove an environment variable. Delete the export OPENAI_API_KEY=... line from your shell profile, then restart Aldwin. |
Your OpenAI key was rejected. Run `aldwin setup` to replace it. | The key stopped working after it was saved. Run /model, choose Manage keys…, pick OpenAI, and choose Update key. |
OpenAI rate limit reached. Wait a moment and try again. | Either too many requests at once, or the account is out of credit: OpenAI reports both the same way. Wait a minute; if it keeps happening, add credit under Billing. |
Can't reach OpenAI. ... | Check your internet connection, or switch to a local model with /model. |
Model ... isn't available to your key. ... | Your account can't use that model. Pick another with /model. |
This conversation is too long for ... Start a fresh one with /new. | Type /new. Your saved memory notes stay. |