Codex AGENTS.md:让 VPS 上的代理指令保持一致

Codex AGENTS.md:让 VPS 上的代理指令保持一致 — 在 VPS 上可靠使用 Codex AGENTS.md:理解文件发现顺序、覆盖规则和工作目录范围,并在无人值守任务启动前验证指令。
2026年11月17日2 分钟阅读
Share with

同一个 Codex 任务,在我们的笔记本上和 VPS 上表现不同。仓库内容完全一样,但代理从另一个目录启动,还继承了不同的账户级指令。反复发送同一提示,并不能修复环境差异。

我们把 Codex AGENTS.md 当作需要版本管理的操作指引,而不是神奇的记忆文件。下面介绍如何在远程代理无人值守工作前,让指令范围可复现。这是一套手动 Codex 工作流程,不是 Office Claws 新增的配置功能。

Codex AGENTS.md:运行环境实际加载什么

官方指令指南说明,指令链会在每次运行开始时构建。启动目录很重要:文件存在于仓库某处,不代表它一定进入初始指令链。

层级发现方式运维影响
Codex 主目录优先 AGENTS.override.md,否则 AGENTS.md;采用首个非空文件VPS 账户可能引入笔记本上没有的规则
项目根目录到工作目录每个目录最多一个文件:覆盖文件、普通文件、已配置的备用文件名从服务目录启动与从根目录启动,加载的链不同
合并后的指令从根目录向下合并,较近的指令优先局部例外可以改变通用默认规则

项目文档合并后的默认上限为 32 KiB。保持简洁;出现截断时检查 project_doc_max_bytes。覆盖文件替代的是同一目录中的普通文件,并不会清除此前所有层级。默认主目录是 ~/.codex,但 CODEX_HOME 可以指向其他位置。

从账户默认规则到仓库和服务目录的指令链

大约 3 分钟运行你的第一个智能体

安装 Office Claws CLI,连接你的 Contabo 账户和 Codex 订阅,你的智能体就会拥有自己的 VPS 和办公室里的一张桌子。

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/月 + 你自己的 Contabo VPS · 密钥保存在你的钥匙串中

写工作约定,而不是整本仓库手册

我们把稳定的共享规则放在仓库根目录,把服务专用命令放在服务附近。不要把整个架构知识库塞进上下文预算;应指出相关文档,以及它用于支持什么决策。

如果仓库的测试命令确实是 npm test,可以参考下面这个简短的根目录文件模板。提交前必须按实际项目调整命令。示例不会赋予权限,也不会配置自动化。

# AGENTS.md
 
## Scope
- Work only on the assigned branch and requested change.
- Read docs/development.md before changing build configuration.
 
## Verification
- Run npm test after code changes; report the command and result.
- If a check cannot run, report the blocker instead of claiming success.
 
## Review boundary
- Do not deploy, publish packages, or rotate credentials.
- Flag authentication and migration changes for human review.

像审查代码一样审查指令文件。把「提出迁移建议」改成「执行迁移」,即使应用源码没有变化,也值得审核。不要在这些文件里放令牌、密码或私人账户信息:仓库指令会发送给模型,不是秘密存储设施。

通过 SSH 验证相同的指令范围

在 VPS 上,要使用与真实任务一致的 Unix 账户、仓库副本、工作目录和 Codex 配置。管理员终端中的结果,不能证明服务账户的配置相同。连接方法见我们的 SSH 工作流指南。

从可信仓库根目录执行下面的只读预检,将路径替换为自己的仓库。它只列出候选文件,不能证明全部文件都会加载;应对照上面的范围规则和代理回答进行检查。最后一条命令会调用模型,可能消耗套餐额度。

cd ~/work/product-api
pwd
git rev-parse HEAD
codex --version
printf 'CODEX_HOME=%s\n' "${CODEX_HOME:-$HOME/.codex}"
find . -type d -name .git -prune -o -type f \
  \( -name AGENTS.md -o -name AGENTS.override.md \) -print
codex exec --sandbox read-only \
  "Do not edit files or execute project commands. List the instruction sources you loaded and summarize the verification and review boundaries."

单独检查账户级文件,不要把其内容复制到共享日志中。还要检查配置中的备用文件名:上面的 find 故意只查找两个标准名称。模型总结适合作为快速检查,不是正式审计,也不是安全保证。

如果任务属于某个嵌套服务,从该目录再次执行预检。修改指令文件后应重新启动一次运行:文档所述的指令链每次运行只构建一次,不会热更新到现有会话。

将文字指令与实际权限控制分开

AGENTS.md 中的「不要部署」不是访问控制机制。应独立限制凭据和工具权限,并配置合适的沙箱与审批策略。不要仅因为指令禁止使用生产部署凭据,就把这些凭据交给夜间运行的代理。

无人值守任务启动前,我们记录提交、Codex 版本、工作目录和指令文件版本。运行并行代理时,应逐一验证仓库副本,而不是假设某台机器上的修改已经同步到所有代理。如果行为不同,先检查账户主目录、CODEX_HOME、覆盖文件、备用名称配置和启动目录,再考虑重写任务提示。

Office Claws 在你自己的 Contabo VPS 上运行 Codex 代理,并提供 CLI 和像素风桌面控制界面。仓库指令维护与结果审查仍由你负责。Office Claws 首个代理的费用从 $4.99/月起;VPS 与受支持的 ChatGPT 套餐另行付费,套餐使用限制仍然适用。详情见 Codex 订阅成本比较。

我们的建议是:为一份简短的工作约定做版本管理,用实际运行账户验证,并保留人工审核。全天在线的机器应让流程更可复现,而不是让文本文件看起来像权限边界。

作者

Office Claws Team

在 Office Claws 构建 AI 智能体管理的未来。分享关于基础设施、安全和开发者体验的见解。

大约 3 分钟运行你的第一个智能体

安装 Office Claws CLI,连接你的 Contabo 账户和 Codex 订阅,你的智能体就会拥有自己的 VPS 和办公室里的一张桌子。

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/月 + 你自己的 Contabo VPS · 密钥保存在你的钥匙串中