你在 Codex cloud 里选一个 org repo，结果报 unable to clone 或 Repository not found。明明你登录 GitHub 时这个 repo 就在那里——但 Codex 看不到。这几乎从来不是 Codex 的 bug，而是 GitHub App 权限没配齐。
最快的修法（覆盖约 80% 的情况）： 打开 https://github.com/settings/installations，确认 ChatGPT Codex Connector（由 OpenAI 发布）这个 App 已经装在拥有该 repo 的 org 上，再进它的配置页，确认这个 repo 在 Repository access 里被勾上。等约 30 秒，回 Codex 重新选一次 repo。如果 org 强制 SAML，你还得给 App 单独授权 SSO（见 Step 4）。下面按优先级排列。
这个 App 的正式名字就叫「ChatGPT Codex Connector」——在 installations 列表里要找的是它，而不是单独的「Codex」字样。Codex 需要三层独立的 GitHub 权限同时对齐：你的 user OAuth 授权、org 上的 App 安装、以及 App 的仓库选择。绝大多数报错，都是其中某一层少勾了一个框。
你属于哪一种情况？
| 症状 | 最可能的原因 | 跳到 |
|---|---|---|
| Codex 的 repo 选择器里根本看不到这个 org | Codex Connector App 从没装到这个 org | Step 1 |
| org 出现了，但唯独这个 repo 缺失 | repo 不在「Only select repositories」白名单里 | Step 2 |
之前能用，突然报 Repository not found | user OAuth / SSO 授权过期了 | Step 3 |
| 企业 org，装了 App 还是看不到 repo | App 的 SAML SSO 没授权 | Step 4 |
报 submodule update failed（不是 clone failed） | submodule 所在 repo 在授权范围外 | Step 5 |
| 全新、没有 commit 的 repo clone 失败 | 空 repo 还没有默认分支 | 见「空 repo 说明」 |
| 看得到 org，但里面一个 repo 都没有 | EMU org——必须由 org owner 装 App | Step 1（管理员） |
常见原因，按命中率从高到低
1. Codex Connector App 没装到 org 上
你只在个人账号上授权了 Codex，但 repo 在 acme-corp 下。这个 App 每个 org 都要单独装一次。
如何判断：打开 https://github.com/organizations/acme-corp/settings/installations。里面没有 ChatGPT Codex Connector，就是这个原因。
2. Repo 不在 App 的 Repository access 白名单里
App 装在 org 上了，但配置成 Only select repositories，而你这个 repo 没被勾。新建 repo 后特别常见——GitHub 不会把新 repo 自动加进「selected」白名单。
如何判断：打开 Codex 安装页看 Repository access。如果显示 Only select repositories (N) 而你的 repo 不在列表里——勾上它。
3. user OAuth 或 SSO 授权过期
用户级授权（与 App 安装分开）会按你所在 org 的 SSO 会话策略到期。一旦过期，即便 App 还装着，Codex 对这个 org 也会被当成「未登录」，昨天还能用的 repo 就开始报 Repository not found。
如何判断：在 Codex 里 Disconnect 再重新连接 GitHub。如果之前消失的 org 或 repo 突然又出现了，说明你的授权确实失效过。
4. App 的 SAML SSO 没授权
强制 SAML 的企业 org，要求每个用户在 活跃的 SSO 会话下给 App 单独授权一次。按 GitHub 官方文档，如果你所在 org 启用了 SSO，而你授权 App 后仍看不到它的资源，就得先开一个新的 SSO 会话、再重新授权这个 App。在你完成之前，该 repo 对 Codex 是隐形的。
如何判断：进 org 的 Settings → Third-party Access → GitHub Apps（点你的头像 → Your organizations → 选这个 org → Settings，然后在侧边栏「Third-party Access」下找），看 Codex 是不是有一条待授权的 SSO grant。也可能要先让 org owner 把这个 App 加白名单。
5. submodule 在授权范围外
Codex 把主 repo clone 下来了，但 task 引用的 submodule 指向 另一个 Codex 够不到的私有 repo。报错是 submodule update failed，不是 clone failed。
如何判断：仔细看报错原文。submodule 失败和顶层 clone 失败是两码事。
6. EMU / Enterprise Managed Users org
对使用 Enterprise Managed Users (EMU) 的 org，必须由 org owner 先为整个 org 安装 ChatGPT Codex Connector App，普通成员才能在 Codex cloud 里连接 repo。截至 2026 年 6 月，普通成员无法自助安装——你会看到 org，但里面一个 repo 都没有。
如何判断：同 org 下的 public repo 用普通 token 本应可见，但 Codex 显示这个 org 的 repo 列表为空、也没有你能点的「Configure」入口。让 org owner 去装 Codex。
套餐说明（通常不是病因）。 截至 2026 年 6 月，Codex（含 cloud 任务）在每一个 ChatGPT 档位都包含：Free、Go、Plus、Pro、Business、Edu、Enterprise。（这和产品早期不同——那时 cloud 是 Plus 及以上才有。）cloud 任务从你套餐的额度里扣，且比本地运行消耗更快，Free 档额度卡得很紧。所以如果是「用量超限」导致任务起不来，报错形态不一样：你会看到配额/限额提示，而不是
unable to clone或Repository not found。如果你看到的是 clone / not-found 这类错，那是下面某一层权限的问题，不是套餐问题。
最短修复路径
按收益从高到低排列。Step 1–3 解决最常见的情况（org 没装、或 scope 配错）。
Step 1：确认 App 装在正确的 org 下
打开：
https://github.com/settings/installations这里列出所有装了 ChatGPT Codex Connector 的 org / 账号。如果目标 org 不在：
- 在任意一个已有安装上点 Configure，或打开
https://github.com/apps/chatgpt-codex-connector点 Install。 - 选拥有你 repo 的那个 org。
- 批准安装。
你不是 org owner 的话，得让管理员批准。把 https://github.com/apps/chatgpt-codex-connector 发给他——他会看到一键 Install 按钮（如果 org 限制了 App 安装，则是 Request 按钮）。EMU org 只有 org owner 能完成这一步。
Step 2：把这个 repo 加进 Repository access
装好后，进入这个 org 的 Codex 安装，滚到 Repository access：
○ All repositories
● Only select repositories
[ ] acme-corp/marketing-site
[x] acme-corp/api-server ← 需要勾这个框
[ ] acme-corp/internal-tools勾上 → 点 Save → 等约 30 秒让 GitHub 同步 → 回 Codex 重试。
经常加新 repo 的团队，可以直接切到 All repositories，省去每个 repo 手动勾一次的麻烦，代价是权限放宽。
Step 3：重新跑一次 OAuth / SSO 授权
即便 App 配置正确，你的 user 授权也可能已经过期。在 Codex 里：
- Settings → Connected accounts → GitHub → Disconnect。
- 重新连接。 这会触发一次全新的 OAuth 授权（如果 org 强制 SSO，还会触发一次 SAML 授权）。
- 企业 SSO 用户要留意 SAML 同意页——它常以弹窗形式打开，很容易漏点，或被弹窗拦截器挡掉。
Step 4：授权 SAML SSO（仅企业）
org 强制 SAML 时，光装 App 不够。访问：
https://github.com/orgs/acme-corp/sso?return_to=%2Fsettings%2Finstallations用 org 的身份提供商（IdP）完成授权。这会生成 Codex 需要的 SSO grant，它才能拿你的 token 在这个 org 里操作。授权当下你必须有一个活跃的 SSO 会话——如果你几周前授权过、会话已过期，就得重做一遍。
Step 5：碰到 submodule，把 submodule 的 repo 也一并授权
如果报错是 submodule update failed，说明 submodule 在另一个 repo 里。把那个 repo 也单独加进 Codex：
# 查看 submodule 的 URL
git config --file .gitmodules --get-regexp url
# 示例输出：
# submodule.shared-types.url git@github.com:acme-corp/shared-types.git把 acme-corp/shared-types 加进同一个 Codex 安装（如果 submodule 在另一个 org，就给那个 org 再装一次）。
Step 6：临时绕过——在 setup 脚本里用细粒度 PAT clone
如果你一时搞不定 App 权限、又必须先把 task 跑起来：生成一个限定到该 repo 的细粒度 Personal Access Token，把它作为 Secret 加进 Codex 环境：
GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
Repository access: Only select repositories → [你的 repo]
Permissions: Contents (read), Metadata (read) # 如果 Codex 要开 PR，再加 Pull requests (read/write)在 Codex 的 Environment 里把它存为名为 GITHUB_TOKEN 的 Secret，然后 在 setup 脚本里 用这个 token clone：
git clone https://x-access-token:$GITHUB_TOKEN@github.com/acme-corp/api-server.git重点：在 Codex cloud 里，Secret 只在任务执行时解密，并且在 agent 阶段开始前会被移除（这是刻意设计，防止 agent 把凭据泄漏进输出或生成的代码）。相对地，环境变量会在整个任务期间（含 agent 阶段）保持有效——但别把明文 token 塞进普通变量，因为 agent 能读到。所以要 在 setup 脚本里 趁 Secret 还在时完成 clone；如果 agent 后续还要 push / fetch，就在 setup 阶段配一个 git 凭据助手（例如把 token 写进 ~/.git-credentials 再执行 git config --global credential.helper store），让已经 clone 下来的工作副本保持已认证状态，而不必把 $GITHUB_TOKEN 暴露给 agent。PAT 只当应急——长期、可审计的正解是装 App。
空 repo 说明
一个全新、还没有任何 commit 的 repo 没有默认分支，即便权限都对，Codex 也会 clone 失败。先 push 一个 commit，再重试：
git commit --allow-empty -m "chore: initialize repo" && git push origin main如何确认已经修好
- 在 Codex 的 repo 选择器里，org 和 repo 现在都出现了、也能选中。
- 启动一个 task——运行日志显示容器在 check out 你的分支/SHA，并且没有
clone failed这一行。 - 如果你用了 Step 6，setup 脚本的日志会显示 clone 成功，进入 agent 阶段时 repo 已经在磁盘上。
如果安装、白名单、SSO 授权都做完了，选择器里却还看不到 repo，那通常是同步缓存在作怪——等一分钟刷新一下，或者把 GitHub Disconnect 再重新连接一次，强制刷新。
预防建议
- 新建 repo 时立刻把它加进 Codex 的 access list——写进你的「建仓 checklist」。
- 活跃团队直接把 org 上的 Codex 设成 All repositories，新 repo 自动包含，省去手动勾。
- SSO 会话策略短的话，记得周期性重跑 Codex 的 OAuth/SSO 授权，加个日历提醒会更稳。
- 把 SAML SSO 授权这一步写进 onboarding 文档——每个企业开发者都会踩一次。
- 带 submodule 的 monorepo，提前把每个 submodule 所在 org 都授权给 Codex。
- 别拿长效 PAT 当主授权——它比 App install 更容易泄漏，而且不会出现在 App 的审计日志里。
FAQ
为什么 repo 在浏览器里看得到，在 Codex 里却看不到？ 你的浏览器会话和 Codex 走的是不同的权限路径。浏览器用的是你登录的个人账号；Codex 用的是 GitHub App 安装加上你的 OAuth/SSO 授权。所以 repo 可能对你完全可见，但 App 对它毫无访问权。先查 App 安装（Step 1）和它的仓库白名单（Step 2）。
Codex clone 私有 repo 需要付费套餐吗？
不需要。截至 2026 年 6 月，Codex（含 cloud 任务）在每个 ChatGPT 档位都有——Free、Go、Plus、Pro、Business、Edu、Enterprise。套餐只限制你 能跑多少：cloud 任务从包含额度里扣，Free 档卡得很紧。撞到额度上限时，提示是用量/限额信息，而不是 unable to clone 或 Repository not found，所以本文这些 clone 报错是权限问题，不是套餐问题。
我是 org 成员、不是 owner——为什么装不了 Codex？
很多 org（尤其是 Enterprise Managed Users / EMU）只允许 org owner 安装或批准 GitHub App。把安装链接 https://github.com/apps/chatgpt-codex-connector 发给一个 owner，他为 org 装好后，你的 repo 就会出现。
昨天还能 clone，今天突然报 Repository not found，发生了什么？
几乎都是你的 SSO 会话或 OAuth 授权过期了（Step 3），或者这个 repo 被移动/改名/转私有到了另一个 App scope 下。在 Codex 里把 GitHub Disconnect 再重新连接；org 强制 SSO 的话再重新授权一次 SSO（Step 4）。
我的 PAT 在本地能用，Codex 却还是 clone 不了，为什么？
在 Codex cloud 里，Secret（包括 GITHUB_TOKEN 这个 PAT）只对 setup 脚本可用，agent 运行前就被剥离了。所以要在 setup 脚本里完成带认证的 git clone、或配好凭据助手，而不是把 token 写在 task prompt 里。
我改完之后，重新运行却不生效。 Codex 会缓存容器状态、最长约 12 小时并复用它。按 Codex cloud 文档，当你改动 setup 脚本、maintenance 脚本、环境变量或 secret 时，缓存会自动失效——但 GitHub 上纯粹的权限改动可能不会触发失效。修好 GitHub 访问后，进环境的 settings 页点 Reset cache（或改一下 setup 脚本里的内容），强制下次运行做一次干净 checkout。在 Business/Enterprise 上，缓存是在所有有权访问该环境的人之间共享的，所以同事一次过期的运行可能会掩盖你的修复。