AI Agent / 系统课时
配置云端开发环境
配置云端开发环境
云端任务能否稳定完成,取决于环境是否可复现。本节把依赖安装、环境变量、初始化脚本和网络权限收敛成一套可验证配置,让 Codex 每次拿到仓库后都能直接进入编辑与测试,而不是把时间消耗在重复修环境上。
学习目标
- 能为仓库设计可重复执行的依赖安装与初始化步骤
- 能区分普通环境变量、敏感凭据和运行期需要的配置
- 能按最小权限原则开放云端任务所需的网络访问
理解云端环境的启动链路
一次云端任务可以理解为“准备工作区 → 初始化环境 → 运行 agent → 验证改动”。真正需要固定下来的不是某台机器,而是从干净工作区恢复到可开发状态的步骤:运行时版本、包管理器、依赖、工具、环境变量以及必要的外部域名都应显式化。

把“能启动”当作最低标准还不够。环境应该满足三个验收条件:初始化可以重复执行、失败能快速暴露、agent 无需猜测项目怎么安装依赖或跑检查。
固化依赖和初始化步骤
优先使用仓库已经提交的锁文件,例如 package-lock.json、pnpm-lock.yaml、poetry.lock。setup 脚本应做到幂等:重复执行不会破坏工作区,也不会依赖上一次任务残留的临时状态。不要在脚本里做数据库迁移、发布或写入生产系统等不可逆操作。
下面假设仓库是一个已提交 package-lock.json 的 Node.js 项目,并在云端环境中配置了非敏感变量 APP_ENV=codex-cloud。可将以下内容作为 setup 脚本:
set -euo pipefail
printf 'node=%s\n' "$(node --version)"
printf 'npm=%s\n' "$(npm --version)"
# 锁文件驱动安装,避免云端任务解析出不同依赖版本。
npm ci --silent
# 初始化阶段尽早检查必要配置,缺失时直接失败。
: "${APP_ENV:?APP_ENV must be configured}"
printf 'APP_ENV=%s\n' "$APP_ENV"预期输出
node=<VALUE>
npm=<VALUE>
APP_ENV=codex-cloud<VALUE> 会随运行时版本、依赖数量和安装速度变化。若 npm ci 失败,先修锁文件、Node 版本或私有包访问问题,不要让 agent 在任务正文里临时改安装策略。
管理变量和敏感信息
普通环境变量适合保存环境名、功能开关、测试端点等非敏感配置。令牌、私钥和私有仓库凭据不要写进 Git、AGENTS.md 或 setup 脚本正文;应放入平台提供的 secret 配置,并尽量只在初始化阶段使用。
还要注意 setup 脚本与 agent 运行阶段不是同一个 shell 会话。不要只靠 export NAME=value 假设变量一定会延续到后续阶段;需要长期可见的非敏感变量,应在云端环境设置中声明,或写入项目明确读取的配置位置。
只开放任务真正需要的网络
依赖安装和 agent 运行要分别考虑网络需求。多数项目在初始化时需要访问包仓库,而 agent 本身可能完全不需要互联网;如果任务只是修改本地代码并跑单元测试,保持 agent 网络关闭最简单。
确实需要访问外部文档或服务时,按“域名 + HTTP 方法”收紧范围。例如只读取公开 API 文档,可只放行文档域名,并优先允许 GET、HEAD、OPTIONS;不要因为一个下载动作就开放全部域名和写请求。
网络规则可以用三问快速检查:
- agent 不联网是否仍能完成任务?如果能,就不要开启。
- 必须联网时,是否能只允许一两个可信域名?
- 是否真的需要
POST、PUT、PATCH或DELETE?如果只是读取资料,通常不需要。
用最小任务验证可复现性
环境保存后,不要立刻委派大型开发。先启动一个小任务,让 Codex 只做环境体检:读取项目说明、确认关键工具版本、执行 lint 和单元测试,不修改业务代码。通过后再把同一环境复用于功能开发或排查任务。
验收时关注的不是“脚本跑完了”这一个信号,而是 Codex 能否在无需追加安装命令、无需临时索要变量、无需扩大网络权限的情况下完成标准检查。出现依赖缺失、缓存失配或网络被拒绝时,应回到环境配置修复,再重新验证,而不是把补丁写进每一个任务提示词。