Setting up OceanToken as a provider

OceanToken's API is OpenAI-compatible at https://api.oceantoken.ai/v1 (chat completions, responses, images, videos, audio, embeddings), and Claude models also answer the Anthropic Messages API at https://api.oceantoken.ai. Auth is Authorization: Bearer sk-....

Only change configuration when the user asked for this setup. Before writing any file (agent config, settings, .env), show the exact change and get a yes; never write a key anywhere without that confirmation.

The key

1. The user creates a key at https://app.oceantoken.ai/ui/?page=api-keys (a credit limit per key is a good idea for agents).
2. Store it as an environment variable, never in a repository file: export OCEANTOKEN_API_KEY=sk-... in the shell profile, or a .env that is listed in .gitignore.
3. Check it: curl -s https://api.oceantoken.ai/v1/models -H "Authorization: Bearer $OCEANTOKEN_API_KEY" | head -c 300.

Codex on OceanToken

Add a provider and a profile to ~/.codex/config.toml so the user's default setup stays untouched and OceanToken is one flag away. Pick the model with search_models (type chat, capability tools); OpenAI GPT-5 family models are the safe choice for Codex.

[model_providers.oceantoken]
name = "OceanToken"
base_url = "https://api.oceantoken.ai/v1"
env_key = "OCEANTOKEN_API_KEY"
wire_api = "responses"

[profiles.oceantoken]
model_provider = "oceantoken"
model = "openai/gpt-5.5"

Run with codex --profile oceantoken, and verify with codex exec --profile oceantoken "Reply with the single word OK". Show the user the diff of config.toml before saving, and back the file up first.

Claude Code on OceanToken

Claude Code talks the Anthropic Messages API, which OceanToken serves for its Claude models. For one project, put this in .claude/settings.local.json (git-ignored); for every project, in ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.oceantoken.ai",
    "ANTHROPIC_AUTH_TOKEN": "<the user's OceanToken key>",
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
  }
}

Use model ids exactly as search_models returns them. Verify with claude -p "Reply with the single word OK". Settings files hold the key in plain text: prefer the project-local file, keep it out of git, and tell the user where it is.

An application calling OceanToken

OpenAI SDKs need only the base URL and key:

import os
from openai import OpenAI
client = OpenAI(base_url="https://api.oceantoken.ai/v1", api_key=os.environ["OCEANTOKEN_API_KEY"])
client.chat.completions.create(model="openai/gpt-5-mini", messages=[{"role": "user", "content": "Hi"}])

Anthropic SDKs: Anthropic(base_url="https://api.oceantoken.ai", api_key=...) with a Claude model id. Read the key from the environment; never hard-code it.

Errors