Complete Introduction to Codex: Turning AI into an Assistant for Computer-Based Work

This handout was prepared with reference to four Codex teaching videos on YouTube, then corrected against the OpenAI Developers Codex documentation on July 1, 2026. It is designed for an AI Agent workshop. Learners who need to review demonstrations can use the links at the end to watch the original videos. Actual features, UI labels, and usage limits depend on the Codex version and official documentation available when you use it.

1. What Codex Is

Opening Claim

Codex 不是另一個聊天視窗，而是能進入工作區的 AI Agent。Codex is not just another chat window. It is an AI agent that can work inside a project.

它能讀檔、改檔、執行命令、檢查結果，並把成果存回指定 project。也因此，使用者要懂範圍、權限、上下文與驗收。It can read files, edit files, run commands, inspect results, and save outputs back to a project. That means users must understand scope, permissions, context, and review.

Codex is OpenAI's AI coding agent. It does more than answer questions: within an authorized working environment, it can understand a project, read files, edit files, run commands, inspect results, and produce code, documents, spreadsheets, presentation materials, web pages, and other artifacts.

In one sentence, the difference is:

• ChatGPT on the web: primarily a browser-based conversation. You usually upload materials yourself, download results yourself, and organize files yourself.
• Codex: can run locally or through Codex surfaces and work directly inside the project / workspace you specify. Within the boundaries allowed by sandbox and approval settings, it can read files, edit files, run tools, use plugins and skills, and save results back into your project.

A practical analogy: using Codex only as a chatbot means using only a small part of a broader working system. You miss the workflows it is designed to support.

Because Codex may be able to touch your files and tools, you should not give one vague instruction and stop checking the result. To use it reliably, you need to understand project scope, permissions, context, AGENTS.md, skills, plugins, and how to review the output.

2. Levels of AI: From Conversationalist to Agent

For workshop teaching, one useful way to think about AI capability is to divide it into several levels:

This is not an official Codex product classification. It is a workshop framework. In this framework, Codex is closer to an agent than to a normal chatbot because it can use tools in an authorized environment and move from answering to doing.

Codex capabilities can be grouped into six areas:

1. Understanding project context: reading project files, configuration, and existing structure to understand what you are working on.
2. Writing and planning: helping write code, documents, specifications, tests, and implementation plans.
3. Operating local tools: editing files, running commands, and running tests within sandbox and approval boundaries.
4. Checking and correcting: using errors, test results, or rendered UI state to revise its work.
5. Producing work artifacts: creating documents, spreadsheets, slides, images, HTML pages, and reports.
6. Connecting external tools: using Plugins, Apps, MCP, or Computer Use to connect Gmail, Google Drive, Slack, GitHub, browsers, or desktop apps.

3. Getting Started

Download and Sign In

1. Go to the official OpenAI Codex page or the ChatGPT / OpenAI Developers Codex documentation, then install the Codex App, CLI, or IDE extension for your platform.
2. Codex supports two common sign-in methods:
   • Sign in with ChatGPT: use Codex access provided by your subscription plan or workspace. Current official documentation lists Codex across Free, Go, Plus, Pro, Business, Edu, and Enterprise plans, but features, limits, and integrations vary by plan.
   • Sign in with an API key: useful for people familiar with APIs, CLI workflows, automation, or CI environments. API-key usage is billed through OpenAI Platform API pricing, and some ChatGPT workspace or cloud features may not be available.

For stable day-to-day use, Plus or a higher plan is usually more practical because the available usage and features are better suited to longer work sessions. Free is better for exploring quick coding tasks. Features such as image generation may not be available on Free, so always check the official pricing page.

Interface Language

If your version of the Codex App provides language settings, look for the language option in Settings and switch to the language you prefer. UI labels and available languages can change by version, so teaching materials should avoid hard-coding exact button labels. In class, follow the screen you actually see.

4. Interface Tour

You can think of the Codex App in three areas:

• Sidebar: entry points for threads, projects, plugins, skills, automations, settings, and related features. The exact items may differ by version.
• Conversation area: where you give instructions, add background, answer questions, review Codex plans, and inspect results. You can type, and some versions support voice input or dictation.
  • Typing / opens slash commands, such as checking status, entering plan mode, creating an AGENTS.md scaffold, or viewing MCP status. Available commands depend on environment and version.
  • For explicit skill invocation, official docs recommend $skill-name. Plugins and app tools often use @, such as @Browser, @Chrome, or a specific plugin.
  • When attaching files, referencing project content, or invoking tools, follow the composer hints shown in your current app version.
• Results and preview area: where you can inspect diffs, files, terminal output, PDFs, spreadsheets, slides, images, web previews, or other artifacts.

Visual Annotation for Web Pages

When Codex creates a web page or HTML report, you can use the in-app browser to preview local development servers, file-backed previews, or public pages that do not require sign-in. In Annotation mode, you can select an element or area and leave feedback such as “this button overflows on mobile” or “this heading is too large.” Then ask Codex to address the comments, and it can return to the code or files to revise them.

The in-app browser does not support login flows, existing cookies, browser extensions, or your normal browser profile. For signed-in websites, use a regular browser, the Codex Chrome extension, or Computer Use, and treat account security carefully.

Branching and Parallel Experiments

If your version provides branching, forking, background threads, or worktree features, you can test different solutions separately. A reliable pattern is to ask Codex to explain its plan before major changes, then use Git branches, worktrees, or separate threads to isolate A/B approaches and avoid mixing results.

5. Four Fundamentals

Decision Points

四大基本功，是讓 Codex 穩定工作的最低門檻。Four fundamentals are the minimum for reliable Codex work.

ProjectProject

這次工作範圍與主要資料夾。The folder and environment for this work.

PermissionsPermissions

Codex 技術上能碰什麼、何時要問你。What Codex can touch and when it must ask.

ContextContext

它當下能看到的資料、對話、檔案與工具輸出。What it can currently see: messages, files, and tool output.

AGENTS.mdAGENTS.md

專案規則、語氣、禁忌、驗收與交付格式。Project rules, tone, forbidden actions, checks, and delivery format.

An agent that can touch local files and tools requires four fundamentals: project, permissions, context, and AGENTS.md. The examples below use the scenario of preparing a workshop event.

1. Project

Workflow

開始前，先確認這次工作的範圍與位置。Before starting, define where this work lives.

建資料夾Create a folder

把活動說明、名單、素材與過去成果放在同一個 project。Put descriptions, lists, assets, and prior outputs in one project.

講清路徑Name paths

直接給資料夾、檔名或目標檔案，減少猜測。Give folders, filenames, or target files to reduce guessing.

整理結構Organize structure

清楚命名本來就是好習慣，Agent 時代更重要。Clear naming is already good practice; agents make it more important.

保留驗收Keep review

Codex 可以執行，但範圍與結果仍由人確認。Codex can execute, but people still confirm scope and results.

In the Codex App, a project is the folder and environment for the current work. If you start Codex CLI from a folder, or add a project in the App, Codex usually treats that folder as the main working scope.

Start by creating a folder on your computer, such as “Workshop Planning,” and put the event description, registration lists, speaker bios, image assets, and past slide decks inside. This basic step matters: you are not handing your whole computer to AI; you are drawing a clear work area so Codex can focus and reduce the risk of touching unrelated files.

When you want Codex to process a file, do not give only a vague keyword and ask it to search. Give the folder, file name, path, or attach the file using the interface. Clearer context means less searching, fewer wasted tokens, and fewer wrong assumptions.

Context Engineering: organize files into clear folders and give them readable names so anyone can understand the project structure. You should do this even without AI; in the agent era, it matters even more.

2. Permissions

Permissions are critical because they determine how much Codex can do on your computer. Official documentation separates safety controls into two layers:

• Sandbox mode: the technical boundary, such as whether Codex can write inside the workspace, touch files outside it, or let commands access the network.
• Approval policy: when Codex must stop and ask you, such as before leaving the sandbox, using the network, running a high-risk command, or operating an external tool.

A practical way to think about common modes:

Permissions are a double-edged tool: higher permission reduces friction, but mistakes can have bigger impact. A safer approach is to start with read-only or workspace-write, ask Codex to describe the plan, edit scope, and verification steps, and then widen permissions only when the task requires it.

AGENTS.md can say things like “do not delete source files” or “explain the plan before editing,” but it is natural-language guidance, not a hard technical safety boundary. Real safety still depends on sandboxing, approvals, Git, backups, file permissions, and human review.

Advanced safety practices include keeping Git history, backing up important files, working on branches or worktrees, keeping sensitive data out of unnecessary workspaces, and using system-level permissions or managed policies to block the riskiest operations.

3. Context

Context is everything the AI can currently see: your conversation, attached documents, project files, tool output, summaries of past work, and possibly memory. More context can help, but more is not always better. Too much material can blur the focus and consume the model's reasoning space.

Three useful habits:

• Summarize state after each phase: after finishing a registration list or event page, ask Codex to write the current state, output locations, and remaining tasks before opening a new thread or moving to the next phase.
• Watch context usage and rate limits: Codex /status can show the thread ID, context usage, and rate limits. If a long task approaches the limit, ask for a summary before continuing.
• Separate planning from execution: discuss complex requirements in a planning thread, generate a clear plan, then open a new thread to execute that plan. This saves context and makes review easier.

“Compress manually around 80%” can be a practical habit, but it is not an official rule. The point is to avoid waiting until an important task is already near the context limit before organizing it.

4. AGENTS.md

AGENTS.md is Codex's operating guide for a project. Think of it as an onboarding manual. It explains what the project is, who it serves, what tone to use, which files not to touch, what checks to run after edits, and where outputs should go.

Official documentation says Codex reads AGENTS.md before work and builds an instruction chain by scope:

• Global scope: by default under ~/.codex, for personal long-term preferences. If AGENTS.override.md exists, it takes precedence over AGENTS.md.
• Project scope: Codex walks from the project root down to the current working directory and looks for AGENTS.override.md, AGENTS.md, and configured fallback filenames.
• Guidance closer to the current directory appears later and can override broader rules.

Example content:

Please respond in Traditional Chinese.
Do not delete source files; propose a plan before removing content.
Before editing documents, explain what you will change.
Always output registration lists as one Excel file.
When finished, include a summary, output path, and verification method.

A simple way to create one is to ask Codex: “I want to create an AGENTS.md. Please help me by asking questions.” Codex can ask about the project purpose, common tasks, output formats, forbidden actions, and verification commands, then draft the file. You can also let a project mature first, then ask Codex to summarize the workflow into AGENTS.md.

Common pitfall: AGENTS.md should not contain everything. Official documentation mentions size limits for project instructions, and in practice you should not put every SOP inside it. AGENTS.md should contain the minimum background and rules needed every time. Longer workflows are better as Skills loaded only when needed.

Difference between AGENTS.md and Memory:

Memory can reduce repeated questions, but it should not replace team rules. Important rules, test commands, safety requirements, and delivery formats belong in AGENTS.md or project documentation.

One-sentence summary: personal preferences can be helped by Memory, but project rules and high-risk instructions should live in AGENTS.md or formal documentation.

6. Settings

In Settings, pay attention to these areas:

• Personalization / Custom instructions: specify your role, reply preferences, common language, and expected output formats. Official docs also mention Codex App personality settings such as Friendly, Pragmatic, or None; the exact localized label depends on version.
• Memories: Memories may be off by default. You can enable them in settings or config.toml. They store stable preferences, recurring workflows, project conventions, and known pitfalls as future context. Do not store secrets or treat memory as the only rule source.
• Models and reasoning effort: as of July 1, 2026, official Codex models documentation recommends starting most tasks with gpt-5.5; lighter tasks may use gpt-5.4-mini. Model information changes quickly, so class materials should re-check the official models page regularly.
• Speed / Fast mode: official docs say Fast mode can make supported models about 1.5x faster but uses a higher credit rate. For example, GPT-5.5 uses 2.5x the standard rate and GPT-5.4 uses 2x. Use it when time matters; it is not always necessary.
• Sandbox and approvals: do not only ask whether Codex will prompt you. Confirm what the sandbox can touch, whether commands can use the network, and when the approval policy will pause for permission. Network, cross-directory work, or external tools may require extra approvals.
• Usage and billing: Codex usage limits vary by plan, model, mode, and feature. The official pricing page currently uses tables such as /5h for local messages, cloud tasks, and reviews. Actual usage should follow pricing docs and the app display.

7. Skills

A Skill is a reusable workflow. It is usually a folder containing SKILL.md, optionally with references, scripts, or assets. Codex initially sees the skill name, description, and path; it loads the full SKILL.md only when it decides the skill is needed. This saves context.

For example, a “workshop preparation” Skill could include reading registration data, checking fields, drafting invitation emails, producing a preparation status report, and creating a post-event review. For the next similar event, you do not need to explain the workflow from scratch.

Common skill scopes:

Codex can activate a Skill in two ways:

1. Explicit invocation: write $skill-name in the prompt, or choose it from a supported skill selector / /skills.
2. Implicit invocation: Codex matches the task against the skill description and loads it automatically.

A good Skill should focus on one job, and its description should clearly state when to use it and when not to use it. If you want to distribute multiple skills, app integrations, or MCP servers as an installable package, official docs recommend using a Plugin.

8. Plugins

Plugins are installable capability bundles in Codex. They may contain:

• Skills: reusable workflows.
• Apps: external service connections such as Gmail, Google Drive, Slack, or GitHub, allowing Codex to read information or take actions.
• MCP servers: services that provide more tools or shared information.

Official examples include:

• Gmail plugin: lets Codex read and manage Gmail.
• Google Drive plugin: works across Drive, Docs, Sheets, and Slides.
• Slack plugin: summarizes channels, triages notifications, or drafts replies.
• Sites: creates and deploys hosted websites, web apps, and games.
• Codex Security plugin: scans authorized code and confirms plausible security findings.

Other capabilities such as PDF, presentations, design, images, deployment, browser control, Computer Use, Chrome, and GitHub may be provided through plugins, skills, MCP, app connectors, or local tools. Availability depends on installed plugins, account plan, workspace policy, and platform. In teaching material, phrase these as “if the corresponding plugin / skill / MCP is installed,” not as guaranteed for every account.

When installing plugins, do not only check whether they connect. Also check the authorization scope and data-sharing policies. External services still follow their own account permissions, privacy policies, and operation risks.

9. Practical Scenarios

The examples below use workshop and campus fair preparation to show how Codex can take on repetitive work. These examples require tools and permissions that may not exist in every environment, so first confirm plugins, skills, sandbox settings, approvals, and account authorization.

1. Scanning and Renaming Files

Many computers contain files named “final,” “really final,” and “final final this time.” Ask Codex to scan a specified folder, explain what files are inside, and propose a consistent naming plan, such as renaming Final真的最後版 to 202606_講座活動說明. Before actual renaming, ask for a rename plan and confirm it.

2. Spreadsheet Consolidation and Processing Logs

Put class registration lists or booth applications into the project, then ask Codex to consolidate them into an Excel or CSV file with only important fields, such as name, department, email, attendance status, and dietary needs.

A useful principle: state the purpose clearly. Instead of only saying “organize this list,” say “prepare a list for attendance confirmation.” Codex will better understand which columns matter and which should be moved to notes.

After processing, ask Codex to produce a processing log: what changed, what data is missing, who needs an email address, and where the output file is. Codex output still needs review; logs make checking and follow-up easier.

Codex can also handle parallel tasks, such as consolidating booth applications while merging volunteer lists. Before execution, split tasks clearly and isolate them by files, threads, branches, or worktrees so outputs do not interfere with each other.

3. Customized Gmail Drafts

After cleaning the list, if the Gmail plugin is installed and authorized, ask Codex to draft customized invitations for different guests, with different openings and greetings based on role, and save them as Gmail drafts. After checking tone, recipients, attachments, and names in samples, let it generate the rest.

Sending email is an external action. Keep human sampling and confirmation in the loop.

4. Slide Drafts

Based on the event description and speaker bios, ask Codex to outline the deck: background, agenda, speaker introduction, registration information, and notes. If your environment has a presentation plugin, skill, or local tool, ask it to output PPTX, PDF, or a Markdown slide draft.

5. Images and Visual Assets

Codex can generate or edit images in a thread. Official docs mention built-in image generation using gpt-image-2, useful for UI assets, banners, backgrounds, illustrations, sprite sheets, and placeholders. This consumes Codex usage limits, and Free plans may not support it.

Example uses:

• Event key visuals, slide covers, speaker cards.
• Volunteer badges: generate a clean background, then use PDF or document tools to batch-fill names.
• Placeholders, banners, icons, or backgrounds for web pages and dashboards.

Chinese text, brand style, and details still require human review. Do not promise that Chinese typography will always be perfect. Treat generated images as drafts, iterate with Codex, and let a person make the final call.

6. HTML Dashboards

Ask Codex to build an HTML dashboard that combines guest attendance, class booth data, and overall event progress with clear charts. If a frontend design skill or plugin is installed, ask it to follow the specified style and responsive requirements.

The dashboard itself does not automatically fetch fresh data. For recurring updates, design the data source, synchronization process, automation, or external integration separately.

7. Event Website and Deployment

For a more complex website, do not start with only “build me a website.” A better workflow is to ask Codex to enter plan mode, list pages, content, assets, registration flow, deployment method, and acceptance criteria. Once the specification is clear, let it implement.

After completion, preview it with the in-app browser and leave precise feedback in Annotation mode. If your environment has Sites or another deployment plugin / tool, ask Codex to follow that flow and report the URL. If not, have it output files that can be opened locally or handed to a deployment platform.

At this point you are using natural-language collaborative development: even without writing code directly, you can describe the desired result, inspect the screen, request revisions, and let Codex update the files. Review and decision-making still remain your responsibility.

10. Automations

Automation

自動化適合固定、重複、可驗收的工作。Automation fits fixed, repeatable, reviewable work.

適合交給排程Good automation candidates

定時檢查報名資料、更新 Excel、找尚未回覆者、彙整過去 24 小時工作紀錄。Check registration data, update Excel files, find non-responders, or summarize the past 24 hours.

上線前先手動跑Run manually first

確認 prompt、權限、模型、工具、輸出位置與風險都符合預期。Confirm the prompt, permissions, model, tools, output location, and risk before scheduling.

對外寄送、刪除、帳務、個資與安全設定，仍要保留人工把關。External sends, deletion, finance, personal data, and security settings still need human review.

The Codex App supports Automations for recurring tasks. You can ask Codex to create or update an automation, such as “check the registration data every day at 9 a.m. and report only if something changed.”

Know these prerequisites:

• Project-scoped automations require the local Codex App to be running, the computer to be powered on, and the project to still exist on disk.
• In a Git repository, an automation can run in the local project or in a dedicated background worktree. Worktrees are better for isolating generated changes.
• Automations use your sandbox settings. Read-only mode limits file changes, network access, and app operations. Full access carries higher risk.
• Before scheduling a task for the first time, run it once manually in a normal thread to confirm the prompt, permissions, model, tools, and output.

Common automations:

• Every morning at 9 a.m., check the registration form, update the Excel file if new people registered, and report the diff.
• Find people who have not replied and generate follow-up email drafts.
• Periodically check guest replies, then update attendance status and dashboard data.
• Review the past 24 hours of work and suggest improvements to AGENTS.md or Skills, while leaving actual edits for human diff review.

The point of automation is not to showcase technology; it is to reduce the hidden cost of remembering routine tasks. Fixed, repeatable, reviewable work is ideal for automation. High-risk, judgment-heavy, or externally visible actions still require human review.

11. Advanced: Computer Use and Remote Control

Computer Use

Computer Use lets Codex see and operate macOS or Windows graphical interfaces, including clicking, typing, switching windows, and checking desktop apps or browser flows. It is useful for GUI tasks that command-line tools, APIs, plugins, or MCP cannot handle well, such as testing a desktop app, reproducing a bug visible only on screen, or using a data source without structured integration.

Before using it, install the Computer Use plugin. On macOS, grant Screen Recording and Accessibility permissions. On Windows, Computer Use operates the active desktop and cannot run in the background while you keep using the same mouse and keyboard session.

Important: Computer Use is a last-resort option. If the target tool has an API, CLI, MCP, or dedicated plugin, use that structured integration first because it is more stable, repeatable, and reviewable. Use Computer Use only when a GUI is necessary, keep the scope small, and stay present for sensitive flows.

Mobile Remote Control

Remote connections let you use Codex from another device. Official documentation confirms that the ChatGPT mobile app can control a connected Mac or Windows Codex App host. You can also continue work from another supported Codex App device or connect the Codex App to projects on an SSH host.

Setup essentials:

• You need Codex access in the same ChatGPT account and workspace.
• The phone needs the latest ChatGPT app. The host needs the latest Codex App, must be awake and online, and must be signed in to the same account and workspace.
• Setup starts from the Codex App host. Scan the QR code and finish pairing in the ChatGPT mobile app.
• Remote access uses the host's projects, threads, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools.
• A Windows host can be controlled from iOS, Android, or a Mac, but the Windows Codex App currently cannot control another computer.

If the host sleeps, loses network, or closes Codex, remote control disconnects. If a remote task uses Computer Use, especially on Windows, expect the host desktop to be used by Codex.

12. Codex vs Claude Code

Codex and Claude Code are both AI coding agent tools, and many ideas transfer between them: project scope, permissions, context, durable rules, reusable workflows, review, and version control. However, product comparisons should be checked against each vendor's official documentation. The table below keeps only Codex-side claims that align with Codex official docs.

A stable cross-tool migration pattern: write the true core rules and knowledge in project files such as CORE_RULES.md, AGENTS.md, README, SOP, or docs. Then create the appropriate entry file for each tool based on its official rules. This is SSOT (Single Source of Truth): maintain the core content once, and let tool-specific entry files refer to or summarize it.

Skills and Markdown files are easy for multiple agents to read, but do not assume every agent triggers, reads, truncates, or executes them the same way. For cross-platform work, the most important assets are clear project structure, file naming, verification workflows, and version control.

13. Principles

• Treat AI as a collaborator, not a one-time tool. New users often ask AI for isolated slide decks or copywriting tasks. Without stable context, the workflow does not improve. More mature usage builds projects, AGENTS.md, Skills, and verification loops so working methods accumulate.
• Give repeatable and reviewable work to AI; keep high-judgment responsibility with yourself. FAQ replies, sales reports, meeting summaries, file classification, and drafts are good starting points. Sending external messages, deleting files, changing finances, handling personal data, or modifying security settings still require human confirmation.
• Codex can also be your tutor. If you do not understand a Skill, ask what it does and when it triggers. Before installing a new tool, ask it to explain risks, steps, and verification before helping you execute.
• You are the agent manager. Do not assume a task handed to Codex will automatically match the complete version in your head. Give context, state goals, review plans, and inspect results. When it is wrong, explain what is wrong, why it is wrong, and how to judge it next time.

Once you understand local file work, project scope, sandbox and approvals, context management, AGENTS.md, Skills, Plugins, Automations, Computer Use, and Remote connections, Codex becomes more than a time-saving tool. It becomes a personal work system that can be trained, corrected, and refined over time.

Video References

This handout was prepared with reference to the following Codex teaching videos on YouTube, then corrected against OpenAI Developers Codex documentation on July 1, 2026. Learners can watch the original videos when they need to review demonstrations, confirm interface details, or revisit examples:

• Video 1: Introduction to Codex and AI content creation workflows
• Video 2: Codex introductory tutorial and AI Agent fundamentals
• Video 3: Codex desktop app workflows and cross-tool migration
• Video 4: Codex applications for spreadsheets, slides, mail merge, and websites

This handout was prepared with reference to four Codex teaching videos on YouTube and corrected against OpenAI Developers Codex documentation on July 1, 2026. Actual features, interface, plans, models, and usage limits may change; use the latest official documentation and the Codex App / CLI / IDE extension currently in front of you.