OpenAI Codex CLI: First Task and Team Settings

Use the first 15 minutes as a setup timebox, assuming you already have a working project and an account with access. Installation, sign-in or a slow test suite can take longer. A useful first result is a small verified change, or a precise explanation of what blocks it. Commands and configuration checked against OpenAI’s documentation on October 27, 2026.

Install Codex CLI and Finish One Useful Task

Codex works inside your project: it can inspect files, edit them and run tools installed on your machine. Think of it as a contributor at a separate workbench. You supply the task and boundaries; you still decide whether the result belongs in the product. OpenAI’s CLI guide

Minutes 0 to 3: Choose One Install Method

On macOS or Linux, the standalone install and update command is:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Use an alternative if it fits your existing setup. Pick one method so you know how to update it later.

For Windows, install or update with this exact command in a new PowerShell window: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex".

These are the install routes in the current CLI documentation and official repository. Open your project directory in the terminal before starting Codex. Check codex --version and standardize the team on 0.164.0 for this setup. If you use npm and want the exact verified release, run npm install -g @openai/codex@0.164.0. Stable release

Minutes 3 to 5: Choose ChatGPT Sign-In or an API Key

For a first interactive session, use ChatGPT sign-in if your plan and workspace provide access. Run codex login and complete the browser flow. Starting codex without an existing login also offers Sign in with ChatGPT.

Choose API-key authentication when you intend to use your OpenAI Platform account, such as for programmatic workflows. With OPENAI_API_KEY already supplied in your shell environment, the documented macOS/Linux command is printenv OPENAI_API_KEY | codex login --with-api-key. Keep the key out of repository files.

Run codex login status to confirm which method is active. This matters on a team: ChatGPT authentication follows the ChatGPT workspace’s controls, while API authentication follows the API organization’s controls. Authentication guide

Cost: ChatGPT sign-in uses the access included with your eligible plan; API-key usage is billed separately through OpenAI Platform at API rates. Use our Codex pricing guide for the plan comparison. For a team trial, measure manual task time against prompting, review and correction time, then subtract incremental usage cost from the value of the time actually saved. A faster first draft only pays when the total work to accept it falls. OpenAI authentication and billing distinction

Minutes 5 to 8: Inspect Before Editing

Create a Git checkpoint first. From your project’s shell prompt, start an inspection session with the documented command codex --sandbox read-only --ask-for-approval on-request.

Give it a bounded investigation. For example, adapt this suggested prompt to your project:

This prompt is a workflow suggestion, not a special Codex command. Read the answer and confirm that it has found the right part of the application. The read-only sandbox allows inspection and commands within its boundary; actions outside that boundary can require approval. Approval and sandbox guide

Minutes 8 to 12: Authorize One Small Change

Use /permissions to switch to workspace editing when you are ready. For a new session, the documented combination is codex --sandbox workspace-write --ask-for-approval on-request.

Then give an acceptance condition:

Start with something you can judge quickly. A test of known behavior is a better first assignment than an open-ended request to improve the architecture.

Minutes 12 to 15: Review the Diff and Evidence

Use /diff to inspect the patch and /review to request a review. Check the actual test output, the files touched and whether the change meets your acceptance condition. Commit only after your own review. Those slash commands belong inside the Codex session, not at your shell prompt. CLI command reference

Choose the Model After You Have a Baseline

Since October 26, 2026, GPT-6.1 Terra is selectable in Codex. It needs CLI 0.159.0 or later; 0.164.0, released October 23, is the latest stable version verified on October 27. Upgrade before trying Terra. Codex models, Codex changelog, GitHub release

Keep GPT-6.1 Sol as the shared coding default. OpenAI positions Sol for complex and long-running work, while its selection guide recommends trying Terra for scoped code fixes, concise writing and screen-based tasks. For a small development team, that means keeping Sol for cross-file refactors, ambiguous bugs and multi-step implementation. Try Terra for a narrow fix with a regression test, a documentation edit from supplied material, or a task grounded in a screenshot. OpenAI’s model-selection guidance

Launch a Terra session from your shell with:

codex -m gpt-6.1-terra

Inside an existing session, use /model to choose an available model or reasoning effort. On 0.164.0, /model gpt-6.1-terra --reasoning medium changes the current session without rewriting saved defaults. To launch Sol explicitly, use codex --model gpt-6.1-sol. Model commands, inline selection behavior

Keep the initial task and effort setting consistent when comparing results. More reasoning can help difficult analysis, but also takes longer and uses more tokens. GPT-6 Luna remains an option for focused, repeatable tasks. Record the model alongside the task and test outcome; selecting a model name does not give an account access to it. Codex model guidance

Set Sandbox Access and Approvals Separately

The sandbox defines what commands can access. The approval policy defines when Codex must ask before acting. Think of the sandbox as the workroom walls and the approval policy as the permission to open a door.

Use on-request for interactive work: actions allowed inside the sandbox can proceed, while actions needing broader access can prompt. never means Codex cannot ask for approval; it does not remove the sandbox. A blocked action can remain blocked.

The protected paths inside writable roots include .git, .agents, .codex and, since 0.159.0, .aws. Keep those protections when updating shared defaults. Current protected paths, release history

A write boundary is not a promise to prompt before every edit. With workspace-write and on-request, Codex can change workspace files and run permitted commands automatically. Inspect the active settings with /permissions. OpenAI’s sandbox and approval behavior

If an old team template sets approval_policy = "untrusted", update it: OpenAI has retired that explicit setting and says it can prevent startup. The older codex exec --full-auto flag has been removed; use codex exec --sandbox workspace-write for that non-interactive path. Removal in the changelog, Current migration guidance

Put Working Agreements in AGENTS.md

Use AGENTS.md to stop repeating how your repository works. Codex reads these instructions when a run starts. /init can generate a scaffold, which a maintainer should edit before the team relies on it.

A useful repository file answers four questions:

• How do developers install dependencies and run the project?
• Which tests and checks apply to a change?
• Which directories contain generated files or require special care?
• What should a completion report include, such as changed behavior, tests run and unresolved failures?

Write your real commands and conventions, not a generic wish list. Keep personal preferences in ~/.codex/AGENTS.md; commit shared repository guidance at the project root.

Codex loads global guidance and then walks from the project root toward the current directory. More local instructions take precedence over earlier guidance; AGENTS.override.md wins over AGENTS.md in the same directory. Restart the session after changing instructions, and ask Codex to summarize the guidance it loaded. AGENTS.md discovery rules

Treat this file as a contributor handbook. Use configuration and managed requirements for technical restrictions.

Keep config.toml Small and Reviewable

Store personal defaults in ~/.codex/config.toml. Put shared project defaults in .codex/config.toml, which Codex loads only for trusted projects. These settings use TOML, a text format for named settings.

This starter keeps Sol for the team’s general coding work and uses the values shown in OpenAI’s configuration guide. Use the model line only when that model is available to your account:

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

The CLI’s flags and --config overrides take precedence over project configuration. Trusted project settings take precedence over selected profiles and your user defaults. Organization requirements can constrain what is allowed regardless of those defaults. Configuration basics

web_search = "cached" selects cached web-search results. It is separate from network access for shell commands. A dependency download can need approval even when Codex has a web-search tool. Keep that distinction in the onboarding notes instead of loosening permissions whenever a command fails.

For a team moving from 0.154.0, keep the shared file small and update the onboarding notes around these changes:

• Inspect settings with /config. Added in 0.163.0, it lets you search preferences, change supported settings and see which need a restart. Remove tui.prompt_suggestions from old templates; 0.159.0 removed it. Release history
• Use session controls deliberately. In 0.164.0, /presets can reuse common prompts and slash commands, and /permissions :read-only can select a permission profile inline. Keep shared defaults in the reviewed file. If you adopt default_permissions, replace the legacy sandbox configuration rather than combining it with sandbox_mode or [sandbox_workspace_write]. Release notes, profile command, configuration reference
• Check resumed sessions. The 0.163.0 and 0.164.0 fixes restore saved permissions and model settings. A changed shared default does not mean an older chat adopts it: check /model and /permissions, or start a new session for the team baseline. Explicit overrides and current managed policy still apply. 0.163.0 notes, 0.164.0 notes

Add an MCP Server Only for a Concrete Need

MCP, or Model Context Protocol, connects Codex to tools and external context. A local server runs as a process; a remote server is reached through an HTTP address. Add one when a task needs information or an action your repository cannot provide.

OpenAI’s documentation example is codex mcp add context7 -- npx -y @upstash/context7-mcp. This starts a documentation server through npx, so that launcher must be available. Run codex mcp list to see configured servers, then /mcp inside a session to inspect active connections. For an OAuth-capable server, use codex mcp login <server-name>, replacing the placeholder with its configured name.

Server configuration belongs under [mcp_servers.<server-name>] in the same TOML configuration system. A team can restrict exposed tools with enabled_tools and disabled_tools; the deny list is applied after the allow list. Start with the smallest useful tool set. MCP setup and settings

Since 0.161.0, you can also run /mcp login <name> inside the active session. The 0.164.0 release adds enterprise MCP authentication through eligible Codex account grants or dedicated sign-in; use that only when your workspace and server support it. MCP release changes

For the separate issue of large tool responses, read our Codex CLI MCP output-limits explainer. Connecting a server and controlling how much output it returns are different setup decisions.

Use Worktrees When Tasks Need Separate Checkouts

A Git worktree gives a task a separate checkout of the repository. It is useful when you want to keep an experiment’s edits apart from the files you are actively working on.

OpenAI introduced managed CLI worktrees in 0.154.0, enabled them by default in 0.156.0, and retired the worktrees feature flag in 0.164.0. Remove features.worktrees from old shared templates; its overrides are now ignored. You no longer need codex features enable worktrees. Start a local session with codex --worktree from a trusted Git project. Worktree release history, flag retirement

Inside an idle local session, /worktree offers a fresh chat or continuation of the current conversation in a managed checkout. Browse worktrees shows existing worktrees and their owner chats. Local Git and trust requirements still apply. Current worktree commands

Plan to review and integrate the work yourself, then clean up checkouts you no longer need. The CLI added ownership details and confirmed deletion of clean managed worktrees in 0.155.0. A separate checkout does not replace sandbox settings or merge review. Lifecycle changes

Use our Codex CLI worktree guide when you are ready for parallel tasks. For a first test-writing assignment, a single checkout is enough.

Six Useful Tasks, Ranked for a Small Team

These are suggested assignments, not measured productivity claims. Start where the acceptance condition is easiest to check.

Codex does not supply missing product decisions or prove that a passing test suite covers every risk. Your acceptance criteria and review remain part of the job. For broader evaluation, use our Codex review; for a purchasing comparison, see Codex vs Claude Code.

Two Focused Tools a Technical Founder Could Build

The stronger opportunity is a regression-test service for one stack. Sell a reviewed test patch to small teams with known bugs and weak coverage. The smallest useful version takes a reproducible case, runs a bounded Codex task in a separate checkout and returns the patch plus test evidence. The hard part is reliable fixtures and meaningful assertions; a test that merely repeats the implementation adds little value.

A repository-specific review assistant is the second option. An engineering lead could pay for reviews that apply the team’s documented conventions and return a short, verifiable findings list. Start with one repository, its AGENTS.md and a repeatable review run. The catch is differentiation: Codex already reviews code, so the product must improve relevance and reduce false alarms. Test generation has the clearer initial deliverable because the buyer can inspect and run what you return.

Questions That Come Up During Setup

On Monday, have one maintainer run the same small task with two teammates, record the review and correction effort, and fix the shared instructions where the handoff breaks. Expand only after the team can repeat that loop confidently.

If you want a repository workflow built around these controls, we build AI production systems.