你在 Codex 里选一个 org repo，结果报 unable to clone 或 Repository not found。明明你登录 GitHub 时这个 repo 就在那里——但 Codex 看不到。这几乎从来不是 Codex 的 bug，是 GitHub App 权限没配齐。
GitHub 有三层独立权限（user OAuth、App 安装、App 仓库 allowlist），Codex 三层都要齐。大多数报错都是某一层少勾了一个框。
常见原因
按命中率从高到低：
1. Codex GitHub App 没装到 org 上
你只在个人账号上授权了 Codex，但 repo 在 acme-corp 下。App 每个 org 都要单独装一次。
如何判断：打开 https://github.com/organizations/acme-corp/settings/installations——里面没有「Codex」就是这个原因。
2. Repo 不在 App 的 Repository access 白名单里
App 装在 org 上了，但配置成 “Only select repositories” 而你的 repo 没被勾。新建 repo 时常见——App 不会自动加进去。
如何判断：去 Codex 安装页看 “Repository access”，如果显示 “Only select repositories (N)” 而目标 repo 不在列表里——勾上。
3. 个人 OAuth token 过期
用户级 OAuth（与 App 安装分开）有 7-30 天的刷新周期，取决于 org 的 SSO 策略。过期后即便 App 还装着，Codex 也会把你当未登录用户。
如何判断：在 Codex 里登出再登入。如果突然多出来 org 或 repo，就是 token 失效了。
4. 企业版 SAML SSO 没单独授权
企业 org 强制 SAML——即使 App 装了，每个用户也得单独走一次 SSO 授权。没授权之前 repo 是隐形的。
如何判断：Org settings → Authentication security 看有没有 Codex 的未授权 SAML grant。可能要先让 org admin 把它加白名单。
5. Repo 属于 Codex 没覆盖的付费层
某些 GitHub Enterprise Cloud 的私有 repo 不在 Codex 免费层范围。你能看到 org 但看不到里面的 repo。
如何判断：同 org 下的 public repo 能看到、private 看不到——这是套餐层级限制，不是权限 bug。
6. 分支 / submodule 在授权范围外
Repo 能 clone，但 task 引用的 submodule 指向另一个 Codex 没权限的私有 repo。报错是 submodule update failed 而不是 clone failed。
如何判断：仔细看报错文案——submodule 错和 clone 错是两回事。
最短修复路径
按收益从高到低，前 3 步覆盖最常见的「org 没装」「scope 没勾」。
Step 1：确认 App 装在正确的 org 下
打开：
https://github.com/settings/installations会列出装了 Codex 的所有 org / 账号。如果目标 org 不在：
- 任意一个已装 install 点 “Configure”（或新建 “New installation”）。
- 选目标 org。
- 批准安装。
不是 org owner 就得让 admin 批准。把 https://github.com/apps/codex 这个链接发给他，他能一键 Install。
Step 2：把 repo 加进 Repository access
App 装好后，进入这个 org 的 Codex install，滚到 “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 流程
即便 App 正确，user token 也可能过期。在 Codex 里：
- Settings → Connected accounts → GitHub → Disconnect。
- 重新连，会触发一次新的 OAuth + SAML grant。
- 企业 SSO 用户注意弹窗里的 SAML 同意页——很容易漏点。
Step 4：授权 SAML SSO（仅企业）
org 强制 SAML 时光装 App 不够，访问：
https://github.com/orgs/acme-corp/sso?return_to=%2Fsettings%2Finstallations在你名字旁边点 “Authorize”——这给 Codex 加上一个 SSO grant，它就能用你的 token 在 org 里操作了。
Step 5：submodule 报错时单独给 submodule repo 授权
报错是 submodule update failed 时，submodule 在另一个 repo 里。把那个 repo 的 org 也加进 Codex App install：
# 看 submodule 列表
git config --file .gitmodules --get-regexp url
# 示例输出
# submodule.shared-types.url git@github.com:acme-corp/shared-types.git把 acme-corp/shared-types 加进同一个 Codex install（如果在另一个 org 就再装一次）。
Step 6：临时绕过——用 Personal Access Token
App 权限一时搞不定但 task 又必须跑，临时生成一个细粒度 PAT 限定到这个 repo，作为 Codex secret 贴进去：
Settings → Developer settings → Personal access tokens → Fine-grained tokens
Repository access: Only select repositories → [你的 repo]
Permissions: Contents (read/write), Pull requests (read/write), Metadata (read)在 Codex 里存为 GITHUB_TOKEN，setup 脚本里 git clone https://x-access-token:$GITHUB_TOKEN@github.com/...。只当应急方案，长期还是装 App。
预防建议
- 新建 repo 立刻把 Codex 加进 access list——写进 repo 创建 checklist
- 活跃团队直接把 Codex 设成 “All repositories”，省去每个新 repo 手动勾
- SSO token 寿命短的话每 30 天重跑一次 OAuth，加个日历提醒
- SAML SSO 授权步骤写进 onboarding 文档——每个企业开发者都会踩一次
- 带 submodule 的 monorepo，每个 submodule 所在 org 都要提前授权
- 别把长效 PAT 当主授权——比 App install 更容易泄漏、也不在 App 审计日志里