# Run OpenAI Codex as an Agno agent with CodexAgent

> Agno's CodexAgent wraps the openai-codex SDK, runs on its own or behind AgentOS, and streams each Codex shell command, file edit and MCP call as an Agno tool event.

- Published: 2026-10-08
- Author: Kaustubh Shukla
- Categories: Changelog
- Canonical: https://www.agno.com/blog/run-openai-codex-as-an-agno-agent-with-codexagent
- Markdown: https://www.agno.com/blog/run-openai-codex-as-an-agno-agent-with-codexagent.md

Agno's `CodexAgent`, imported from `agno.agents.codex`, wraps the official `openai-codex` Python SDK, which bundles the Codex CLI and starts it locally as an app-server subprocess. Codex keeps running its own loop of shell commands, file edits, web search and MCP calls, and Agno adds sessions, streaming, the AgentOS API and the UI around it. It joins the Claude Agent SDK, LangGraph, DSPy and Antigravity adapters.

Install the SDK and authenticate once.

```bash
pip install openai-codex
codex login
```

Then use it like any Agno agent.

```python
from agno.agents.codex import CodexAgent
from agno.db.sqlite import SqliteDb

agent = CodexAgent(
    name="Codex Coder",
    model="gpt-5.6-luna",
    sandbox="workspace-write",
    approval_mode="deny_all",
    reasoning_effort="high",
    cwd=".",
    db=SqliteDb(db_file="tmp/codex.db"),
)

agent.print_response("Summarize this repository", stream=True, session_id="repo-tour")
```

To put the same agent behind an API, hand it to AgentOS. It streams over SSE at `/agents/codex-coder/runs` and shows up in the AgentOS UI next to your native agents.

```python
from agno.os import AgentOS

agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="codex_app:app", reload=True)
```

![How CodexAgent turns Codex app-server notifications into Agno run events. Streamed answer text becomes RunContentEvent content and reasoning text becomes reasoning_content. When Codex starts a shell command, file change, MCP call or web search, Agno emits a ToolCallStartedEvent named shell, apply_patch, mcp__server__tool or web_search, and the completed item becomes a ToolCallCompletedEvent carrying the output, exit code, diff or results. A failed turn, or an error Codex will not retry, ends the run with a RunErrorEvent. Each Agno session maps to one Codex thread, saved in session_data codex_thread_id when a db is set.](https://www.agno.com/images/v3-1-2-codex-event-mapping.png)

Every Agno `session_id` gets one Codex thread. With a `db`, CodexAgent saves the thread id on the Agno session, so the second message in `repo-tour` resumes the same thread even after a restart. Without a `db`, the link lives in memory for as long as the agent object does. When a thread can't be resumed, for example with `ephemeral=True` or after Codex deleted its session files, CodexAgent starts a fresh thread and puts the stored chat history at the top of the prompt.

The constructor maps straight onto Codex settings. `sandbox` takes `read-only`, `workspace-write` or `full-access`, and `approval_mode` takes `auto_review` or `deny_all`. Use `deny_all` on a server, since nobody is there to answer a permission request. `output_schema` holds Codex's final answer to a JSON Schema and returns it as a JSON string, and `config` passes Codex config overrides to every thread, such as an `mcp_servers` table. CodexAgent checks these values when a run opens its thread, and a bad one fails that run.

```text
# real output: CodexAgent(sandbox="yolo").run("hi")
status: RunStatus.error
content: Unknown sandbox 'yolo'. Expected one of: read-only, workspace-write, full-access
```

See the [cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/frameworks/codex/codex_agentos.py), and learn more about [running Codex](https://docs.agno.com/agent-os/multi-framework/codex) in the documentation.