配置

English | 简体中文

README · 安装 · 测试 · 常见问题

默认配置

默认配置如下：

model = "gpt-6-astra" # KISS My Agent managed
model_reasoning_effort = "high" # KISS My Agent managed

[features]
multi_agent = true # KISS My Agent managed

[features.context_management]
experimental_mode = true # KISS My Agent managed

[agents]
enabled = true # KISS My Agent managed

这些默认值在所选可信配置层生效且没有更高优先级覆盖时，选择 Astra/high、启用多代理、自定义 Agent 发现及实验上下文管理；不改变权限、并发、trust、provider、认证或 telemetry。

Setup 独立为每个缺失的 Master 字段补入 gpt-6-astra / high，为每个缺失功能字段补入带 marker 的 true，包括 features.context_management.experimental_mode。已有显式值（包括 false）保留。只有完整的顶层 gpt-5.6-sol / max pair、每个 key 准确出现一次且每行带准确的 # KISS My Agent managed marker 时，才成对更新为 Astra/high。已修改、未标记或不完整 pair 的已有字段继续归用户所有，只补真正缺失的字段。重复 assignment、无效 TOML 与 ownership 歧义属于 conflict。Setup 只修改选定的 project 或 global scope。

默认角色使用 Astra / medium

首次 setup 会安装三个可编辑 seeds：

Current seeds 显式设置 model = "gpt-6-astra" 和上表中的 effort。它们是可编辑的 fresh-setup 默认值。Fresh setup 只创建缺失 starter；任何已经存在的角色都归用户所有，setup 或 Plugin update 永不覆盖、迁移或判定其版本。Setup 已存在后，缺失 starter 会保持 intentionally absent。Plugin cache seeds 只是 package resources，不会自动成为 Host 可发现角色。

三个 Owner

三个层次不能互相替代。角色文件不会启用 multi-agent tools，启用开关不会创建角色 catalog，instructions 也不会授予 runtime 权限。Catalog 保持开放，master 只从实际存在的角色中动态选择；KISS My Agent 不要求固定团队人数或 workflow。Master 可以直接完成明确的小任务或局部工作；对实质批量工作、可独立并行或需要不同视角的工作，在收益超过协调成本时应积极委派。按工作量、并行机会、耦合、风险与协调成本选择，角色可选不等于 Master 包办全部。每种可用角色都可有零个、一个或多个实例，不要求固定组合、顺序或每次启动子代理。组织默认扁平，由 master 直接 fan-out 到当前角色。只有独立子系统需要大量并行、且直接汇总会污染 master context 时，master 才可临时把一个现有 Agent 指定为有界的部门主管。主管可在自身 scope 内调度同类或相关角色实例并向 master 汇总，但其 workers 不再继续委派。Assignment 随任务结束而消失，因此最多一层中间管理，不允许深层嵌套、固定部门、新 seed、固定人数或 organization schema。每个共享文件或资源仍只有一个 writer/operator。无论采用哪种执行方式，Master 都保留架构与验收决策、冲突解决、证据解释和最终汇总责任。

不要仅为组建团队执行 setup。KMA 管理下的明确小任务可直接执行，无需切换 workflow。如果 delegation 被禁用、不可用或没有合适角色，Master 可在已有授权和自身能力内继续工作，无需为 staffing 另设审批。用户明确要求的独立检查、特定角色或真实能力缺口仍须报告，不能把直接执行冒充为满足这些要求。

配置层

Codex 配置优先级从高到低为：CLI flags 与 --config overrides；可信项目中的 .codex/config.toml（越接近当前工作目录优先级越高）；--profile 选择的 profile；用户 config；系统 config；内置 defaults。因此，project 中的 true 可以覆盖更低层的 user false，CLI false 也可以覆盖 project。管理员 requirements 还可能单独约束最终设置。

项目与全局 setup 始终分开。对于 role definitions，Host 应用 project-over-global precedence 并负责更广泛的 catalog warnings；KISS setup 不会拒绝或协调这两个 scope 中的 roles。修改 config、instructions、Skills、Plugins 或角色 TOML 后启动新会话；已有会话不保证热加载。

对话式 Agent 配置向导

没有真实工作负载需要不同模型、effort 或 sandbox 时，应保留继承默认值。要在一个明确 scope 中配置现有角色，运行：

$kiss-my-agent:kiss-my-agent-setup configure agents for this project
$kiss-my-agent:kiss-my-agent-setup configure global agents

要显式把三个已有 KISS roles 设置为 gpt-6-astra / medium，请使用下面准确的项目限定 prompt：

$kiss-my-agent:kiss-my-agent-setup configure agents in this project: for kiss_explorer, kiss_coder, and kiss_reviewer, set model to gpt-6-astra and model_reasoning_effort to medium

请求已经点名一个或多个角色时，向导只解析这些 targets；没有点名时，先只列出 direct role paths 而不解析内容，等待用户选择一个或多个角色后，再只解析选中的文件。向导为 model、model_reasoning_effort 与 sandbox_mode 提供 keep、inherit 或显式值，写入前展示准确 diff；设置 danger-full-access 时必须单独确认。无效的未选角色不会阻塞操作，其 catalog warnings 由 Host 负责。

Project scope 解析到 <unique Host project or active workspace root>/.codex/agents；存在多个 roots 或没有唯一 root 时，向导会先要求选择绝对 project target，选择前不写入。Global scope 优先使用非空 CODEX_HOME，否则使用当前用户的 ~/.codex，并定位到其 agents/ 目录。向导会在检查前展示解析后的绝对 role-directory path。

向导不会创建、删除、重命名或恢复角色。模型可用性取决于 Host 与账户，因此向导不附带硬编码 model catalog。请使用当前 Host 展示的准确 ID，或者保留继承。

若已有角色使用 default_permissions 或 sandbox_workspace_write table，向导不会再写入冲突的 sandbox_mode。这类相关多字段修改应在核对当前 Host schema 后手工完成。

手工编辑角色

也可以直接在已有 standalone role 文件中完成相同修改：

name = "my_role"
description = "Explain when Codex should use this role."
model = "HOST_SUPPORTED_MODEL_ID"
model_reasoning_effort = "HOST_SUPPORTED_EFFORT"
sandbox_mode = "read-only"

developer_instructions = """
Give this role one narrow responsibility and preserve the parent task boundary.
"""

必需字段为 name、description 与 developer_instructions。name 字段才是身份；让文件名与它一致是最简单的约定。有效 catalog 中的名称必须唯一。

模型与权限优先级

Codex 会先为每个 model 或 effort 字段依次解析显式 spawn 值、agents.default_subagent_model 或 agents.default_subagent_reasoning_effort，最后是 parent。若显式 spawn 或 [agents] 默认值选择了模型，但这两个来源都没有指定 effort，Codex 会使用该模型的默认 effort。随后，自定义 Agent role 文件中显式的 model 或 model_reasoning_effort 成为最终 role override。Role 文件只 override model 时，会保留此前已解析的 effort，不会根据该角色模型自动重新计算。

其他省略的 session 设置继承 parent。子代理继承 parent 当前的 sandbox policy；Codex 在 spawn 时还会重新应用 parent turn 的实时 sandbox 与 approval overrides，即使 role 文件写了不同默认值。管理员要求还可进一步限制权限；角色文件不是权限授权。应在新会话中验证实际行为。

Setup 为缺失的 Master 字段补入 gpt-6-astra / high；当前 seed roles 显式使用 gpt-6-astra / medium。已有用户显式选择保持不变。Role wizard 只修改选定角色。静态检查不能证明 Host 有效配置，应在新任务中验证。 如果配置的模型阻止启动，可用 Host 支持的模型 override 启动一次恢复会话：

codex --config 'model="HOST_SUPPORTED_MODEL_ID"' --config 'model_reasoning_effort="HOST_SUPPORTED_EFFORT"'

随后修改持久 config 或 role TOML，并再次启动新会话。KISS My Agent 不会静默替换 fallback model 或 effort。

Setup Scopes

Plugin-owned Skill 使用 Agent 原生文件操作，不需要 Python、Node.js 或包管理器：

$kiss-my-agent:kiss-my-agent-setup set up this project
$kiss-my-agent:kiss-my-agent-setup check this project
$kiss-my-agent:kiss-my-agent-setup remove from this project

$kiss-my-agent:kiss-my-agent-setup set up globally
$kiss-my-agent:kiss-my-agent-setup check global setup
$kiss-my-agent:kiss-my-agent-setup remove global setup

项目 scope 管理 <target>/.codex/config.toml、准确的 <target>/.codex/agents/{kiss_explorer,kiss_coder,kiss_reviewer}.toml targets，以及 <target>/AGENTS.md 中的一个 managed block。全局 scope 管理 $CODEX_HOME 下的对应 paths。Skill 始终留在已安装 Plugin 中。

“This project” 表示 Host 当前唯一的 project 或 active workspace root，而不是 shell 恰好所在的某个子目录。Skill 会显示解析后的绝对目标；存在多个 workspace roots、目标不唯一时先让用户选择。

冲突与 Ownership

• 保留无关 config、角色、instructions、comments 和显式 false。
• Setup、check 与 remove 只检查所选 scope 中由 KISS 管理的 config、AGENTS paths 和三个准确 bundled role targets；不解析其他 role files 或 opposite scope 中的 roles。
• 所选 managed path 的类型不安全、所选 config 或准确 bundled target 的 TOML 无效、准确 bundled target 缺少 identity fields 或 name 与文件名不同、managed ownership 不明确，或存在适用的 AGENTS.override.md 时，在写入前停止。
• 其他文件中的 duplicate identities 与 project/global duplicate role names 不会阻塞 KISS setup 或 check。Catalog warnings 和 project-over-global precedence 由 Host 负责；KISS 不会协调这些冲突。
• 每个已有角色都归用户所有并逐字节保留。Setup 永不拿它与历史 seeds 比较、判定版本或迁移它。后续 setup 不会恢复用户有意删除的 starter。
• 显式 remove 会删除带准确 marker 且值精确匹配的当前默认配置 与任何准确的旧 marked Master pair、managed AGENTS block，以及字节完全匹配 current、known v0.2.6、known v0.2.5 或 known v0.1 seed 的 bundled roles；其他角色文件仍归用户所有。 Remove 保留上下文子表及其他用户字段；只删除精确默认值和准确 marker 同时匹配的配置。

单次启动禁用

不编辑文件并关闭两个公开 multi-agent 表面：

codex --config features.multi_agent=false --config agents.enabled=false

如需持久移除 KISS 项目指导与 seeds，应使用明确的 project remove 命令。只禁用 multi-agent 开关不会删除已有 AGENTS block。

官方参考

• Subagents and custom agents
• Basic configuration and precedence
• Configuration Reference
• Advanced Configuration
• GPT-6 Astra