Codex admin automation: a safe setup guide for IT admins

What Codex is, and where it runs

According to the Codex documentation, Codex starts from a goal or task and can gather context, take action and produce output. It is offered in the ChatGPT desktop and mobile apps, ChatGPT on the web, the Codex CLI, the Codex IDE extension and Codex Cloud. The documentation also describes GitHub integration, a GitHub Action, a non-interactive mode (codex exec) and an SDK. Several pages now use the name "ChatGPT Work" next to Codex, and the pricing page says the two share usage.

For admin automation the useful surfaces are the CLI (scriptable), the desktop app (local scheduled tasks), the cloud (tasks that do not depend on your laptop) and the GitHub Action (runs inside CI). The IDE extension is mainly for interactive work, and the plugins page says plugins are not available in it.

Project instruction files: AGENTS.md

Codex reads AGENTS.md files before it starts work. According to the AGENTS.md page:

• A global file lives in the Codex home directory (~/.codex unless CODEX_HOME is set). AGENTS.override.md there takes priority over AGENTS.md.
• In a project, Codex walks from the project root down to the current directory and includes at most one file per directory, checking AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames.
• Files are concatenated from the root downward, so files closer to the working directory come later and override earlier guidance.
• The combined limit is 32 KiB by default (project_doc_max_bytes). The instruction chain is built once per run or per TUI session, so restart Codex after editing.

For admin work, use this file for facts the agent cannot guess: which tenants and subscriptions are in scope, which commands are read-only, what must never be run, where results go. The page gives no general rules on what to put in these files, so the suggestions in the setup section are ours, not a vendor recommendation. An instruction file is guidance, not enforcement. The hooks page says tool hooks are "not a complete enforcement boundary", so enforce hard limits in the sandbox, in the permissions of the account the agent uses, and in review.

Sandbox and approval modes

The approvals and security page defines the controls you will use most:

• Sandbox modes: read-only, workspace-write (the default "Auto" preset, together with on-request approvals) and danger-full-access, which the documentation marks as not recommended. Its CLI alias is --dangerously-bypass-approvals-and-sandbox (--yolo).
• Approval policy values: on-request, never, a granular form that keeps chosen categories interactive and auto-rejects the rest, and untrusted, which is retired. approvals_reviewer can be user (default) or auto_review.
• Network access is off by default. You can enable it for workspace-write with network_access = true and narrow it with a network proxy domain list, where deny overrides allow.
• In workspace-write, .git, .agents, .codex and .aws stay read-only even though they sit in a writable root.
• For CI, the page gives --sandbox read-only --ask-for-approval never as the example of a limited unattended run.

Subagents inherit the parent's sandbox and approval settings. A custom agent file cannot override sandbox_mode, approval_policy or mcp_servers, and asking an agent in prose to avoid edits does not create a read-only sandbox.

Integrations: MCP, plugins, skills and hooks

MCP. Servers are defined in ~/.codex/config.toml, or in .codex/config.toml for trusted projects, under [mcp_servers.<name>]. The documentation covers local STDIO servers and streamable HTTP servers with OAuth or a bearer token read from an environment variable, the codex mcp add, list and login commands, and per-server enabled_tools and disabled_tools. default_tools_approval_mode can be auto, prompt, writes or approve, with per-tool overrides, and writes prompts for tools not marked read-only. Prefer prompt or writes for anything that can change state, and pass secrets through environment variables rather than prompts or repository files.

Plugins. The plugins page says a plugin bundles skills, MCP servers, browser extensions and hooks. It does not use the word "connectors"; the MCP servers inside a plugin are the part that connects to services such as GitHub or Slack. Workspace admins can manage company-managed app accounts and import a GitHub marketplace for their team. The page says plugin hooks should be reviewed and trusted before they run, and that Codex sandbox and approval policies apply to plugin capabilities that run through a Codex host.

Skills. A skill is a directory with a required SKILL.md (with name and description) and optional scripts/, references/ and assets/. Codex discovers skills in the repository (.agents/skills), the user's home, /etc/codex/skills for admins and a bundled system set. The documentation recommends instructions over scripts unless you need deterministic behaviour. A repeatable read-only runbook, such as checking certificate expiry across a listed set of hosts, is a good fit.

Hooks. Events include PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, SessionStart and SessionEnd. A PreToolUse hook can deny a call. Hooks are configured in hooks.json or config.toml, in enabled plugins or in admin-managed requirements.toml, and non-managed hooks must be reviewed and trusted. The page lists limits: hosted tools such as WebSearch are not covered, and hooks are not a complete enforcement boundary.

Subagents. Custom agents are TOML files in ~/.codex/agents/ or .codex/agents/. The page recommends read-heavy parallel work first because parallel writes can conflict, and notes that subagents use more tokens.

Automation: CLI, scheduled tasks, cloud and GitHub

Non-interactive CLI. codex exec "<task>" prints progress to stderr and the final message to stdout. The default sandbox is read-only. --json gives a JSON Lines event stream (thread.started, turn.completed, item.*, error and others), --output-schema requires the final answer to match a JSON Schema, -o writes the last message to a file, and codex exec resume continues a session. For CI, the documentation says to authenticate with CODEX_API_KEY, and not to set OPENAI_API_KEY or CODEX_API_KEY as a job-level variable in workflows that run repository-controlled code.

Scheduled tasks. According to the automations page, tasks run unattended with your default sandbox settings. Time-based schedules support custom controls or an RFC 5545 RRULE. In the desktop app a task can work in a local project or an isolated worktree, but the computer must be on and the app running. Web (cloud) tasks cannot work in a folder on your computer. Event triggers (Gmail, Slack, GitHub) are web and mobile only on eligible plans, and a task cannot combine event triggers with a time schedule. Tasks use approval_policy = "never" when organisation policy allows it, otherwise they fall back to the selected permission mode. In read-only mode, calls that modify files or use the network fail. The CLI and IDE extension do not provide the Scheduled management view.

Cloud environments. Each cloud task gets its own isolated workspace from a published environment, with an install script and a start skill. The documentation describes full public internet as an option you turn on, with a narrower "Package managers" preset and an additional-domains list. It distinguishes plain environment variables from "network secrets" that the proxy substitutes for allowed HTTPS destinations, and offers OIDC for short-lived cloud credentials. It also lists unsupported items, including GitLab and self-hosted GitHub Enterprise Server, and some Azure services for OIDC. The security page says the Codex Cloud (Legacy) agent phase runs offline by default, while the environments page does not state a default, so check what your workspace shows.

GitHub Action. openai/codex-action@v1 runs codex exec in a job. Inputs include sandbox, safety-strategy (default drop-sudo), allow-users and allow-bots, and by default only users with write access can trigger it. The documentation advises least-privilege job permissions, sanitising untrusted pull request, commit and issue text because of prompt injection, and not using the unsafe strategy on multi-tenant runners. Runners must be Linux or macOS unless unsafe is used.

Set up a safe automated workflow, step by step

1. Pick one read-only job. Examples: a weekly report of stale accounts from an export, or a summary of failed backup jobs. Do not start with changes.
2. Create a dedicated identity. Give the agent its own service identity with read-only roles, not an admin's session. See the AI agent identity and least privilege guide.
3. Write AGENTS.md. State scope (tenants, subscriptions, hosts), allowed commands, forbidden actions, the output format and where results go. Keep it short, because the 32 KiB limit is shared by every file in the chain.
4. Start in read-only. Keep network access off. If a job needs an API, add only that domain through the proxy list, and only then.
5. Connect tools with MCP, narrowly. Use enabled_tools to list exactly what is needed and set the approval mode to prompt or writes.
6. Make output structured. Use --output-schema and --json so a script, not a person reading prose, decides what happens next.
7. Add a hook or wrapper that logs every tool call before you widen anything (see the next section).
8. Run it by hand several times, then schedule it. Review the first runs in the Scheduled view or the job output.
9. Add change actions last, and keep a human approval step. For PowerShell, see human approval before AI-generated PowerShell runs.
10. Never put secrets in prompts or AGENTS.md. Use environment variables, network secrets or OIDC as the documentation describes, and rotate a key if it may have been exposed.

What to log

Aim for a record that answers who asked, which tool ran, against what, with which approval, and what happened. The documentation gives you these sources:

• codex exec --json event streams, -o output files and CI job logs for unattended runs.
• Hooks: PreToolUse and PostToolUse can write a line per tool call. The documentation names SessionEnd, PreModelRequest, PostModelRequest and Interrupt as advisory events that suit logging. Because hooks are not a complete boundary and skip some hosted tools, treat the hook log as evidence, not proof of completeness.
• For Enterprise workspaces, the Compliance API page describes an append-only compliance log stream with conversation_message and codex_log event types. It warns that local OpenTelemetry events do not establish a complete record of every local command, file operation or approval. Retention periods and plan requirements are not stated on that page.

Record at least a correlation ID, the identity used, the tool and redacted arguments, the approval decision, start and end time, exit status and the output location. Test a few sample entries with the free AI agent audit log checker, and read AI agent audit trail for the field list. Mask secrets before logs leave the host.

Cost model

The pricing page says ChatGPT Work and Codex are included in ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise plans and share usage. Message limits depend on the model and the size and complexity of the task, cloud tasks can use more allowance than local messages, and credits can be used after included limits are reached. For automation in shared environments such as CI, the page describes an API key option for the CLI, SDK or IDE extension, charged at API rates and not covering cloud features. It also notes model retirement dates that affect scheduled tasks on retired models. This guide quotes no prices; take them from the pricing page on the day you decide.

To model your own cost, count runs per week, allow for retries and subagents, and set a cap: fewer tools, a narrower prompt, a smaller model where the job allows it, and a hard stop for failures.