Codex CLI
Why this agent
OpenAI 的 Codex CLI 是终端 AI 编程助手。它通过 TOML 配置支持 MCP;espctl 的接入方式和基于 JSON 的 agent 一样,只是用 TOML 语法。
Prerequisites
- 已安装 Codex CLI 并在
$PATH中(codex --version能跑)。 espctl已安装在磁盘上某个稳定位置(下文需要完整路径)。- (可选,用于远程构建)Aegis 构建服务器地址 +
MCP_AUTH_SECRET。
Install snippet (or alternative)
写入 ~/.codex/config.toml(或者项目目录下的 .codex/config.toml
作为项目级):
[mcp_servers.espctl]
command = "/path/to/espctl"
args = ["mcp", "serve"]
cwd = "/path/to/your/esp-idf/project"
[mcp_servers.espctl.env]
CONTROL_BASE_URL = "https://esphome.cloud"
MCP_AUTH_SECRET = "your-access-key"
注意事项:
[mcp_servers.espctl.env]是它自己的一段 TOML 表 —— 每个变量一行。 不要试图嵌入 JSON 风格的 map。args是一个 TOML 字符串数组,完全按上面写。- 路径/值规则和 Claude Code 那一章一样。
或者 —— 拿到预填好的 TOML 片段:
读取
install://codex,把代码片段给我。
First-run verification
重启 Codex CLI(或者重新打开持有它的 shell)。在 Codex 聊天里:
我有哪些 espctl 工具?
预期:列出约 40 个工具。
Troubleshooting
- 启动时报 “unknown table” 或 TOML 解析错 → 确认
[mcp_servers.espctl]和[mcp_servers.espctl.env]是两段独立的 表,各自占一行。内联env = { ... }在某些 TOML 版本能用,但不 一定;两段式才是稳的。 - 工具列表为空 → 用
codex --debug(把 MCP 错误打到终端) 或者看~/.codex/logs/。 - 项目级配置不生效 → Codex CLI 从当前工作目录读
.codex/config.toml;先cd进项目再运行codex。