---
title: "model_instructions_file 替换的是内置指令，不是 AGENTS.md"
summary: "路径指向一份文件，整份替换模型自带的 base instructions。仓库约定仍写 AGENTS.md。相对路径相对的是那份 config 所在的 .codex/ 目录。"
category: config
level: advanced
surfaces: [cli, ide, app]
tags: ["model_instructions_file", "AGENTS.md", "config.toml"]
canonical: /tips/model-instructions-file/
---

# model_instructions_file 替换的是内置指令，不是 AGENTS.md

路径指向一份文件，整份替换模型自带的 base instructions。仓库约定仍写 AGENTS.md。相对路径相对的是那份 config 所在的 .codex/ 目录。

官方配置参考把 `model_instructions_file` 写成「Replacement for built-in instructions instead of AGENTS.md」。它换掉的是 Codex 自带的系统指令，不是项目 `AGENTS.md`。仓库约定、测试命令、禁止事项仍放 `AGENTS.md`。

用户级用绝对路径，避免 cwd 一变就丢文件：

```toml
model_instructions_file = "/home/you/.codex/base-instructions.txt"
```

项目 `.codex/config.toml` 里的相对路径，相对的是**包含这份 config 的 `.codex/` 目录**，不是仓库根：

```toml
model_instructions_file = "base-instructions.txt"
```

这时文件应放在 `.codex/base-instructions.txt`，不是仓库根。旧键 `experimental_instructions_file` 已弃用。顶层字符串键 `instructions` 是预留位，写了也不会当指令用。

不要把长篇 AGENTS.md 拷进这个文件指望「覆盖项目说明」；项目文档发现链仍走 `AGENTS.md` / `project_doc_fallback_filenames`。改完用 `codex debug prompt-input` 看模型真正吃到的指令，再 `/debug-config` 核对路径。

## 来源

- [OpenAI · Advanced configuration](https://learn.chatgpt.com/docs/config-file/config-advanced)
- [OpenAI · Configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)