Codex 中文手册

简体中文

繁體中文

简体中文

繁體中文

外观

交流群即将上线

常见问题 FAQ ​

安装与登录 ​

codex 装完了但命令找不到 ​

安装脚本把二进制放在一个目录里，但那个目录不在你的 PATH 上。 重开一个终端先试试；还不行就看安装脚本的输出，它会告诉你装到哪了， 把那个目录加进 PATH。用 npm 或 Homebrew 装一般不会有这个问题。

该用 ChatGPT 账号还是 API 密钥登录 ​

两条路的差别不只是计费。用 ChatGPT 账号，你的使用受 ChatGPT 工作空间权限、 RBAC 和 ChatGPT Enterprise 的数据保留/驻留设置约束；用 API 密钥， 适用的是你所属 API 组织的设置。

另外 Codex 云端必须用 ChatGPT 登录，API 密钥用不了， 而且用 API 密钥时部分功能可能不可用。

公司环境里基本上是被决定好的：管控挂在 ChatGPT 工作空间上，就得用账号登录。 详见 快速上手 02。

一台机器能同时装 CLI、IDE 扩展和桌面应用吗 ​

能，登录状态各自独立。而且 CLI 和 IDE 扩展共用同一套配置层 （~/.codex/config.toml），MCP 服务器配一次两边都能用。

权限与沙盒 ​

--sandbox 和 --ask-for-approval 有什么区别 ​

一个管能力上限，一个管打断频率：

  • --sandbox：它执行命令时技术上能做到什么（能写哪、能不能联网）
  • --ask-for-approval：哪些动作必须先停下来问你

-a never 不等于放开权限——沙盒该拦还是拦。真正放开是 --sandbox danger-full-access。 完整对照见 快速上手 04。

默认能联网吗 ​

不能。默认情况下智能体在关闭网络访问的状态下运行。 workspace-write 也默认禁网，要开得显式配：

toml
[sandbox_workspace_write]
network_access = true

「工作空间」到底包括哪些目录 ​

当前目录，加上 /tmp 之类的临时目录。拿不准就在会话里 /status 看一眼。

它会不会改我的 .git ​

不会。workspace-write 下这几个路径受递归只读保护：

  • <可写根目录>/.git（是 gitdir: 指针文件的话，解析出的真实目录也保护）
  • <可写根目录>/.agents
  • <可写根目录>/.codex

所以 git diff / git checkout 这条退路始终有效。

审批提示太多，但我又不想直接 never ​

两个中间选项：

toml
approval_policy = "on-request"
approvals_reviewer = "auto_review"

符合条件的审批交给审查智能体，按策略放行低/中风险、拒绝严重风险。 代价是额外的模型调用，会多花额度。

或者用细粒度策略，让某些类别保持交互式、其余自动拒绝：

toml
approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = false, skill_approval = false } }

--yolo 能用吗 ​

能用，但想清楚在哪用。在一个随时能扔掉的容器里没什么问题； 在你自己的开发机、在有未提交改动的仓库里用，就是拿工作赌它这次不会跑错命令。

真需要放开，先把工作放进 Dev Container 或 Git 工作树。

上下文与会话 ​

聊着聊着它就变笨了 ​

上下文被中间产物填满了。按这个顺序想：任务换了就开新会话； 日志和探索结果主线程不需要就拆给子智能体； 约定每次重讲就写进 AGENTS.md；确实是长任务，才去调压缩阈值。 详见 快速上手 06。

怎么接着上一次的会话 ​

bash
codex resume                          # 交互式
codex exec resume --last "..."        # 非交互式，接最近一次
codex exec resume <SESSION_ID> "..."  # 指定会话

子智能体会继承我的权限设置吗 ​

会，而且是运行时覆盖优先。你在会话里用 /permissions 改过的设置、 甚至 --yolo，启动子智能体时会重新应用，即使自定义智能体文件里设了别的默认值。

所以要限制子智能体，得先把父级轮次的权限选对。

团队使用 ​

同事那儿的行为跟我不一样 ​

先查这三件事：

  1. 项目信任了吗？ 不信任的话 .codex/ 层（配置、钩子、规则）整个跳过。
  2. 他的 ~/.codex/config.toml 里有什么？ 用户配置优先级低于项目配置，但仍会生效。
  3. 他敲了什么命令行标志？ CLI 标志优先级最高，盖过所有配置文件。

优先级从高到低：CLI 标志 → 项目配置 → 配置方案 → 用户配置 → 系统配置 → 内置默认值。

怎么禁止团队用 danger-full-access ​

管理员下发 requirements.toml，用权限配置方案：

toml
default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true

不在允许列表里的就用不了。见 进阶 05。

CI 里怎么放 API 密钥 ​

如果工作流会签出或运行仓库控制的代码，别把密钥设成作业级环境变量—— 构建脚本、测试、依赖钩子都能读到。

GitHub Actions 上用官方的 openai/codex-action，别自己装 CLI 再传密钥。 更好的做法是把生成补丁和开 PR 拆成两个作业：拿密钥的没写权限， 有写权限的看不到密钥。完整例子见 案例 03。

关于本站 ​

「官方文档」区的内容是你们翻译的吗 ​

不是。OpenAI 自己同时维护 zh-Hans 和 zh-Hant 两套中文文档， 本站直接抓官方对应语言的原文，没有经过任何机器翻译，繁体也不是从简体转过去的。 每一页顶部都有回官方原文的链接。

那繁体的教程部分呢 ​

「快速上手 / 进阶 / 实战案例 / 参考」这几十篇是我们自己写的简体原稿， 繁体由 OpenCC 转换。用词已经逐条对齐官方 zh-Hant 的译法—— 比如「权限」保持「權限」而不是 OpenCC 默认的「許可權」， 「插件」写全「外掛程式」，「会话」用「工作階段」。 对照表在 scripts/i18n-terms.mjs。

内容多久更新一次 ​

镜像靠 npm run fetch 重新抓，不是实时的。产品更新很快， 发现和官方对不上时以官方页面为准——每页顶部都有链接。

有些官方页面这里为什么没有 ​

两类：一类是分区落地页（比如官方的 Codex CLI 首页）， 它们在 Markdown 孪生页里被压成了没有层级的卡片文案，代码块全丢了， 镜像过来只会误导人，所以跳过，本站用自己写的分区索引代替； 另一类是内容由前端组件渲染、Markdown 里根本没有正文的页面（比如官方术语表）， 这类我们自己重写了一份，见术语表。

非官方社区教程 · 「官方文档」区为 learn.chatgpt.com 中文原文镜像 · 以官方页面为准

Copyright © 2026 Codex 中文手册