{ "canonical_name": "openai/codex", "compilation_id": "pack_a5cf1914e0b24d569db4a763fddeeb57", "created_at": "2026-05-13T10:35:20.668145+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm i -g @openai/codex` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm i -g @openai/codex", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_85dda9c946e943f28f9bbcf35e1b1fe0" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_a74197d521a2cca19f2473b20f4634b1", "canonical_name": "openai/codex", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/openai/codex", "slug": "codex", "source_packet_id": "phit_5b1ff2e81b0049aa9cdbd54c70f75c79", "source_validation_id": "dval_f21347d8e3f84f7f902de098e84d2a89" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 chatgpt的用户", "github_forks": 11886, "github_stars": 82254, "one_liner_en": "Lightweight coding agent that runs in your terminal", "one_liner_zh": "Lightweight coding agent that runs in your terminal", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, coding, git" }, "target_user": "使用 chatgpt 等宿主 AI 的用户", "title_en": "codex", "title_zh": "codex 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Checkpoint Resume", "label_zh": "断点恢复流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-checkpoint-resume", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_5b1ff2e81b0049aa9cdbd54c70f75c79", "page_model": { "artifacts": { "artifact_slug": "codex", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm i -g @openai/codex", "label": "Codex · 官方安装入口", "source": "https://github.com/openai/codex#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "断点恢复流程", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 chatgpt的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Lightweight coding agent that runs in your terminal" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "chatgpt", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Selected model is at capacity. Please try a different model. The same error everyday", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_2839c851344f4b669bd1c21b29e7bd08 | https://github.com/openai/codex/issues/22456 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Selected model is at capacity. Please try a different model. The same error everyday", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Extensive UI flickering when codex is working", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_47a11c3a9f3943168527e0a086872c1f | https://github.com/openai/codex/issues/11901 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Extensive UI flickering when codex is working", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Codex Desktop voice transcription blocked by Cloudflare challenge on /backend-api/transcribe after resolved incident", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_dcdaacada441496491e68dd4db3d802b | https://github.com/openai/codex/issues/21985 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Codex Desktop voice transcription blocked by Cloudflare challenge on /backend-api/transcribe after resolved incident", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Codex IDE extension fails GitHub MCP startup with \"connection closed: initialize response\" in PyCharm AI Chat", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_45286dbe57a44800be79bc6a5819956f | https://github.com/openai/codex/issues/22461 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Codex IDE extension fails GitHub MCP startup with \"connection closed: initialize response\" in PyCharm AI Chat", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Iranian phone numbers are not supported for Codex login", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_d651d7b5cf594cafa27dfffa45890baa | https://github.com/openai/codex/issues/21918 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Iranian phone numbers are not supported for Codex login", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex Desktop falsely reports @chrome plugin unavailable when bundled Chrome plugin is installed", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_a0eee5b5c5fb447ebe2c2d3bdf74aa33 | https://github.com/openai/codex/issues/22463 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Codex Desktop falsely reports @chrome plugin unavailable when bundled Chrome plugin is installed", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Chrome plugin hangs in setupAtlasRuntime despite extension/native host checks passing", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_4d667016a4ab4f9aa5416a3b08e71d55 | https://github.com/openai/codex/issues/22462 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Windows Chrome plugin hangs in setupAtlasRuntime despite extension/native host checks passing", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:965415649 | https://github.com/openai/codex | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：/goal-first sessions are missing from resume lists", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_e65f6682c39b409a8c96267f4bdc1d3e | https://github.com/openai/codex/issues/20792 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：/goal-first sessions are missing from resume lists", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：I have to set up the workspace every time I start a new session. My Codex usage quota is decreasing automatically even though I haven’t used it at all.", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_f8afe7124b3e44cfacbc62a9e001179c | https://github.com/openai/codex/issues/22457 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：I have to set up the workspace every time I start a new session. My Codex usage quota is decreasing automatically even…", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Renaming session with enter triggers the session window", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_a49c134e628047c1b558f3286721d0e7 | https://github.com/openai/codex/issues/22460 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Renaming session with enter triggers the session window", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:965415649 | https://github.com/openai/codex | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:965415649 | https://github.com/openai/codex | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | github_repo:965415649 | https://github.com/openai/codex | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:965415649 | https://github.com/openai/codex | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.130.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_0c9ba2dc6c7444688a9de6a144fee613 | https://github.com/openai/codex/releases/tag/rust-v0.130.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：0.130.0", "user_impact": "可能影响授权、密钥配置或安全边界。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：Selected model is at capacity. Please try a different model. The same error everyday。", "title": "踩坑日志" }, "snapshot": { "contributors": 442, "forks": 11886, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 82254 }, "source_url": "https://github.com/openai/codex", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Lightweight coding agent that runs in your terminal", "title": "codex 能力包", "trial_prompt": "# codex - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 codex 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-protocol：协议层详解。围绕“协议层详解”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-agent：核心Agent模块。围绕“核心Agent模块”模拟一次用户任务，不展示安装或运行结果。\n5. page-execution：执行系统。围绕“执行系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-protocol\n输入：用户提供的“协议层详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-agent\n输入：用户提供的“核心Agent模块”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-execution\n输入：用户提供的“执行系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-protocol：Step 3 必须围绕“协议层详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-agent：Step 4 必须围绕“核心Agent模块”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-execution：Step 5 必须围绕“执行系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/openai/codex\n- https://github.com/openai/codex#readme\n- .codex/skills/babysit-pr/SKILL.md\n- .codex/skills/code-review/SKILL.md\n- .codex/skills/code-review-breaking-changes/SKILL.md\n- .codex/skills/code-review-change-size/SKILL.md\n- .codex/skills/code-review-context/SKILL.md\n- .codex/skills/code-review-testing/SKILL.md\n- .codex/skills/codex-bug/SKILL.md\n- .codex/skills/codex-issue-digest/SKILL.md\n- .codex/skills/codex-pr-body/SKILL.md\n- .codex/skills/remote-tests/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 codex 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Codex Desktop voice transcription blocked by Cloudflare challenge on /ba（https://github.com/openai/codex/issues/21985）；github/github_issue: Codex Desktop falsely reports @chrome plugin unavailable when bundled Ch（https://github.com/openai/codex/issues/22463）；github/github_issue: missing context % usage in new version（https://github.com/openai/codex/issues/18101）；github/github_issue: Extensive UI flickering when codex is working（https://github.com/openai/codex/issues/11901）；github/github_issue: /goal-first sessions are missing from resume lists（https://github.com/openai/codex/issues/20792）；github/github_issue: Windows Chrome plugin hangs in setupAtlasRuntime despite extension/nativ（https://github.com/openai/codex/issues/22462）；github/github_issue: Codex IDE extension fails GitHub MCP startup with \"connection closed: in（https://github.com/openai/codex/issues/22461）；github/github_issue: Iranian phone numbers are not supported for Codex login（https://github.com/openai/codex/issues/21918）；github/github_issue: Significant increase in quota consumption after upgrading to v0.130.0（https://github.com/openai/codex/issues/22459）；github/github_issue: Phone number verification doesn't work（https://github.com/openai/codex/issues/20161）；github/github_issue: Renaming session with enter triggers the session window（https://github.com/openai/codex/issues/22460）；github/github_issue: I have to set up the workspace every time I start a new session. My Code（https://github.com/openai/codex/issues/22457）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Codex Desktop voice transcription blocked by Cloudflare challenge on /ba", "url": "https://github.com/openai/codex/issues/21985" }, { "kind": "github_issue", "source": "github", "title": "Codex Desktop falsely reports @chrome plugin unavailable when bundled Ch", "url": "https://github.com/openai/codex/issues/22463" }, { "kind": "github_issue", "source": "github", "title": "missing context % usage in new version", "url": "https://github.com/openai/codex/issues/18101" }, { "kind": "github_issue", "source": "github", "title": "Extensive UI flickering when codex is working", "url": "https://github.com/openai/codex/issues/11901" }, { "kind": "github_issue", "source": "github", "title": "/goal-first sessions are missing from resume lists", "url": "https://github.com/openai/codex/issues/20792" }, { "kind": "github_issue", "source": "github", "title": "Windows Chrome plugin hangs in setupAtlasRuntime despite extension/nativ", "url": "https://github.com/openai/codex/issues/22462" }, { "kind": "github_issue", "source": "github", "title": "Codex IDE extension fails GitHub MCP startup with \"connection closed: in", "url": "https://github.com/openai/codex/issues/22461" }, { "kind": "github_issue", "source": "github", "title": "Iranian phone numbers are not supported for Codex login", "url": "https://github.com/openai/codex/issues/21918" }, { "kind": "github_issue", "source": "github", "title": "Significant increase in quota consumption after upgrading to v0.130.0", "url": "https://github.com/openai/codex/issues/22459" }, { "kind": "github_issue", "source": "github", "title": "Phone number verification doesn't work", "url": "https://github.com/openai/codex/issues/20161" }, { "kind": "github_issue", "source": "github", "title": "Renaming session with enter triggers the session window", "url": "https://github.com/openai/codex/issues/22460" }, { "kind": "github_issue", "source": "github", "title": "I have to set up the workspace every time I start a new session. My Code", "url": "https://github.com/openai/codex/issues/22457" } ], "status": "已收录 15 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "Lightweight coding agent that runs in your terminal", "effort": "安装已验证", "forks": 11886, "icon": "code", "name": "codex 能力包", "risk": "可发布", "slug": "codex", "stars": 82254, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "断点恢复流程", "本地优先" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/openai/codex 项目说明书\n\n生成时间：2026-05-13 10:17:37 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [协议层详解](#page-protocol)\n- [核心Agent模块](#page-core-agent)\n- [执行系统](#page-execution)\n- [终端用户界面](#page-tui)\n- [技能系统](#page-skills)\n- [插件系统](#page-plugins)\n- [Hook系统](#page-hooks)\n- [沙箱与安全](#page-sandboxing)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [核心Agent模块](#page-core-agent)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/openai/codex/blob/main/README.md)\n- [codex-rs/tui/src/slash_command.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs)\n- [codex-rs/tui/src/bottom_pane/footer.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/footer.rs)\n- [codex-rs/config/src/profile_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs)\n- [codex-rs/config/src/tui_keymap.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/tui_keymap.rs)\n- [codex-rs/config/src/config_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs)\n
\n\n# 项目概述\n\n## 什么是 Codex CLI\n\nCodex CLI 是 OpenAI 开发的本地编程智能助手，能够在用户的计算机上本地运行。它是一个跨平台的命令行工具，旨在帮助开发者完成各种编码任务，包括代码编写、文件编辑、Git 操作和终端命令执行。 资料来源：[README.md:1]()\n\nCodex 提供三种使用形态：\n\n| 使用形态 | 说明 | 访问方式 |\n|---------|------|---------|\n| **CLI 工具** | 本地终端界面，运行在用户计算机上 | 运行 `codex` 命令 |\n| **IDE 插件** | 集成在 VS Code、Cursor、Windsurf 等编辑器中 | 安装 IDE 插件 |\n| **桌面应用** | 独立的桌面客户端体验 | 运行 `codex app` 或访问网页版 |\n\n对于云端智能助手版本（Codex Web），用户可以访问 chatgpt.com/codex。 资料来源：[README.md:8]()\n\n## 安装与运行\n\n### 安装方式\n\nCodex 支持两种主流安装方式：\n\n```shell\n# 使用 npm 全局安装\nnpm install -g @openai/codex\n\n# 使用 Homebrew 安装\nbrew install --cask codex\n```\n\n安装完成后，直接在终端运行 `codex` 即可启动。 资料来源：[README.md:17-28]()\n\n## 核心功能模块\n\n### 命令系统（Slash Commands）\n\nCodex CLI 内置丰富的斜杠命令系统，用户可以通过 `/` 前缀调用各种功能：\n\n| 命令类别 | 功能项 | 说明 |\n|---------|-------|------|\n| 会话管理 | `/resume`, `/fork`, `/clear` | 恢复会话、分叉会话、清除终端 |\n| 文件操作 | `/mention`, `/diff` | 提及文件、显示 Git 差异 |\n| 配置管理 | `/status`, `/debug-config`, `/settings` | 查看状态、调试配置、设置选项 |\n| 开发工具 | `/skills`, `/hooks`, `/mcp` | 技能系统、生命周期钩子、MCP 工具 |\n| 界面定制 | `/theme`, `/keymap`, `/pets`, `/title` | 主题、快捷键、终端宠物、标题栏 |\n| 执行控制 | `/plan`, `/goal`, `/stop` | 计划模式、目标设置、停止后台进程 |\n| 权限管理 | `/permissions`, `/elevate-sandbox` | 权限配置、沙盒提升 |\n| 高级功能 | `/realtime`, `/collab`, `/agent` | 实时语音、协作模式、多代理 |\n\n资料来源：[codex-rs/tui/src/slash_command.rs:1-50]()\n\n### 快捷键系统\n\nCodex 的文本用户界面（TUI）支持全面的快捷键绑定，主要包括：\n\n**运动类快捷键**\n\n| 操作 | 默认绑定 | 说明 |\n|------|---------|------|\n| `motion_left` | 左移 | 光标向左移动 |\n| `motion_right` | 右移 | 光标向右移动 |\n| `motion_up` | 上移 | 光标向上移动一行 |\n| `motion_down` | 下移 | 光标向下移动一行 |\n| `motion_word_forward` | `w` | 移动到下一个单词开头 |\n| `motion_word_backward` | `b` | 移动到上一个单词开头 |\n| `motion_word_end` | `e` | 移动到单词结尾 |\n| `motion_line_start` | `0` | 移动到行首 |\n| `motion_line_end` | `$` | 移动到行尾 |\n\n**分页器快捷键**\n\n| 操作 | 功能 |\n|------|------|\n| `scroll_up` / `scroll_down` | 按行滚动 |\n| `page_up` / `page_down` | 按页滚动 |\n| `half_page_up` / `half_page_down` | 半页滚动 |\n| `jump_top` / `jump_bottom` | 跳转到顶部/底部 |\n| `close` / `close_transcript` | 关闭分页器/转录 |\n\n**列表和审批快捷键**\n\n| 类别 | 操作 |\n|------|------|\n| 列表 | `move_up`, `move_down`, `accept`, `cancel` |\n| 审批 | `open_fullscreen`, `open_thread`, `approve`, `deny`, `decline` |\n\n资料来源：[codex-rs/config/src/tui_keymap.rs:1-50]()\n\n### 底部面板与状态栏\n\nCodex 界面底部面板展示各类快捷操作提示，包括：\n\n- 命令执行相关快捷键\n- Shell 命令快捷键\n- 文件路径操作（粘贴图片、外部编辑器调用）\n- 历史记录搜索\n- 推理模式切换（`reasoning_down` / `reasoning_up`）\n- 会话转录显示\n\n底部面板采用双列布局展示各项功能，每列之间有 4 个字符的间距。 资料来源：[codex-rs/tui/src/bottom_pane/footer.rs:1-50]()\n\n### 状态显示系统\n\n状态栏提供实时的工作环境信息：\n\n| 状态项 | 说明 | 示例值 |\n|-------|------|--------|\n| `AppName` | 应用名称 | Codex |\n| `ProjectName` | 项目名称 | my-project |\n| `GitBranch` | 当前 Git 分支 | feat/awesome-feature |\n| `PullRequestNumber` | PR 编号 | PR #123 |\n| `BranchChanges` | 分支变更统计 | +12 -3 |\n| `Permissions` | 权限级别 | Workspace |\n| `ContextRemaining` | 剩余上下文 | Context 0% left |\n| `UsedTokens` | 已使用 Token | 0 used |\n| `Model` | 当前模型 | gpt-5.2-codex |\n| `SessionId` | 会话 ID | 550e8400-e29b-41d4 |\n\n资料来源：[codex-rs/tui/src/status/card.rs:1-50](), [codex-rs/tui/src/status_surfaces.rs:1-40]()\n\n## 配置系统\n\n### 配置文件结构\n\nCodex 采用 TOML 格式的配置文件，支持多层级配置：\n\n```toml\n# 全局配置\n[profile.default]\nmodel = \"gpt-5\"\ninclude_apply_patch_tool = true\ninclude_permissions_instructions = true\n\n# TUI 配置\n[profile.default.tui]\nsession_picker_view = \"grid\" # 或 \"list\"\n\n# 实验性功能\n[profile.default.features]\ncodex_git_commit = true\nexperimental_realtime = false\n```\n\n### 配置选项说明\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `model_instructions_file` | 路径 | 自定义模型指令文件（不推荐） |\n| `compact_prompt` | 字符串 | 历史压缩提示词 |\n| `commit_attribution` | 字符串 | 提交信息中的共同作者署名 |\n| `forced_chatgpt_workspace_id` | 字符串 | 限制登录到特定工作区 |\n| `forced_login_method` | 枚举 | 强制使用特定登录方式 |\n\n资料来源：[codex-rs/config/src/profile_toml.rs:1-40](), [codex-rs/config/src/config_toml.rs:1-50]()\n\n## 主题与语法高亮\n\nCodex 内置多种语法高亮主题，支持自定义代码显示颜色：\n\n**可用主题列表**\n\n| 主题名称 | 类型 |\n|---------|------|\n| catppuccin-latte / macchiato / mocha | 暖色调 |\n| coldark-cold / dark | 冷色调 |\n| dark-neon | 霓虹风格 |\n| dracula | 经典紫红 |\n| github | GitHub 风格 |\n| gruvbox-dark / light | 复古风格 |\n| inspired-github | GitHub 灵感 |\n| 1337 (leet) | 黑客风格 |\n| monokai-extended 系列 | Monokai 扩展 |\n| nord | 北欧极简 |\n| one-half-dark / light | 简约双色 |\n\n资料来源：[codex-rs/tui/src/render/highlight.rs:1-60]()\n\n## 目标与预算系统\n\nCodex 内置目标追踪系统，支持长时间运行任务的规划与监控：\n\n```mermaid\ngraph TD\n A[创建目标] --> B{预算检查}\n B -->|预算充足| C[执行任务]\n B -->|预算耗尽| D[触发预算限制提示]\n C --> E[目标更新]\n E --> F{任务完成?}\n F -->|否| C\n F -->|是| G[目标达成]\n D --> H[暂停或终止]\n```\n\n目标系统包含以下组件：\n\n- **目标模板**：使用 Markdown 模板定义目标展示格式\n- **预算限制**：监控任务消耗，必要时触发提醒\n- **目标更新**：实时反馈目标进展状态\n\n资料来源：[codex-rs/core/src/goals.rs:1-60]()\n\n## 环境上下文\n\nCodex 能够感知并注入当前工作环境信息：\n\n```xml\n\n \n \n /path/to/project\n bash\n \n \n 2024-01-15\n Asia/Shanghai\n\n```\n\n| 环境组件 | 说明 |\n|---------|------|\n| `cwd` | 当前工作目录 |\n| `shell` | 终端类型（bash/zsh/powershell） |\n| `network` | 网络状态信息 |\n| `subagents` | 子代理信息（多代理模式下） |\n\n资料来源：[codex-rs/core/src/context/environment_context.rs:1-50]()\n\n## 应用与插件系统\n\nCodex 支持外部应用集成和 MCP（Model Context Protocol）工具：\n\n```mermaid\ngraph LR\n A[Codex CLI] --> B[应用系统]\n A --> C[MCP 工具]\n B --> D{应用配置}\n D -->|已启用| E[集成到界面]\n D -->|已禁用| F[隐藏]\n C --> G[工具列表]\n G --> H[详细工具说明]\n```\n\n**应用元数据结构**\n\n| 字段 | 说明 |\n|-----|------|\n| `id` | 应用唯一标识 |\n| `name` | 显示名称 |\n| `description` | 应用描述 |\n| `logo_url` | 图标 URL |\n| `is_enabled` | 是否启用 |\n| `install_url` | 安装链接 |\n\n资料来源：[codex-rs/app-server-protocol/src/protocol/v2/apps.rs:1-50]()\n\n## 架构总览\n\n```mermaid\ngraph TB\n subgraph 前端层\n A[命令行入口] --> B[文本用户界面 TUI]\n B --> C[底部面板]\n B --> D[状态栏]\n B --> E[快捷键系统]\n end\n \n subgraph 配置层\n F[配置文件] --> G[配置解析器]\n G --> H[Profile 管理]\n H --> I[TUI 设置]\n H --> J[功能开关]\n end\n \n subgraph 核心层\n K[会话管理] --> L[目标系统]\n K --> M[上下文管理]\n M --> N[环境感知]\n L --> O[预算控制]\n end\n \n subgraph 集成层\n P[IDE 插件接口] --> Q[应用系统]\n P --> R[MCP 工具]\n Q --> S[应用市场]\n end\n \n A --> K\n G --> K\n```\n\n## 技术栈概述\n\n| 组件 | 技术选型 | 说明 |\n|-----|---------|------|\n| CLI 核心 | Rust | 高性能本地执行 |\n| 前端界面 | 自研 TUI | 终端文本用户界面 |\n| 配置格式 | TOML | 人类可读的配置文件 |\n| 主题系统 | TextMate 主题格式 | 兼容主流编辑器语法高亮 |\n| 序列化 | JSON Schema | API 数据结构定义 |\n| 类型导出 | TypeScript | 前端类型安全 |\n\n## 快速入门\n\n1. **安装 Codex**：`npm i -g @openai/codex` 或 `brew install --cask codex`\n2. **启动应用**：运行 `codex` 命令\n3. **查看帮助**：输入 `/help` 或查看底部快捷键提示\n4. **自定义配置**：编辑 `~/.codex/config.toml`\n5. **切换主题**：使用 `/theme` 命令选择语法高亮主题\n\n## 相关资源\n\n- 官方文档：[developers.openai.com/codex/ide](https://developers.openai.com/codex/ide)\n- 桌面应用：运行 `codex app` 或访问 chatgpt.com/codex\n- IDE 插件：支持 VS Code、Cursor、Windsurf\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[协议层详解](#page-protocol), [核心Agent模块](#page-core-agent), [终端用户界面](#page-tui)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [codex-rs/config/src/state.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n- [codex-rs/config/src/loader/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/loader/mod.rs)\n- [codex-rs/config/src/config_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs)\n- [codex-rs/config/src/profile_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs)\n- [codex-rs/core/src/context/environment_context.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs)\n- [codex-rs/core/src/goals.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs)\n- [codex-rs/tui/src/chatwidget.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs)\n- [codex-rs/file-search/README.md](https://github.com/openai/codex/blob/main/codex-rs/file-search/README.md)\n
\n\n# 系统架构\n\n## 1. 概述\n\nCodex CLI 是 OpenAI 开发的一个本地代码智能助手，采用 Rust 语言重写实现。该项目遵循模块化架构设计，将功能拆分为多个独立但协作的子系统。\n\n核心架构包含以下几个主要层次：\n\n| 层次 | 模块 | 职责 |\n|------|------|------|\n| 配置层 | `codex-rs/config/` | 管理配置加载、层级合并、需求约束 |\n| 核心层 | `codex-rs/core/` | 处理环境上下文、目标管理、推理逻辑 |\n| 交互层 | `codex-rs/tui/` | 终端用户界面、聊天组件、状态显示 |\n| 文件搜索 | `codex-rs/file-search/` | 模糊文件搜索、模式匹配 |\n| 沙箱层 | `codex-rs/windows-sandbox-rs/` | Windows 平台沙箱环境 |\n\n资料来源：[codex-rs/README.md](https://github.com/openai/codex/blob/main/codex-rs/README.md)\n\n## 2. 配置系统架构\n\n### 2.1 配置层级结构\n\nCodex 采用多层配置架构，不同来源的配置按优先级合并。配置层级从低到高依次为：\n\n```mermaid\ngraph TD\n A[系统配置
System] --> B[用户配置
User]\n B --> C[项目配置
Project]\n C --> D[MDM 托管配置
MDM Managed]\n D --> E[会话标志配置
Session Flags]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n```\n\n`ConfigLayerStack` 结构维护配置层级列表，其中 `layers` 向量按从低优先级（基础）到高优先级（覆盖）的顺序排列。资料来源：[codex-rs/config/src/state.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n\n### 2.2 配置来源枚举\n\n```rust\npub enum ConfigLayerSource {\n System { file: PathBuf },\n User { file: PathBuf },\n Project { dot_codex_folder: AbsolutePathBuf },\n Mdm { domain: String, key: String },\n SessionFlags,\n LegacyManagedConfigTomlFromFile { file: PathBuf },\n LegacyManagedConfigTomlFromMdm,\n}\n```\n\n每种配置来源对应不同的配置文件位置：\n\n| 来源类型 | 文件位置 | 说明 |\n|---------|---------|------|\n| System | 系统指定路径 | 系统级配置 |\n| User | 用户目录 `~/.codex/` | 用户个性化配置 |\n| Project | 项目 `.codex/` 目录 | 项目特定配置 |\n| MDM | 移动设备管理 | 企业托管配置 |\n| SessionFlags | 命令行参数 | 会话级别覆盖 |\n\n资料来源：[codex-rs/config/src/state.rs:1-30](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n\n### 2.3 配置文件加载流程\n\n配置加载器 (`ConfigLoader`) 负责协调多层级配置的读取和合并：\n\n```mermaid\nsequenceDiagram\n participant User as 用户/CLI\n participant Loader as ConfigLoader\n participant FileSystem as 文件系统\n participant Merger as 配置合并器\n \n User->>Loader: 启动 Codex\n Loader->>FileSystem: 读取系统配置\n FileSystem-->>Loader: system.toml\n Loader->>FileSystem: 读取用户配置\n FileSystem-->>Loader: config.toml\n Loader->>FileSystem: 读取项目配置\n FileSystem-->>Loader: .codex/config.toml\n Loader->>Merger: 合并配置层级\n Merger-->>User: 最终配置\n```\n\n配置加载过程中的关键步骤包括：\n1. 解析 TOML 格式的配置文件\n2. 清理无效的项目配置键\n3. 解析相对路径为绝对路径\n4. 合并 Git worktree 的钩子配置\n\n资料来源：[codex-rs/config/src/loader/mod.rs:1-80](https://github.com/openai/codex/blob/main/codex-rs/config/src/loader/mod.rs)\n\n### 2.4 Profile 配置结构\n\nProfile 机制允许用户定义命名配置集，每个 Profile 可包含独立的 TUI 设置、窗口配置和功能开关：\n\n```rust\npub struct ProfileTui {\n /// Resume/Fork 会话选择器的首选布局\n pub session_picker_view: Option,\n}\n\npub struct FeaturesToml {\n // 注入已知功能键到 schema\n}\n```\n\nProfile 作用域的配置包括：\n- TUI 布局偏好设置\n- 窗口配置\n- 功能特性开关\n\n资料来源：[codex-rs/config/src/profile_toml.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs)\n\n### 2.5 配置诊断系统\n\n当配置解析失败时，诊断系统提供详细的错误报告：\n\n```rust\npub fn format_config_error(error: &ConfigError, contents: &str) -> String {\n // 输出格式: path:line:column: message\n // 包含错误位置的高亮行\n}\n```\n\n错误报告包含文件路径、行号、列号和错误消息，并从 TOML 解析的 span 信息中提取错误位置。资料来源：[codex-rs/config/src/diagnostics.rs:1-40](https://github.com/openai/codex/blob/main/codex-rs/config/src/diagnostics.rs)\n\n## 3. 环境上下文系统\n\n### 3.1 上下文数据模型\n\n环境上下文 (`EnvironmentContext`) 聚合了 Codex 运行所需的全部环境信息：\n\n```mermaid\ngraph TD\n EC[EnvironmentContext] --> Env[Environments]\n EC --> Date[CurrentDate]\n EC --> TZ[Timezone]\n EC --> Net[Network]\n EC --> Subs[Subagents]\n \n Env --> Single[Single Environment]\n Env --> Multiple[Multiple Environments]\n Env --> None[None]\n```\n\n关键字段：\n- **environments**: 工作目录和 shell 信息\n- **current_date**: 当前日期\n- **timezone**: 时区设置\n- **network**: 网络连接状态\n- **subagents**: 子代理信息\n\n资料来源：[codex-rs/core/src/context/environment_context.rs:1-60](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs)\n\n### 3.2 上下文 XML 渲染\n\n环境上下文以 XML 格式渲染，供模型理解当前执行环境：\n\n```xml\n\n \n /path/to/project\n bash\n \n 2024-01-15\n Asia/Shanghai\n\n```\n\n资料来源：[codex-rs/core/src/context/environment_context.rs:60-100](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs)\n\n## 4. 目标管理系统\n\n### 4.1 目标生命周期\n\nCodex 的目标 (Goal) 系统管理长时间运行的任务：\n\n```mermaid\nstateDiagram-v2\n [*] --> NewGoal: 设置目标\n NewGoal --> Active: 开始执行\n Active --> Paused: 中断\n Active --> Completed: 完成\n Active --> Failed: 失败\n Paused --> Active: 恢复\n Failed --> [*]\n Completed --> [*]\n```\n\n`ExternalGoalPreviousStatus` 枚举表示外部目标变更前的状态：\n- `NewGoal`: 新创建的逻辑目标\n- `Existing`: 更新的现有目标\n\n资料来源：[codex-rs/core/src/goals.rs:1-80](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs)\n\n### 4.2 预算限制与节流\n\n目标系统内置预算限制提示模板：\n- `continuation.md`: 继续执行提示\n- `budget_limit.md`: 预算耗尽提示\n- `objective_updated.md`: 目标更新通知\n\n资料来源：[codex-rs/core/src/goals.rs:80-120](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs)\n\n## 5. TUI 终端用户界面\n\n### 5.1 组件架构\n\nTUI 模块采用组件化设计：\n\n```\ntui/src/\n├── chatwidget.rs # 聊天消息组件\n├── markdown_render_tests.rs # Markdown 渲染测试\n└── bottom_pane/\n ├── footer.rs # 底部状态栏\n ├── status_surface_preview.rs # 状态预览\n └── approval_overlay.rs # 审批覆盖层\n```\n\n### 5.2 风险等级映射\n\n聊天组件 (`chatwidget`) 处理来自应用服务器协议的风险等级映射：\n\n```mermaid\ngraph LR\n A[GuardianRiskLevel] --> B[AppServer]\n B --> C[chatwidget]\n C --> D[Protocol]\n \n D --> Low\n D --> Medium\n D --> High\n D --> Critical\n```\n\n| 应用服务器等级 | 协议等级 |\n|--------------|---------|\n| Low | Low |\n| Medium | Medium |\n| High | High |\n| Critical | Critical |\n\n资料来源：[codex-rs/tui/src/chatwidget.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs)\n\n### 5.3 状态栏配置\n\n底部面板显示快捷命令和状态信息：\n\n| 类别 | 快捷键 |\n|------|--------|\n| 常规命令 | `/` |\n| Shell 命令 | `!` |\n| 队列消息 | `Tab` |\n| 退出 | `Ctrl+C` |\n| 推理导航 | `Ctrl+↑/↓` |\n\n自定义快捷键可通过 `/keymap` 命令配置。资料来源：[codex-rs/tui/src/bottom_pane/footer.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/footer.rs)\n\n### 5.4 状态预览项\n\n状态表面预览显示会话的各类状态信息：\n\n| 预览项 | 示例值 |\n|-------|--------|\n| AppName | Codex |\n| GitBranch | feat/awesome-feature |\n| PullRequestNumber | PR #123 |\n| BranchChanges | +12 -3 |\n| ContextRemaining | Context 0% left |\n| UsedTokens | 0 used |\n| Model | gpt-5.2-codex |\n| FastMode | Fast on |\n\n资料来源：[codex-rs/tui/src/bottom_pane/status_surface_preview.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/status_surface_preview.rs)\n\n### 5.5 审批覆盖层\n\n文件变更审批系统提供多种决策选项：\n\n| 选项 | 快捷键 | 效果 |\n|------|--------|------|\n| Yes, proceed | approve | 接受变更 |\n| Yes, don't ask again | approve_for_session | 本次会话接受 |\n| No, tell Codex | reject | 拒绝并说明 |\n\n资料来源：[codex-rs/tui/src/bottom_pane/approval_overlay.rs:1-60](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs)\n\n## 6. 文件搜索模块\n\n### 6.1 搜索架构\n\n`codex_file_search` 模块提供快速的模糊文件搜索能力：\n\n```mermaid\ngraph TD\n Input[搜索模式] --> Traverse[目录遍历]\n Traverse --> Ignore[应用 .gitignore]\n Ignore --> Files[文件列表]\n Files --> Fuzzy[模糊匹配]\n Fuzzy --> Results[结果排序]\n```\n\n核心依赖：\n- **ignore**: 目录遍历（ripgrep 使用的 crate）\n- **nucleo-matcher**: 快速模糊匹配\n\n资料来源：[codex-rs/file-search/README.md](https://github.com/openai/codex/blob/main/codex-rs/file-search/README.md)\n\n## 7. Slash 命令系统\n\n### 7.1 命令分类\n\nSlash 命令通过 `/` 触发，提供丰富的交互功能：\n\n| 类别 | 命令 | 功能 |\n|------|------|------|\n| 会话管理 | `/resume`, `/fork`, `/clear` | 恢复、分叉、清空会话 |\n| 文件操作 | `/diff`, `/mention` | Git 差异、提及文件 |\n| 模型控制 | `/model`, `/personality` | 选择模型、交流风格 |\n| 权限管理 | `/permissions`, `/elevate-sandbox` | 权限设置 |\n| 实验功能 | `/experimental`, `/realtime` | 开关实验特性 |\n\n支持内联参数的命令：\n- `/review`, `/rename`, `/plan`, `/goal`\n- `/ide`, `/keymap`, `/mcp`, `/pets`, `/side`\n- `/resume`, `/sandbox-read-root`\n\n资料来源：[codex-rs/tui/src/slash_command.rs:1-100](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs)\n\n## 8. 安装与部署\n\n### 8.1 安装方式\n\n| 方式 | 命令 |\n|------|------|\n| npm | `npm i -g @openai/codex` |\n| Homebrew | `brew install --cask codex` |\n| GitHub Releases | 下载平台特定二进制 |\n\n### 8.2 目录结构\n\n```\n$CODEX_HOME/\n├── config.toml # 用户配置\n├── sessions/ # 会话数据\n├── log/ # 日志文件\n└── hooks/ # 生命周期钩子\n```\n\n- **sqlite_home**: SQLite 数据库路径，默认 `$CODEX_HOME`\n- **log_dir**: 日志目录，默认 `$CODEX_HOME/log`\n\n资料来源：[codex-rs/config/src/config_toml.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs)\n\n## 9. 模块依赖关系\n\n```mermaid\ngraph TD\n App[codex-rs 主程序]\n Config[config 模块]\n Core[core 模块]\n TUI[TUI 模块]\n FileSearch[file-search 模块]\n Sandbox[windows-sandbox-rs]\n \n App --> Config\n App --> Core\n App --> TUI\n Core --> FileSearch\n Core --> Sandbox\n TUI --> Config\n TUI --> Core\n```\n\n各模块职责清晰分离，通过公共接口交互，便于维护和测试。\n\n---\n\n\n\n## 协议层详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [核心Agent模块](#page-core-agent)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [codex-rs/tui/src/chatwidget.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs)\n- [codex-rs/app-server-protocol/src/protocol/v2/apps.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/apps.rs)\n- [codex-rs/config/src/state.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n- [codex-rs/config/src/config_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs)\n- [codex-rs/config/src/config_requirements.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_requirements.rs)\n- [codex-rs/tui/src/bottom_pane/approval_overlay.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs)\n
\n\n# 协议层详解\n\n## 1. 概述\n\nCodex 项目的协议层是连接前端界面（TUI）、后端服务（App Server）和核心引擎（Core）之间的通信桥梁。该层定义了数据类型转换、API 协议版本管理、以及跨模块通信的数据结构规范。\n\n协议层主要包含两个核心命名空间：\n- `codex_app_server_protocol`：应用服务器协议定义\n- `codex_protocol`：Codex 核心协议定义\n\n## 2. 协议架构\n\n### 2.1 模块组织结构\n\n```\ncodex-rs/\n├── app-server-protocol/src/protocol/\n│ ├── mod.rs # 协议主入口\n│ ├── v1.rs # 版本 1 协议定义\n│ └── v2/ # 版本 2 协议定义\n│ ├── mod.rs\n│ ├── apps.rs # 应用相关协议\n│ └── ...\n```\n\n### 2.2 协议层次关系图\n\n```mermaid\ngraph TD\n subgraph \"前端层 TUI\"\n A[ChatWidget]\n B[ApprovalOverlay]\n C[StatusSurface]\n end\n \n subgraph \"协议转换层\"\n D[codex_app_server_protocol]\n E[codex_protocol]\n end\n \n subgraph \"核心层 Core\"\n F[Guardian]\n G[Approvals]\n end\n \n A --> D\n B --> D\n C --> D\n \n D --> E\n E --> F\n E --> G\n \n style D fill:#f9f,color:#000\n style E fill:#9f9,color:#000\n```\n\n## 3. 风险等级协议\n\n### 3.1 风险等级定义\n\nCodex 使用统一的四层风险等级体系，用于评估操作的安全性和敏感度。\n\n| 风险等级 | 说明 | 适用场景 |\n|---------|------|---------|\n| `Low` | 低风险操作 | 读取文件、查看状态 |\n| `Medium` | 中等风险 | 修改配置、创建文件 |\n| `High` | 高风险 | 执行命令、修改系统 |\n| `Critical` | 极高风险 | 删除文件、权限变更 |\n\n**资料来源**：[codex-rs/tui/src/chatwidget.rs:1-20](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs)\n\n### 3.2 协议间转换\n\n风险等级在 `codex_app_server_protocol` 和 `codex_protocol` 之间存在一一映射关系：\n\n```rust\n(|risk_level| match risk_level {\n codex_app_server_protocol::GuardianRiskLevel::Low => {\n codex_protocol::approvals::GuardianRiskLevel::Low\n }\n codex_app_server_protocol::GuardianRiskLevel::Medium => {\n codex_protocol::approvals::GuardianRiskLevel::Medium\n }\n codex_app_server_protocol::GuardianRiskLevel::High => {\n codex_protocol::approvals::GuardianRiskLevel::High\n }\n codex_app_server_protocol::GuardianRiskLevel::Critical => {\n codex_protocol::approvals::GuardianRiskLevel::Critical\n }\n})\n```\n\n**资料来源**：[codex-rs/tui/src/chatwidget.rs:1-20](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs)\n\n## 4. 用户授权协议\n\n### 4.1 授权等级定义\n\n| 授权等级 | 说明 | 权限范围 |\n|---------|------|---------|\n| `Unknown` | 未知状态 | 未确定授权级别 |\n| `Low` | 低授权 | 基础操作权限 |\n| `Medium` | 中等授权 | 常规开发操作 |\n| `High` | 高授权 | 敏感操作权限 |\n\n### 4.2 授权协议转换\n\n用户授权信息在协议间进行转换：\n\n```rust\nuser_authorization: review.user_authorization.map(|user_authorization| {\n match user_authorization {\n codex_app_server_protocol::GuardianUserAuthorization::Unknown => {\n codex_protocol::approvals::GuardianUserAuthorization::Unknown\n }\n codex_app_server_protocol::GuardianUserAuthorization::Low => {\n codex_protocol::approvals::GuardianUserAuthorization::Low\n }\n codex_app_server_protocol::GuardianUserAuthorization::Medium => {\n codex_protocol::approvals::GuardianUserAuthorization::Medium\n }\n codex_app_server_protocol::GuardianUserAuthorization::High => {\n codex_protocol::approvals::GuardianUserAuthorization::High\n }\n }\n})\n```\n\n**资料来源**：[codex-rs/tui/src/chatwidget.rs:1-30](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs)\n\n## 5. 应用协议（V2）\n\n### 5.1 应用信息结构\n\n应用元数据结构定义如下：\n\n```rust\npub struct AppInfo {\n pub id: String,\n pub name: String,\n pub description: Option,\n pub logo_url: Option,\n pub logo_url_dark: Option,\n pub distribution_channel: Option,\n pub branding: Option,\n pub app_metadata: Option,\n pub labels: Option>,\n pub install_url: Option,\n #[serde(default)]\n pub is_accessible: bool,\n #[serde(default = \"default_enabled\")]\n pub is_enabled: bool,\n #[serde(default)]\n pub plugin_display_names: Vec,\n}\n```\n\n**资料来源**：[codex-rs/app-server-protocol/src/protocol/v2/apps.rs:50-70](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/apps.rs)\n\n### 5.2 应用元数据\n\n应用元数据支持以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `screenshots` | `Vec` | 应用截图列表 |\n| `developer` | `String` | 开发者信息 |\n| `version` | `String` | 版本号 |\n| `version_id` | `String` | 版本标识 |\n| `version_notes` | `String` | 版本说明 |\n| `first_party_type` | `String` | 第一方类型 |\n| `first_party_requires_install` | `bool` | 是否需要安装 |\n| `show_in_composer_when_unlinked` | `bool` | 未链接时显示 |\n\n**资料来源**：[codex-rs/app-server-protocol/src/protocol/v2/apps.rs:30-50](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/apps.rs)\n\n## 6. 配置层协议\n\n### 6.1 配置层级来源\n\n配置层定义在 `ConfigLayerSource` 枚举中，支持多种配置来源：\n\n| 来源类型 | 说明 | 优先级 |\n|---------|------|-------|\n| `Mdm` | MDM 托管偏好 | 最高 |\n| `System` | 系统级配置 | 高 |\n| `User` | 用户级配置 | 中 |\n| `Project` | 项目级 `.codex/config.toml` | 低 |\n| `SessionFlags` | 会话命令行参数 | 特殊 |\n\n```rust\npub enum ConfigLayerSource {\n Mdm { domain: String, key: String },\n System { file: PathBuf },\n User { file: PathBuf },\n Project { dot_codex_folder: AbsolutePathBuf },\n SessionFlags,\n LegacyManagedConfigTomlFromFile { file: PathBuf },\n LegacyManagedConfigTomlFromMdm,\n}\n```\n\n**资料来源**：[codex-rs/config/src/state.rs:50-80](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n\n### 6.2 配置需求协议\n\n配置需求通过 `RequirementSource` 定义来源：\n\n```rust\npub enum RequirementSource {\n Unknown,\n MdmManagedPreferences { domain: String, key: String },\n CloudRequirements,\n SystemRequirementsToml { file: PathBuf },\n LegacyManagedConfigTomlFromFile { file: PathBuf },\n LegacyManagedConfigTomlFromMdm,\n}\n```\n\n**资料来源**：[codex-rs/config/src/config_requirements.rs:1-30](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_requirements.rs)\n\n### 6.3 配置层堆栈\n\n```mermaid\ngraph LR\n A[System Config] --> B[User Config]\n B --> C[Project Config]\n C --> D[Session Flags]\n D --> E[MDM Config]\n \n style A fill:#eee,color:#000\n style E fill:#f96,color:#000\n```\n\n配置层堆栈顺序定义：\n\n```rust\npub enum ConfigLayerStackOrdering {\n LowestPrecedenceFirst,\n HighestPrecedenceFirst,\n}\n\npub struct ConfigLayerStack {\n /// 从最低优先级（基础）到最高优先级（顶层）\n layers: Vec,\n /// 用户配置层索引\n user_layer_index: Option,\n}\n```\n\n**资料来源**：[codex-rs/config/src/state.rs:80-100](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n\n## 7. 审批协议\n\n### 7.1 审批决策来源\n\n自动审查决策来源定义：\n\n```rust\nenum AutoReviewDecisionSource {\n Agent,\n}\n```\n\n### 7.2 审批选项配置\n\n审批覆盖层支持的选项：\n\n| 选项标签 | 决策类型 | 说明 |\n|---------|---------|------|\n| `Yes, proceed` | `Accept` | 接受变更 |\n| `Yes, and don't ask again for these files` | `AcceptForSession` | 本会话内接受 |\n| `No, and tell Codex what to do differently` | `Reject` | 拒绝并反馈 |\n\n**资料来源**：[codex-rs/tui/src/bottom_pane/approval_overlay.rs:50-80](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs)\n\n### 7.3 文件系统路径协议\n\n| 特殊路径 | 说明 |\n|---------|------|\n| `:root` | 项目根目录 |\n| `:minimal` | 最小访问范围 |\n| `:project_roots` | 所有项目根目录 |\n| `:tmpdir` | 系统临时目录 |\n| `/tmp` | 传统临时目录路径 |\n\n**资料来源**：[codex-rs/tui/src/bottom_pane/approval_overlay.rs:20-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs)\n\n## 8. 状态显示协议\n\n### 8.1 状态行项目\n\n状态行支持显示以下信息项目：\n\n| 项目 | 示例值 | 说明 |\n|-----|-------|------|\n| `AppName` | Codex | 应用名称 |\n| `ProjectName` | my-project | 项目名称 |\n| `GitBranch` | feat/awesome-feature | Git 分支 |\n| `PullRequestNumber` | PR #123 | PR 编号 |\n| `BranchChanges` | +12 -3 | 分支变更统计 |\n| `ContextRemaining` | Context 0% left | 上下文剩余 |\n| `ContextUsed` | Context 0% used | 上下文使用量 |\n| `Model` | gpt-5.2-codex | 当前模型 |\n| `ModelWithReasoning` | gpt-5.2-codex medium | 模型及推理级别 |\n\n**资料来源**：[codex-rs/tui/src/bottom_pane/status_surface_preview.rs:20-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/status_surface_preview.rs)\n\n### 8.2 状态项目分类\n\n状态项目按语义分类：\n\n| 分类 | 对应项目 | 语法高亮作用域 |\n|-----|---------|--------------|\n| `Model` | 模型名称 | `entity.name.type` |\n| `Path` | 路径信息 | `string` |\n| `Branch` | 分支信息 | `entity.name.function` |\n| `State` | 运行状态 | `keyword.control` |\n| `Usage` | 使用量统计 | `constant.numeric` |\n| `Limit` | 限制信息 | `constant.language` |\n| `Mode` | 模式切换 | `storage.modifier` |\n| `Thread` | 线程标题 | `markup.heading` |\n| `Progress` | 任务进度 | `markup.inserted` |\n\n**资料来源**：[codex-rs/tui/src/bottom_pane/status_line_style.rs:30-60](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/status_line_style.rs)\n\n## 9. 序列化与类型安全\n\n### 9.1 JSON Schema 生成\n\n协议类型通过 `schemars` 库自动生成 JSON Schema：\n\n```rust\n#[derive(JsonSchema)]\n#[schemars(schema_with = \"crate::schema::features_schema\")]\npub features: Option,\n```\n\n### 9.2 TypeScript 类型导出\n\n使用 `serde` 和 `ts` 属性导出 TypeScript 类型：\n\n```rust\n#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"v2/\")]\npub struct AppInfo { ... }\n```\n\n## 10. 总结\n\nCodex 的协议层设计遵循以下原则：\n\n1. **类型安全**：使用 Rust 强类型系统确保协议转换的正确性\n2. **版本管理**：支持 V1 和 V2 协议版本共存\n3. **分层设计**：清晰的协议层次结构，便于维护和扩展\n4. **双向转换**：支持 `codex_app_server_protocol` 与 `codex_protocol` 之间的无缝转换\n5. **可扩展性**：通过可选字段和枚举变体支持功能扩展\n\n---\n\n\n\n## 核心Agent模块\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [执行系统](#page-execution), [技能系统](#page-skills)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [codex-rs/core/src/lib.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/lib.rs)\n- [codex-rs/core/src/agent/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/agent/mod.rs)\n- [codex-rs/core/src/client.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/client.rs)\n- [codex-rs/core/src/session/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/session/mod.rs)\n- [codex-rs/core/src/tools/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/mod.rs)\n- [codex-rs/core/src/goals.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs)\n- [codex-rs/core/src/context/environment_context.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs)\n- [codex-rs/config/src/state.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs)\n- [codex-rs/config/src/profile_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs)\n- [codex-rs/tui/src/slash_command.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs)\n
\n\n# 核心Agent模块\n\n## 概述\n\nCodex CLI 的核心Agent模块是整个系统的中枢组件，负责协调用户交互、工具调用、上下文管理和会话生命周期。该模块采用 Rust 实现，运行于本地计算机，提供零依赖的安装体验。\n\n资料来源：[codex-rs/README.md:1-15]()\n\n## 模块架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n subgraph \"核心层\"\n A[Agent] --> B[Client]\n A --> C[Session]\n A --> D[Tools]\n end\n \n subgraph \"上下文层\"\n C --> E[EnvironmentContext]\n C --> F[Goals]\n end\n \n subgraph \"配置层\"\n G[Config] --> C\n G --> A\n end\n \n subgraph \"UI层\"\n H[TUI] --> A\n H --> C\n end\n```\n\n### 核心模块职责\n\n| 模块 | 职责 | 主要文件 |\n|------|------|----------|\n| Agent | 主控制逻辑、任务调度、决策 | `core/src/agent/mod.rs` |\n| Client | 与后端API通信、协议处理 | `core/src/client.rs` |\n| Session | 会话状态管理、历史记录 | `core/src/session/mod.rs` |\n| Tools | 工具注册、调用、结果处理 | `core/src/tools/mod.rs` |\n| Goals | 目标跟踪、预算管理 | `core/src/goals.rs` |\n\n资料来源：[codex-rs/core/src/lib.rs]()\n\n## Agent主模块\n\n### 主控制流程\n\nAgent模块作为协调者，处理用户输入并生成响应：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[解析命令]\n B --> C{命令类型}\n C -->|工具调用| D[工具选择]\n C -->|聊天| E[模型推理]\n D --> F[执行工具]\n E --> G[生成响应]\n F --> H[结果处理]\n H --> G\n G --> I[渲染输出]\n```\n\n### 任务执行状态\n\nAgent维护任务执行的状态机：\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: 初始化\n Idle --> Running: 接收任务\n Running --> WaitingApproval: 需要确认\n WaitingApproval --> Running: 批准\n WaitingApproval --> Cancelled: 拒绝\n Running --> Paused: 暂停/恢复\n Paused --> Running: 恢复\n Running --> Completed: 任务完成\n Completed --> Idle: [*]\n Cancelled --> Idle: [*]\n```\n\n资料来源：[codex-rs/core/src/agent/mod.rs]()\n\n## Client客户端模块\n\n### API通信机制\n\nClient模块负责与OpenAI后端服务通信，采用Protocol Buffers定义的协议：\n\n```rust\n// 风险级别映射\nGuardianRiskLevel::Low\nGuardianRiskLevel::Medium \nGuardianRiskLevel::High\nGuardianRiskLevel::Critical\n```\n\n资料来源：[codex-rs/tui/src/chatwidget.rs:1-30]()\n\n### 请求/响应处理\n\nClient支持多种API交互模式：\n\n| 模式 | 描述 | 用途 |\n|------|------|------|\n| 标准对话 | 同步请求-响应 | 日常交互 |\n| 流式响应 | Server-Sent Events | 实时输出 |\n| 工具调用 | Tool Use协议 | 代码执行 |\n\n## Session会话管理\n\n### 会话生命周期\n\n会话模块管理Codex的完整交互周期：\n\n```mermaid\ngraph TD\n A[创建会话] --> B[加载配置]\n B --> C[初始化环境]\n C --> D[处理消息]\n D --> E{任务状态}\n E -->|完成| F[保存会话]\n E -->|暂停| G[保存草稿]\n E -->|失败| H[记录错误]\n F --> I[会话结束]\n G --> J[可恢复]\n H --> I\n```\n\n### 配置层级\n\n会话使用分层配置系统，按优先级从低到高：\n\n| 层级 | 来源 | 覆盖方式 |\n|------|------|----------|\n| 系统配置 | `/etc/codex/config.toml` | 不可覆盖 |\n| 用户配置 | `~/.config/codex/config.toml` | 可覆盖 |\n| 项目配置 | `.codex/config.toml` | 可覆盖 |\n| 会话标志 | 命令行参数 | 最高优先级 |\n\n资料来源：[codex-rs/config/src/state.rs:1-50]()\n\n### 配置配置文件结构\n\n```toml\n[profile.default]\nmodel = \"gpt-4o\"\ninclude_apply_patch_tool = true\ninclude_permissions_instructions = true\ninclude_environment_context = true\n\n[profile.default.tui]\nsession_picker_view = \"grid\"\n\n[profile.default.features]\nexperimental_unified_exec = true\n```\n\n资料来源：[codex-rs/config/src/profile_toml.rs:1-80]()\n\n## Tools工具系统\n\n### 工具注册与调用\n\nTools模块提供Codex的扩展能力：\n\n| 工具类别 | 功能 | 配置项 |\n|----------|------|--------|\n| 文件操作 | 读取、写入、编辑文件 | `include_apply_patch_tool` |\n| 权限管理 | 访问控制、审批流程 | `include_permissions_instructions` |\n| 应用集成 | Apps指令 | `include_apps_instructions` |\n| 协作模式 | 多人协作 | `include_collaboration_mode_instructions` |\n\n资料来源：[codex-rs/config/src/profile_toml.rs:50-70]()\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as Agent\n participant T as Tools\n participant S as 沙箱\n \n U->>A: 发送请求\n A->>T: 选择工具\n T->>S: 执行命令\n S-->>T: 返回结果\n T-->>A: 工具响应\n A-->>U: 生成回复\n```\n\n## Goals目标系统\n\n### 目标跟踪机制\n\nGoals模块管理长时间运行任务的进度和预算：\n\n```rust\n// 预算限制提示模板\nstatic BUDGET_LIMIT_PROMPT_TEMPLATE: LazyLock