Skip to content

[Bug]: Local Classic Codex 角色模板缺少 developer_instructions,启动时被忽略 #905

Description

@reuwi

Component / host

Local — Codex

Edition

Local Classic

LoopForge version

Local installation record: installer/package 0.2.2, classic:codex.
Codex CLI: 0.167.0 on macOS.
The same seven TOML templates were also verified in upstream commit dd56585276d8ecb6e0d6865f55e255194d75f85a.

What happened?

在已安装 Classic Codex 工作流的项目目录启动 codex,出现 7 条自定义角色加载警告:角色 TOML 缺少必需的 developer_instructions,被 Codex 忽略。

本地 7 个 TOML 的 SHA-256 均与 .devflow/install-state.json 中的安装记录一致,并且与上游模板内容相同,并非手工修改造成。

预期:按文档安装后启动 Codex,不应因为 LoopForge 自带的角色模板产生 malformed agent role 警告。

Reproduction

  1. 在项目中安装 Classic Codex 工作流。官方文档入口:npx -y loopforge-cli@latest install codex。本次观察到的本地安装版本是 0.2.2。
  2. 在项目目录启动 codex(本次环境为 codex-cli 0.167.0)。
  3. 在进入 DevFlow 工作流之前,启动阶段即可看到下述警告。

Sanitized diagnostics

Ignoring malformed agent role definition: agent role file at <project>/.codex/agents/devflow-architect.toml must define `developer_instructions`

相同问题涉及:

  • devflow-architect.toml
  • devflow-code-reviewer.toml
  • devflow-developer.toml
  • devflow-knowledge-engineer.toml
  • devflow-leader.toml
  • devflow-solo-developer.toml
  • devflow-test-engineer.toml

Source analysis

  1. 角色模板 当前内容为:

    name = "devflow-architect"
    description = "DevFlow architect:产出技术方案和执行计划。"
    instructions = ".codex/agents/architect.md"

    当前 Codex 的 standalone custom agent schema 要求 name、description、developer_instructions。参见 OpenAI custom agents 文档。模板使用的 instructions 路径字段未满足这一要求。

  2. materialize_classic() 直接复制宿主资产目录,将这些 TOML 原样安装到用户项目中。

  3. Classic 派发协议 实际使用内置 explorer / worker,并要求在提示词中传入 Markdown 角色职责,而不是派发这些 devflow-* 自定义角色。因此当前确认的影响是启动警告和自定义角色未注册;没有证据表明整个 DevFlow 一定因此无法运行。

  4. doctor() 检查资产是否存在和安装文件是否改动,没有验证这些角色定义是否符合 Codex schema。安装 E2E 的文件存在性检查也不能发现这一不兼容。

Suggested fix

  • 如果 Classic 继续使用内置 agent 加提示词的派发方式,可考虑停止安装未使用的自定义角色 TOML,并处理已安装项目中的旧文件。
  • 如果保留这些自定义角色,应迁移为有效的 developer_instructions,确保角色 Markdown 的指令被正确加载。不能仅改字段名后就假定文件路径会被自动读取。
  • 增加 Codex 角色配置的 schema / 真实加载兼容性验证。

尚未验证该格式从哪个 Codex 版本起不兼容,也未运行完整 DevFlow 业务流程。

Safety checks

  • I removed credentials, private endpoints, internal identifiers, and personal data.
  • I searched existing issues for duplicates (including open and closed issues; no matching report found).

Activity

  1. cocofhu00 commented on Nov 16, 2026

    @cocofhu00
    Contributor

    感谢反馈!理解你的意思是:按文档安装 Local Classic Codex 工作流(0.2.2)后,在 codex-cli 0.167.0 下启动 Codex,会因 7 个 devflow-*.toml 角色模板缺少 developer_instructions 而出现 malformed agent role 警告,这些自定义角色被忽略;模板与安装记录、上游内容一致,并非本地改动。

    已经看到,会按现有 Issue 排期查看。你提供的版本、复现步骤和源码分析都很完整,谢谢。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions