> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Kataven with Codex CLI — voice AI from OpenAI's terminal agent

> Use OpenAI's Codex CLI to build voice agents, run outbound campaigns, and manage telephony. Install the Python SDK and let Codex write the code itself — no MCP needed.

[Codex CLI](https://github.com/openai/codex) 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](/guides/manage-with-chatgpt) — that uses MCP.

## 1. Mint an API key

[hub.kataven.ai/settings](https://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

```bash theme={null}
pip install kataven
```

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

## 3. Set the env var Codex will inherit

```bash theme={null}
export KATAVEN_API_KEY="sk_live_acme_..."
```

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.

<Note>
  `KATAVEN_ACCOUNT_ID` is **not** required when `KATAVEN_API_KEY` starts with `sk_live_` — the account is in the prefix.
</Note>

## 4. Launch Codex and ask

```bash theme={null}
codex
```

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](/sdks/python/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

| What changed             | Check it at                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Agents                   | [hub.kataven.ai/agents](https://hub.kataven.ai/agents)                                                     |
| Prompts, playbooks, FAQs | [hub.kataven.ai/knowledge](https://hub.kataven.ai/knowledge)                                               |
| Phone numbers            | [hub.kataven.ai/phone-numbers](https://hub.kataven.ai/phone-numbers)                                       |
| Live or recent calls     | [hub.kataven.ai/conversations](https://hub.kataven.ai/conversations)                                       |
| Campaign progress        | [hub.kataven.ai/campaigns](https://hub.kataven.ai/campaigns)                                               |
| Tools, integrations      | [hub.kataven.ai/tools](https://hub.kataven.ai/tools), [hub.kataven.ai/store](https://hub.kataven.ai/store) |

## 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](https://hub.kataven.ai/settings) → **Limits** tab.

## What's next

* [Manage with ChatGPT](/guides/manage-with-chatgpt) — the MCP path for chat-only ChatGPT.
* [Manage with Claude Code](/guides/manage-with-claude-code) — the same flow with Anthropic's terminal agent.
* [Python SDK reference](/sdks/python/overview) — what Codex reads when it figures out what's possible.