Codex 中转站项目环境教程：灵能API CC Switch 依赖安装、环境切换与验证
同一台电脑上不同项目可能使用不同 Node.js、Python、依赖版本和启动命令。如果 Codex 读错目录或复用了旧环境，常见结果就是安装失败、测试失败或修改后无法运行。本文以灵能API和 CC Switch 为基础，整理项目环境检查、依赖安装、运行验证和环境隔离流程。
先把项目环境分成三层
项目运行环境可以分成工具层、依赖层和配置层。工具层是 Node.js、npm、Python 或其他命令；依赖层是项目安装的包和版本；配置层则包括 API 地址、模型、令牌和项目环境变量。三层混在一起时，出现错误很难定位。
让 Codex 执行项目命令前，先确认当前目录和环境版本，再让它读取依赖文件。
- 工具层：确认系统能找到正确命令。
- 依赖层：按照项目文件安装，不凭记忆升级。
- 配置层：本地秘密与项目模板分开保存。
第一步：确认灵能API模型和项目线路
进入灵能API页面或控制台，确认当前 Model ID、接口地址和令牌状态。项目环境问题不应该与模型线路问题混在一起，因此建议先固定一张已知可用的 Codex 配置卡。
- 官网入口：https://www.lnsns.com/
- *ase **L：按照当前接口说明填写。
- Model ID：从当天列表复制。
- API Key：使用项目或设备专用令牌。
️ 第二步：用 CC Switch 固定项目线路
打开 CC Switch 的 Codex 页面，创建“灵能API-Codex-项目环境”配置卡。项目环境排查期间不要频繁更换模型，先保证线路稳定，再处理依赖和命令。
卡片名称要写明项目用途，*ase **L 和 Model ID 从当前服务信息复制。复制已有卡片后重新核对 API Key，不要把共享模板里的占位符当成真实配置。
️ 第三步：进入项目先检查命令和目录
Get-Location
node -v
npm -v
python --version
git status不需要的命令可以跳过，重点是确认当前工作目录和项目使用的工具版本。不要从其他项目的终端窗口直接继续，因为窗口可能仍然加载旧 PATH 和环境变量。
如果项目使用版本管理文件，例如 package.json、package-lock.json、pyproject.toml 或 requirements.txt，先让 Codex 读取这些文件，再决定安装命令。
✍️ **步：让 Codex 先解释依赖安装计划
请阅读 package.json 和锁定文件。
说明项目需要的运行时、安装命令和启动命令。
先给计划，不要执行安装，不要修改依赖版本。安装依赖可能修改锁定文件、下载大量内容或触发脚本。先让 Codex 解释影响范围，确认命令适合当前项目，再逐条执行。
- 是否使用正确的包管理器。
- 是否需要指定 Node/Python 版本。
- 安装是否会执行项目脚本。
- 失败后如何清理和恢复。
第五步：按项目文件安装，不直接升级全部依赖
依赖安装应优先遵循项目已经提交的锁定文件。不要因为某个包版本较旧，就让 Codex 一次性升级整个依赖树。升级属于另一项变更，需要单独建立分支、记录原因并运行完整测试。
npm ci
# 或按照项目文档执行指定安装命令
npm test
npm run *uild如果项目使用其他包管理器，以项目文件和文档为准。安装完成后先检查 Git diff，确认没有无关文件被修改。
✅ 第六步：用最小运行命令验证环境
依赖安装成功不代表项目可以运行。先执行项目提供的最小检查或单元测试，再执行构建，最后才启动完整开发服务。每一步都有结果后再继续。
如果项目命令失败，先看错误发生在依赖安装、环境变量还是代码本身。不要因为 Codex 能返回回答，就认为项目运行环境已经正确。
- 第一层：版本和依赖检查。
- 第二层：局部测试或类型检查。
- 第三层：构建和启动命令。
第七步：项目环境变量和 API 配置分开
Codex 的 API 配置属于客户端线路，项目自己的环境变量属于项目运行时。两者可以同时存在，但不应互相覆盖。项目模板只保留变量名和占位符，真实值在本机设置。
# .env.example
APP_ENV=development
CODEX_MODEL=<项目使用的模型>
CODEX_API_KEY=<本机私密值>出现‘本地能用、团队成员不能用’时，优先比较变量名、版本和启动目录，不要直接共享你的完整 Key。
- 检查 .env 是否在忽略列表中。
- 检查 PowerShell 当前变量是否覆盖项目配置。
- 检查启动脚本是否指向正确环境。
第八步：启动 Codex 前***连接测试
项目依赖和配置完成后，保存并启用目标卡片，关闭旧 Codex 和 PowerShell，再启动新进程。先在空目录做只读任务，确认线路没有被项目环境变量覆盖。
mkdir codex-project-env-check
cd codex-project-env-check
codex测试成功后，再回到项目目录，让 Codex 只读取一个指定文件并解释依赖。确认工作区和线路都正确，再让它执行安装、测试或修改命令。
项目环境常见问题
排错时记录项目目录、命令、错误码和卡片名称，不记录完整 API Key 和项目敏感内容。
- 命令不存在：检查 PATH 和版本管理工具。
- 依赖安装失败：检查包管理器、锁定文件和运行时版本。
- 401：检查当前 CC Switch 卡片和 API Key。
- 403：检查额度、模型权限和分组。
- 404：检查 *ase **L 是否重复 /v1。
- model not found：复制当前 Model ID。
- 本地和团队结果不同：比较目录、版本和变量名。
项目环境验收清单
把环境检查、依赖安装和线路验证分开，Codex 才能更稳定地参与不同项目的开发工作。
- 当前 PowerShell 目录正确。
- Node/Python 和包管理器版本符合项目要求。
- 依赖安装遵循锁定文件。
- 项目环境变量与 Codex API 配置分开。
- CC Switch 卡片和模型已经固定。
- 空目录和项目局部读取测试通过。
- API Key 没有进入模板、仓库和日志。