You have a task that needs half an hour of waiting, an investigation with three independent questions, a flow you repeat every Friday, a company tool the agent should read from: Codex offers four mechanisms, one per problem. Codex Cloud runs a task in a remote environment with its own workspace and carries on even when your computer is off; it costs configuration, forces you to send the code elsewhere and is not available with an API key alone. Subagents launch several agents in parallel from the same session: they speed up reading investigations, consume more tokens and do not resolve write conflicts on their own. Skills package repeatable instructions. MCP connects the agent to external tools, and every MCP server is third-party code entering your workflow. The common rule of thumb: delegate what you can verify afterwards, keep by hand what you cannot undo.
Part seven of the OpenAI Codex series, with the documentation opened on 13 November 2026. You need the permissions of part 3 and the AGENTS.md rules of part 4. I have not tried the four mechanisms on Codex: the scripts run without an agent and check the shape of configuration files. I am not affiliated with OpenAI.
Codex Cloud: work that does not occupy your laptop
Each task has its own workspace and can continue while your computer sleeps; you review the results from the web, from the phone or from the desktop app. You start it by choosing "Work in" and then "Cloud" on the web or in the desktop app; from the terminal there is codex cloud, which opens a picker, while codex cloud exec submits a task directly and codex cloud list lists recent chats (with --json for scripts).
Environments
If the default environment appears you can start without choosing a repository, for example to have a script written and tried on sample data; if the task needs existing code, you indicate which repository to clone. To reuse a configuration you create an environment: you choose the repositories (GitHub, and GitLab.com through the selector of a reusable environment), Codex inspects the project, installs dependencies and tools and tries the flow, you review the report and publish; tasks start from the published environment. The configuration records an install script and a "start skill" that starts the services. The saved state of a task remains recoverable for up to seven days after the last turn and, the page warns, does not replace version control: whatever you need must be committed.
Network, secrets, known limits
Internet access is chosen between fully open and restricted to the domains you allow (there is a preset for package managers such as npm, PyPI, crates.io or Maven). For services that require credentials there are two different tools. An environment variable reaches the programs of the environment directly. A network secret is a credential for a specific HTTPS service: you set key, value and allowed domains, the programs receive a placeholder and the proxy substitutes the real value only toward those domains, on port 443, without putting the credential in a process or in a local file. Mind the detail: saving a network secret adds its domains to the restricted internet access. Every allowed domain is a possible exit channel and every saved secret is a credential that lives outside your machine: give the environment least-privilege credentials, read-only if the task is an investigation.
On limits, the page lists the default resources of each virtual machine: 2 vCPU, 8 GiB of memory and 8 GiB of disk for Plus, 4 vCPU, 16 GiB and 32 GiB for Pro, Business and Enterprise. It declares computer use and self-managed GitHub Enterprise Server as not yet supported. A private network is reached with a VPN, and today Tailscale is the only supported provider. Skills saved in the repository are available in cloud tasks, the personal ones on your computer are not synchronized. How much quota you consume the Pricing page says only in part: cloud tasks can use more than local messages.
When the cloud is worth it, and when it is not
- Worth it: long, independent tasks (a mechanical migration, a set of tests to write, an investigation into a bug), several tasks in parallel, work to start from the phone, results that come back as changes to review or as pull requests.
- Not worth it: tasks that depend on your local environment (a database on the laptop, hardware, data that cannot leave), exploratory work where you want to correct course every minute.
- Not available: with an API key alone. The Pricing table indicates that cloud features are not part of key-based access.
The trade-off is that of every delegation: you gain waiting time and lose the ability to stop the agent halfway with a word. You compensate with well-bounded tasks and a criterion of "done" written in the prompt (part 2). The criterion that ties the three items together is reversibility: the cloud is fine for what comes back to you as a change to review.
Subagents: parallelism of reading, not of writing
A subagent is a delegated agent that Codex starts for a specific task; Codex runs them in parallel and gathers their results into one answer. You do not "launch" them from a file: you ask for them in the prompt, or AGENTS.md and skills make them be requested, and Codex handles starting, waiting and closing the threads. A good prompt says how to split the work, whether to wait for all of them and what to return.
An example with this structure: "Spawn three agents: the first lists where the function calcolaSconto is used, the second looks for the tests that cover it, the third for the documentation that mentions it. Wait for all and summarize in a table". Three independent investigations, no writing, one summary. The opposite, three agents modifying the same module, is a recipe for a conflict: the documentation recommends starting from reading work (exploration, tests, triage, summary) and being more cautious with parallel writing. The reason is context: exploration notes, test logs and stack traces in the main chat make it less reliable, and subagents return summaries in place of the raw output.
Custom agents
The built-in ones are default, worker and explorer. Each custom agent is a TOML file: personal ones in ~/.codex/agents/, project ones in .codex/agents/. The file must define name, description and developer_instructions; it can set model and model_reasoning_effort and turn off capabilities (for example features.shell_tool). An agent with the same name as a built-in one, such as explorer, takes precedence. The global values live under [agents]: enabled (it is true if you do not write it), max_concurrent_threads_per_session (a cap on open threads, excluding the main one; if missing, Codex decides), default_subagent_model and default_subagent_reasoning_effort.
The line that matters for security is another one, and it is worth reading carefully: subagents inherit the sandbox and approvals of the main turn, including those changed with /permissions or --yolo, and an agent file cannot override sandbox_mode, approval_policy, model_provider or mcp_servers. An agent's instructions can ask it not to modify files, but the page specifies that they do not create a separate read-only sandbox. So a "read-only explorer" is so by instruction, not by permission: if you want the guarantee, you give it to the session that launches it (part 3). In non-interactive flows, an action that requires a new approval fails and the error travels up to the parent flow.
The following script checks with tomllib the shape of an agent and of an [mcp_servers] table. Required fields, non-overridable keys and the list of MCP keys are a copy of the Subagents and Configuration Reference pages of 13 November, to be updated if they change. The first agent is inspired by the "PR review" example in the documentation; the second is deliberately wrong (the description is missing, it tries to force sandbox_mode); the configuration contains a typo (enabled_tool) and an entry present in two lists.
# Shape check of a custom agent and of an [mcp_servers] table
# against what the Subagents and Configuration Reference pages declare (13 November 2026).
import tomllib
REQUIRED = {"name", "description", "developer_instructions"}
NOT_OVERRIDABLE = {"sandbox_mode", "approval_policy", "model_provider", "mcp_servers"}
MCP_KEYS = {
"command", "args", "env", "env_vars", "cwd", "url", "auth", "bearer_token_env_var",
"http_headers", "env_http_headers", "http_headers_helper", "environment_id",
"startup_timeout_sec", "tool_timeout_sec", "enabled", "required", "startup_readiness",
"enabled_tools", "disabled_tools", "default_tools_approval_mode", "tools",
}
def agent(label, text):
cfg = tomllib.loads(text)
for key in sorted(REQUIRED - cfg.keys()):
print(f"{label}: {key} is missing")
for key in sorted(NOT_OVERRIDABLE & cfg.keys()):
print(f"{label}: {key} in the agent file has no effect (the parent's value applies)")
if REQUIRED <= cfg.keys() and not (NOT_OVERRIDABLE & cfg.keys()):
print(f"{label}: ok")
def mcp_server(label, text):
for sid, table in tomllib.loads(text)["mcp_servers"].items():
unknown = sorted(table.keys() - MCP_KEYS)
if "command" not in table and "url" not in table:
print(f"{label}/{sid}: needs command (stdio) or url (HTTP)")
if unknown:
print(f"{label}/{sid}: undocumented keys: {', '.join(unknown)}")
both = set(table.get("enabled_tools", [])) & set(table.get("disabled_tools", []))
if both:
print(f"{label}/{sid}: {', '.join(sorted(both))} in enabled_tools and disabled_tools: disabled_tools wins")
if not unknown and ("command" in table or "url" in table):
print(f"{label}/{sid}: ok")
agent("explorer", '''
name = "pr_explorer"
description = "Explores the code read-only and gathers evidence."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Do not modify files. Cite files and symbols.
"""
''')
agent("sly", '''
name = "fast"
sandbox_mode = "danger-full-access"
developer_instructions = "Do everything."
''')
mcp_server("config", '''
[mcp_servers.docs]
url = "https://mcp.example.invalid/mcp"
required = true
enabled_tool = ["search"]
[mcp_servers.browser]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"
''')
# Output:
# explorer: ok
# sly: description is missing
# sly: sandbox_mode in the agent file has no effect (the parent's value applies)
# config/docs: undocumented keys: enabled_tool
# config/browser: screenshot in enabled_tools and disabled_tools: disabled_tools wins
# config/browser: ok
The first lines of the output show the healthy case and the sly one: an agent file that writes sandbox_mode = "danger-full-access" gets nothing, and the script says so instead of letting you believe the opposite. The last ones show the most insidious error of a TOML file, the misspelled key: Codex does not recognize it as the intended one, and you believe you have limited the tools. The script also flags screenshot, present in both lists, because disabled_tools wins and this is rarely intended. It is a check of shape: it does not prove that Codex accepts the file.
The cost: each subagent does its own model and tool work, so a run with subagents uses more tokens than a single-agent one. For models the guide suggests gpt-6-luna for fast, bounded scans and gpt-6.1-sol for demanding work; if you choose an explicit model, effort starts at high for Luna and at low for Astra (cost comparison in part 5).
Skills and plugins: instructions you can call up
A skill, according to the documentation, packages instructions and resources for a specific task or workflow. Concretely it is a folder with a SKILL.md file, which must contain name and description, plus optional folders for scripts, references and resources. Codex can choose one by itself when the request matches the description, or you call it with $ (or with /skills); in ChatGPT you use @. To create one: $skill-creator, or by hand. Skills follow the open agent skills standard. A plugin is an installable package that can include skills, MCP servers and lifecycle hooks of the Codex runtime, and ChatGPT and Codex share the same plugin directory.
For repositories, Codex looks for the .agents/skills folder in every directory from the folder where you launch Codex up to the root; then there are the user's skills in $HOME/.agents/skills, the administrative ones in /etc/codex/skills and the system ones included in the product. If two skills have the same name Codex does not merge them: both appear. The documentation also describes "progressive disclosure": Codex starts from the name and description of each skill, and loads the full SKILL.md only when it decides to use it. The initial list has a budget, at most 2% of the model's context window (8,000 characters if the window is unknown), and if there are many skills Codex shortens the descriptions first.
The following script builds a small test repository in a temporary folder, with two skills at the root and in the subproject, and applies those rules: it searches from the working folder upward, reads the frontmatter and compares the length of the initial entry with that of the full file. It mirrors the rules of the page, it is not Codex's code, and it shows what the text alone does not convey: the weight is in the body, the choice is in the description. Names, descriptions and folders are in Italian, as in the Italian edition, because their length enters the character counts (prepara-release is "prepare release", audit-pagamenti "payments audit", servizi/pagamenti "services/payments").
# Shows how the skills of a repository are found and why the description matters.
# Mirrors the rules of the "Build skills" page (13 November 2026): it is not Codex's code.
import os
import tempfile
CHAR_BUDGET = 8000 # initial list when the context window is unknown
def frontmatter(text):
lines = text.split("\n")
assert lines[0] == "---", "frontmatter missing"
end = lines.index("---", 1)
fields = dict(r.split(": ", 1) for r in lines[1:end] if ": " in r)
return fields, "\n".join(lines[end + 1:])
def write_skill(root, folder, name, description, body):
d = os.path.join(root, folder, ".agents", "skills", name)
os.makedirs(d)
with open(os.path.join(d, "SKILL.md"), "w", encoding="utf-8") as f:
f.write(f"---\nname: {name}\ndescription: {description}\n---\n{body}\n")
def find(root, cwd):
"""Looks for .agents/skills from cwd up to the repository root."""
found, current = [], cwd
while True:
base = os.path.join(current, ".agents", "skills")
if os.path.isdir(base):
for name in sorted(os.listdir(base)):
found.append(os.path.join(base, name, "SKILL.md"))
if current == root:
return found
current = os.path.dirname(current)
# Names, descriptions, folders and bodies are in Italian on purpose: their length
# enters the character counts printed below.
with tempfile.TemporaryDirectory() as root:
write_skill(root, ".", "prepara-release", "Prepara una release: changelog, versione, tag. Non usarla per hotfix.",
"Passi:\n" + "\n".join(f"{i}. passo {i} della release" for i in range(1, 41)))
write_skill(root, "servizi/pagamenti", "audit-pagamenti", "Controlla un modulo di pagamento contro la checklist interna.",
"Apri la checklist e confronta ogni voce con il modulo.")
write_skill(root, "servizi/pagamenti", "prepara-release", "Release del solo servizio pagamenti.",
"Stessa procedura, ma con il tag del servizio.")
cwd = os.path.join(root, "servizi", "pagamenti")
initial_total = 0
for path in find(root, cwd):
with open(path, encoding="utf-8") as f:
text = f.read()
fields, body = frontmatter(text)
entry = f"{fields['name']}: {fields['description']} ({os.path.relpath(path, root)})"
initial_total += len(entry)
print(f"{os.path.relpath(path, root):52s} list {len(entry):3d} characters, full {len(text):4d}")
print(f"initial list total: {initial_total} characters on a budget of {CHAR_BUDGET}")
names = [frontmatter(open(p, encoding='utf-8').read())[0]['name'] for p in find(root, cwd)]
print("repeated names (not merged):", sorted({n for n in names if names.count(n) > 1}))
# Output:
# servizi/pagamenti/.agents/skills/audit-pagamenti/SKILL.md list 138 characters, full 160
# servizi/pagamenti/.agents/skills/prepara-release/SKILL.md list 113 characters, full 126
# .agents/skills/prepara-release/SKILL.md list 128 characters, full 1182
# initial list total: 379 characters on a budget of 8000
# repeated names (not merged): ['prepara-release']
In the output the root skill weighs 128 characters in the initial list and 1,182 in the full file: the fixed cost of every installed skill is its description, the variable one the body, paid only when needed. This is why the guide recommends short descriptions, with purpose and boundaries up front: the implicit choice depends on those words. The two prepara-release are not merged and both appear, so do not reuse the same name between root and subfolder.
For the rule that always applies you need AGENTS.md (part 4); the skill is for the on-demand flow. When is it worth the effort? When a task repeats at least three times with the same pattern and the same traps, like "prepare the release": this is my own criterion, not the source's. An old skill that describes a changed procedure is worse than no skill.
MCP: other people's tools, in your flow
An MCP server describes the available tools and handles the requests: searching a ticket, reading documentation. The CLI has codex mcp to add, list and authenticate servers; the commands are below, not run. The configuration lives in config.toml (~/.codex/config.toml, or the project's .codex/config.toml, but only for projects you trust) in [mcp_servers.<name>] tables. The first comment in the block is in Italian, as in the Italian edition: the block is a pattern to adapt and is not run.
# schema da adattare, non eseguito: richiede Codex installato
codex mcp add context7 -- npx -y @upstash/context7-mcp # server locale (stdio)
codex mcp list # server configurati
codex cloud list --json # chat cloud recenti, per script
The keys that matter for risk are few. For a local (stdio) server you need command, for a remote one url. required = true makes startup fail if the server is not ready (and, as seen in part 6, makes codex exec exit with an error). enabled_tools and disabled_tools are a list of allowed and one of forbidden tools, with the second applied after the first. default_tools_approval_mode accepts auto, prompt, writes and approve, and writes asks for confirmation for tools not marked as read-only. The default timeouts are 10 seconds for startup (startup_timeout_sec) and 60 for each call (tool_timeout_sec). A misspelled key produces no error in your editor: the lint of the previous section serves this purpose too.
The risks are three, and they are my own reasoning, not documentation pages: a local MCP server runs on your machine with your permissions, so install only from sources you would vet like a dependency; its output is untrusted context, because a ticket or a page read through a tool can contain hostile instructions, and the security guide of the GitHub Action lists pull request bodies and commit messages among the sources of prompt injection; a token with too many privileges given to an MCP server becomes the agent's privilege. Every server also adds context to every message, and the Pricing page recommends turning off the ones you do not need. For content that arrives from another system the Python SDK offers ExternalMessage, which Codex treats as tool output with lower priority than user and developer instructions: a mitigation, not a guarantee.
A reasonable adoption sequence
- For the first two weeks, only the local CLI and
AGENTS.md(parts 2 and 4). - Then subagents for reading investigations: high gain, low risk.
- Then a skill for your most repeated task.
- Only then an MCP server, one at a time, with least-privilege tokens.
- The cloud last, when you have a bounded task and an environment with the minimum of credentials.
The order here matters, and it is by increasing exposure: each step adds something that goes beyond the perimeter of the previous step, first more work (subagents), then more instructions (skills), then third-party code and data (MCP), finally your codebase on a remote machine (cloud). It is a sequence that I propose, not the source.
Frequently asked questions
Does Codex Cloud work with an API key alone?
No. The price table indicates that with an API key you use the CLI, the SDK and the IDE extension but not the cloud features, such as review on GitHub or Slack. The cloud requires signing in with a ChatGPT account on a plan that includes it.
Can subagents have broader permissions than the main agent?
No. They inherit the sandbox and approvals of the main turn and an agent file cannot override sandbox_mode, approval_policy, model_provider or mcp_servers. The instructions "do not modify files" do not create a separate read-only sandbox.
What is not demonstrated here
I have not tried any of the four mechanisms on Codex. The two scripts check the shape of test files and mirror the rules of the documentation, not the real behavior of the product. I do not know how much quota the cloud and subagents consume compared with an equivalent local session: for subagents the source says only that they use more tokens, for the cloud that they can use more than local messages. I have not verified how a concrete MCP server behaves, nor the syntax of plugins and their manifest.
Sources
- Codex Cloud - starting tasks, default environment, consulted on 2026-11-13
- Cloud environments - environments, network, network secrets, VPN, machine resources, known limits, skills in cloud tasks, consulted on 2026-11-13
- Subagents - built-in agents, TOML files,
[agents]keys, inheritance of sandbox and approvals, cost, consulted on 2026-11-13 - Build skills - structure of a skill, search paths, progressive disclosure, budget of the initial list, consulted on 2026-11-13
- Skills and plugins - difference between skills and plugins, the
$mention, shared directory, consulted on 2026-11-13 - Model Context Protocol -
[mcp_servers]tables, keys, defaults,codex mcp, consulted on 2026-11-13 - Configuration Reference - list of the
mcp_serversandagentskeys, consulted on 2026-11-13 - Developer commands -
codex cloudandcodex mcp, consulted on 2026-11-13 - Pricing - cloud features excluded with an API key alone, cloud consumption, effect of MCP servers on quota, consulted on 2026-11-13
- Codex SDK - the
ExternalMessagetype of the Python SDK, consulted on 2026-11-13 - openai/codex-action, docs/security.md - the sources of prompt injection in a pull request flow, consulted on 2026-11-13
The pages were downloaded in full and read at the passages cited. The two scripts were run with Python 3.14 (python3 -I), twice each, with identical output, without Codex and without network.
← Part 6: codex exec and the SDK Part 8: the honest comparison →
Commenti
Caricamento commenti...
Sign in to comment