角色创建工具

概述

当用户想要创建、更新或排查由

[agents.<role>]

和角色

config_file

支持的自定义子Agent角色时，可使用此技能。

该技能会将角色安装到

~/.codex/config.toml

（或用户选择的项目配置文件）中，写入角色专属配置文件，并对照

codex-rs/core/config.schema.json

验证键的支持性。

默认采用严格极简模式：仅配置

model

、

model_reasoning_effort

和

developer_instructions

，除非用户明确要求添加其他参数。

默认安装位置为

~/.codex/config.toml

，但如果用户要求创建项目范围的角色，该角色将被安装到项目的

.codex/config.toml

中，也可安装到仓库的子文件夹内。

必填输入项

第一步必须是收集输入信息。在执行任何写入/安装/验证命令前，需收集并确认以下内容：

```
model
```
```
model_reasoning_effort
```
```
developer_instructions
```
安装范围（
```
global
```
或
```
project
```
）
```
role_name
```
```
description
```
```
role_config_file
```
（优先使用绝对路径）

提问需简洁明了：

该角色应使用哪个模型？

（推荐：

gpt-5.3-codex

）

应使用何种推理强度？

（推荐：

medium

；可选值

medium|high|xhigh

）

该角色的developer_instructions应优先关注什么？

（目标、边界、成功标准）

你希望将其安装到全局配置（~/.codex/config.toml）还是项目配置（.codex/config.toml）中？

是否需要沙箱、网页搜索、MCP或其他限制？

在spawn_agent中应显示什么角色名称和描述？

执行门槛：

不得推断缺失的必填值。
必须在用户明确提供所有上述必填输入项或明确接受默认值后，才能开始第二步（写入文件）。

可选参数默认规则

除非明确要求，否则不得设置沙箱标志。
除非明确要求，否则不得设置
```
web_search
```
。
除非明确要求，否则不得设置MCP标志/条目。
除非明确要求，否则不得添加任何其他可选的
```
config_file
```
键。
如果用户意图不明确，添加可选键前需先提出简短的澄清问题。

知识与应用规则

角色创建工具必须了解完整的配置范围，但仅应应用用户要求的键。

必须执行的行为：
在有帮助时解释可用的可选类别。
当用户询问可能性时，提供具体示例/模板。
默认生成极简配置。
仅在用户明确要求时添加可选键。
如果用户表示“使用默认/继承”，则省略可选键，而非设置明确值。

角色配置范围（可自定义内容）

角色

config_file

会被解析为完整的配置层。如果某个键被省略，通常会从父配置继承。

模型与推理：
```
model
```
```
model_reasoning_effort
```
```
model_reasoning_summary
```
```
model_verbosity
```
```
personality
```
核心行为：
```
developer_instructions
```
沙箱与权限：
```
sandbox_mode
```

[sandbox_workspace_write]

字段，如

network_access

、

writable_roots

网页搜索：
```
web_search
```
（
```
disabled|cached|live
```
）
功能开关：
```
[features]
```
键，如
```
memory_tool
```
、
```
shell_tool
```
MCP服务器：

[mcp_servers.<name>]

条目（

enabled

、

required

、

command

、

args

、

env_vars

）

应用/连接器：
```
[apps.<name>]
```
条目（
```
enabled
```
）

当用户询问高级角色控制时，可使用以下模板中的具体示例：

```
templates/minimal-role-config.toml
```
```
templates/restricted-role-config.toml
```
```
templates/full-role-config.toml
```

templates/frontend-architecture-role.toml

支持的角色声明键

对于

[agents.<role_name>]

，仅支持以下键：

```
description
```
```
config_file
```

不得在

[agents.<role_name>]

下添加任何其他内容。

工作流程

收集并确认必填输入项（硬性门槛）。

询问模型、推理强度、developer_instructions、安装范围、角色名称、描述和角色配置文件路径。
仅当用户明确同意时，才确认是否使用默认值。
此步骤不得写入文件。

验证环境和解析后的路径。

确保仓库模式文件存在：
```
codex-rs/core/config.schema.json
```
根据范围解析配置目标：
```
global
```
->
```
~/.codex/config.toml
```
```
project
```
->
```
<project>/.codex/config.toml
```

创建或更新角色配置文件。

使用
```
scripts/write_role_config.sh
```
写入必填字段。
仅在用户明确要求时添加可选控制项。
脚本支持的可选控制项：
```
sandbox_mode
```
+ 工作区写入设置
```
web_search
```
模式（设置为
```
disabled
```
可禁用网页搜索）
MCP控制项（
```
mcp_clear
```
、
```
mcp_enable
```
、
```
mcp_disable
```
）
如果用户需要脚本标志之外的选项（例如
```
model_reasoning_summary
```
、
```
features
```
、
```
apps
```
、复杂的MCP服务器定义），请从
```
templates/
```
下的模板开始手动编辑，然后运行验证。
在输出中清晰说明：
```
已配置：
```
已写入的键
```
可用但未设置：
```
未配置的相关可选键（将继承父配置）

在主配置文件中安装角色。

使用
```
scripts/install_role.sh
```
。
此脚本会写入/更新：
```
features.multi_agent = true
```

[agents.<role_name>] description/config_file

增量安全机制：
安装程序仅修改与角色相关的键，保留
```
config.toml
```
的其他内容不变。
安装程序在写入前始终会为目标
```
config.toml
```
创建带时间戳的备份。
除非传入
```
--update-existing
```
参数，否则不会覆盖已有的角色定义。

验证后再报告成功。

使用
```
scripts/validate_role.sh
```
。
确认角色配置文件中存在必填字段。
确认角色声明仅包含
```
description/config_file
```
键。
确认顶层角色配置键符合模式文件要求。

分享可运行的Agent调用示例。

示例：

json

{"agent_type":"<role_name>","message":"<task>"}

命令示例

bash

# 1) 写入角色配置文件（仅包含必填字段；默认行为）
.codex/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/researcher.toml \
  --role-name researcher \
  --model gpt-5.3-codex \
  --reasoning medium \
  --developer-instructions "仅研究代码和文档；禁止编辑；返回file:line格式的证据。"

# 1b) 可选控制项（仅在明确要求时使用）
.codex/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/researcher.toml \
  --role-name researcher \
  --model gpt-5.3-codex \
  --reasoning medium \
  --developer-instructions "仅研究代码和文档；禁止编辑；返回file:line格式的证据。" \
  --sandbox-mode workspace-write \
  --network-access false \
  --writable-roots "/home/willr/Applications/codex1" \
  --web-search disabled

# 2) 在~/.codex/config.toml中注册角色
.codex/skills/role-creator/scripts/install_role.sh \
  --role-name researcher \
  --description "只读代码库研究专家" \
  --role-config-file ~/.codex/agents/researcher.toml

# 2b) 有意更新现有角色定义
.codex/skills/role-creator/scripts/install_role.sh \
  --role-name researcher \
  --description "更新后的角色描述" \
  --role-config-file ~/.codex/agents/researcher.toml \
  --update-existing

# 3) 验证角色配置和声明键
.codex/skills/role-creator/scripts/validate_role.sh \
  --role-name researcher \
  --config ~/.codex/config.toml \
  --role-config ~/.codex/agents/researcher.toml \
  --schema /home/willr/Applications/codex1/codex-rs/core/config.schema.json

防护规则

如果运行时返回
```
unknown agent_type
```
，请验证角色是否存在于当前配置中，且
```
config_file
```
路径存在/可读取。
如果运行时返回
```
agent type is currently not available
```
，请检查角色文件的TOML格式有效性和是否使用了不支持的键。
保持指令与角色相关且可操作（范围、允许/禁止操作、交付格式）。
未运行验证不得宣称操作成功。

参考资料

角色键矩阵与运行时行为：
```
references/role-config-reference.md
```
可复用模板：
```
templates/
```

role-creator

NPX安装

标签

SKILL.md 内容（中文）