AI Agent / 系统课时

配置云端开发环境

配置云端开发环境

云端任务能否稳定完成,取决于环境是否可复现。本节把依赖安装、环境变量、初始化脚本和网络权限收敛成一套可验证配置,让 Codex 每次拿到仓库后都能直接进入编辑与测试,而不是把时间消耗在重复修环境上。

学习目标

  • 能为仓库设计可重复执行的依赖安装与初始化步骤
  • 能区分普通环境变量、敏感凭据和运行期需要的配置
  • 能按最小权限原则开放云端任务所需的网络访问

理解云端环境的启动链路

一次云端任务可以理解为“准备工作区 → 初始化环境 → 运行 agent → 验证改动”。真正需要固定下来的不是某台机器,而是从干净工作区恢复到可开发状态的步骤:运行时版本、包管理器、依赖、工具、环境变量以及必要的外部域名都应显式化。

Codex 云端环境从仓库到可执行任务的启动链路

把“能启动”当作最低标准还不够。环境应该满足三个验收条件:初始化可以重复执行、失败能快速暴露、agent 无需猜测项目怎么安装依赖或跑检查。

固化依赖和初始化步骤

优先使用仓库已经提交的锁文件,例如 package-lock.json、pnpm-lock.yaml、poetry.lock。setup 脚本应做到幂等:重复执行不会破坏工作区,也不会依赖上一次任务残留的临时状态。不要在脚本里做数据库迁移、发布或写入生产系统等不可逆操作。

下面假设仓库是一个已提交 package-lock.json 的 Node.js 项目,并在云端环境中配置了非敏感变量 APP_ENV=codex-cloud。可将以下内容作为 setup 脚本:

bash
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"

预期输出

text
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 能否在无需追加安装命令、无需临时索要变量、无需扩大网络权限的情况下完成标准检查。出现依赖缺失、缓存失配或网络被拒绝时,应回到环境配置修复,再重新验证,而不是把补丁写进每一个任务提示词。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置云端开发环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通