Codex VS Code 插件为何报错“Add a project to use Codex”？

作者：袖梨 2026-09-12

Codex VS Code 插件报错“Add a project to use Codex”，通常表示当前窗口没有附加可用的项目文件夹，而不是账号或模型故障。Codex 需要明确的工作目录来读取文件、运行命令和写入修改；空窗口、只打开单个文件、打开文件系统根目录，或远程窗口未选择具体项目时，都可能缺少这个上下文。

先打开真实项目目录

在 VS Code 中选择“文件”里的“打开文件夹”，选中项目自己的目录。优先选择包含源码、配置文件或 Git 仓库的具体文件夹，不要直接选择磁盘根目录或整个主目录。

也可以从终端进入项目后启动：

cd /path/to/your-project
code .

官方 IDE 文档的入门流程同样要求先打开项目，再让 Codex解释代码库、进行修改或调试问题。

在 Codex 面板中添加项目

  1. 从活动栏打开 Codex 面板。
  2. 若图标不可见，从命令面板运行 Codex: Open Codex Sidebar。
  3. 在项目选择界面勾选刚打开的文件夹。
  4. 选择添加项目并继续。
  5. 确认输入区附近显示正确的项目名称和 Git 分支。

发送一个只读测试请求，例如让 Codex列出项目顶层目录。错误提示消失、项目名称正确且回答引用当前工作区文件，才说明项目上下文已经建立。

确认不是只打开了单个文件

从文件管理器双击一个源码文件，VS Code 可能以无文件夹窗口打开。此时编辑器能显示文件，却没有稳定的工作区根目录。

检查资源管理器顶部是否显示项目文件夹。若只看到孤立文件，应使用“打开文件夹”重新打开项目，而不是继续在当前空窗口重试。

不要把文件系统根目录当项目

在本地或 Remote-SSH 中直接打开 /，会给工具过大的文件范围，也可能无法被插件当作有效项目边界。应选择具体子目录，例如：

/home/your-name/projects/my-app
/workspaces/my-service
C:Usersyour-namesourcemy-app

项目根目录应让构建、测试和版本控制命令具有明确含义。目录太宽不仅可能触发项目识别问题，也会扩大文件扫描和命令作用范围。

远程环境要选远程路径

Remote-SSH、WSL、Dev Container 和 Codespaces 窗口使用另一套文件系统。应在当前远程环境中打开真实项目目录，而不是选择本机路径或远程根挂载点。

环境应选择的项目常见错误
Remote-SSH远程主机中的仓库目录只连接主机但未打开文件夹
WSL发行版内的项目目录混用 Windows 与 Linux 路径
Dev Container容器内挂载的工作区打开容器根目录
Codespaces当前 Codespace 的仓库目录扩展只装在本地端

检查 VS Code 左下角的远程指示器，并在集成终端运行 pwd。资源管理器、终端和 Codex 选择的项目应属于同一环境。

检查扩展安装位置

VS Code 远程扩展可以安装在本地端或远程端。若 Codex 面板在本地窗口存在、进入远程窗口后消失，应打开扩展详情，确认扩展已经在当前远程目标中启用。

安装或启用后重新加载窗口，再打开具体远程项目。不要因为本地扩展列表显示“已安装”，就假设远程扩展宿主也已经加载它。

处理多根工作区

多根工作区同时包含多个文件夹，Codex 可能无法自动判断哪个根目录是当前项目。最简单的诊断方法是新开一个只包含目标文件夹的窗口。

  1. 记录当前工作区中的所有根目录。
  2. 单独打开需要操作的那个目录。
  3. 在 Codex 面板重新添加该项目。
  4. 确认提示能够发送后，再回到多根工作区逐个添加。

项目已添加但错误仍存在

先确认当前窗口仍打开原文件夹。新建空窗口、重新连接远程主机或容器重建后，原来的项目选择可能不再对应当前路径。

随后运行 Developer: Reload Window，重新打开 Codex 面板并再次选择项目。若仍失败，保存 Codex 和扩展宿主日志，再测试一个全新的本地 Git 项目：

mkdir -p /tmp/codex-project-check
cd /tmp/codex-project-check
git init
printf '# Testn' > README.md
code .

临时项目可以添加而原项目不能添加时，重点检查原项目路径、权限、工作区配置和远程挂载；所有项目都失败时，再检查扩展状态和登录链路。

用权限检查排除不可访问目录

pwd
ls -ld .
test -r . && echo readable
test -w . && echo writable
git rev-parse --show-toplevel 2>/dev/null || true

Codex 是否允许写入还受沙箱和审批策略约束，但项目目录至少需要能被当前 VS Code 扩展宿主识别和读取。网络挂载断开、容器路径变化或目录权限异常都会使已保存的项目失效。

区分相似但不同的故障

现象优先处理
明确显示 Add a project打开文件夹并在面板添加项目
Codex 图标完全不存在用命令面板打开并检查扩展安装位置
面板卡在 Logo 或空白检查 WebView、扩展宿主和 Codex 日志
项目已显示但提示发送失败检查错误详情、网络和认证
只有旧项目失效重新打开实际路径并核对权限

不要用过度清理替代诊断

  • 不要删除整个 ~/.codex 来处理单纯的项目未选择提示。
  • 不要因为项目未附加就反复退出 ChatGPT 登录。
  • 不要把整个主目录或磁盘根目录添加为方便的替代方案。
  • 不要在未备份时删除 VS Code 用户数据。
  • 不要在远程窗口中只检查本地扩展状态。

完成修复后的验收

  1. 关闭并重新打开 VS Code，确认目标项目仍在资源管理器中。
  2. 打开 Codex 面板，确认显示正确项目与分支。
  3. 发送只读请求并验证回答使用当前项目文件。
  4. 创建 Git 检查点后，再执行一次小范围编辑任务。
  5. 在远程环境中重新连接一次，确认项目仍可重新选择。

“Add a project to use Codex”本质上是缺少明确工作目录的状态提示。解决顺序应当是打开具体项目文件夹、在 Codex 面板附加它、确认本地与远程环境一致，再处理多根工作区或残留状态。只有错误在有效项目中持续出现时，才需要进入扩展日志、权限和远程安装位置的进一步排查。

相关文章

精彩推荐