Skip to main content
Codex CLI is OpenAI’s terminal coding agent. Like Claude Code, it has a shell — so the cleanest way to manage Kataven is to install the Python SDK and let Codex write the calls itself. No MCP server required for this path. If you want to drive Kataven from chat-only ChatGPT (Desktop or Web), see Manage with ChatGPT — that uses MCP.

​
1. Mint an API key

hub.kataven.ai/settings → API Keys tab → Create API key. Suggested name: codex-local. Copy the sk_live_… value — it shows once.

​
2. Install the SDK

Node also works (npm install @kataven/server) if you’d rather Codex write TypeScript.

​
3. Set the env var Codex will inherit

Add it to ~/.zshrc / ~/.bashrc so every Codex session has it. The SDK reads the env var automatically — Codex doesn’t need to know the value.
KATAVEN_ACCOUNT_ID is not required when KATAVEN_API_KEY starts with sk_live_ — the account is in the prefix.

​
4. Launch Codex and ask

Then type:
List all my agents and tell me which ones are pinned to a phone number. Then create a new “Sales SDR” agent with a friendly tone and attach the general-faqs playbook.
Codex reads the Python SDK overview, writes the script, runs it, and reports back.

​
Prompts that work well

  • “Show me every agent and its current model. If any are still on gpt-3.5, upgrade them to gpt-4o-mini.”
  • “I just uploaded a CSV of leads at ~/leads.csv. Create an outbound campaign called ‘Spring Q2 push’ targeting them. Pause it immediately so I can review before going live.”
  • “Take the prompt from agent front-desk-v1 and clone it into front-desk-v2-experimental. Don’t attach any tools yet.”
  • “Place a test call from my main number to my cell using the Front Desk agent, then show me the live transcript link.”

​
Verify what Codex did

​
Why no MCP for Codex?

Codex can spawn processes (python -c "…", write & run files). Anything the SDK can do, Codex can do directly. MCP is only useful when the AI tool cannot spawn processes — Claude Desktop, ChatGPT Desktop, n8n nodes, etc.

​
Sandbox / approval mode

We strongly recommend running Codex with default approval prompts on for write operations. Reads (agents.list, campaigns.list) are safe to auto-approve; mutations (agents.create, campaigns.start, calls.originate) should require a click. Codex’s --full-auto mode will happily place outbound calls without asking — only enable it on a disposable account.

​
Troubleshooting

401 Unauthorized — KATAVEN_API_KEY isn’t set in the shell Codex is using. Run echo $KATAVEN_API_KEY from inside Codex before retrying. “Account not found” — you’re using a Zitadel JWT instead of an sk_live_ key, and KATAVEN_ACCOUNT_ID isn’t set. Easier path: mint an sk_live_ key (step 1). 403 Forbidden on POST /api/v1/api-keys or admin endpoints — sk_live_ keys can’t manage other keys, mint integrations, or set cost caps. Those routes require a Hub UI session. 429 Too Many Requests — per-tenant cost cap exceeded. View limits at hub.kataven.ai/settings → Limits tab.

​
What’s next