本文不是理论堆砌,而是用一个真实可用的案例——在 Claude Code 里自定义/codex命令,把编码任务一键委派给 WSL 里的 OpenAI Codex CLI——完整演示自定义命令的写法、原理与踩坑点。一、为什么要自定义命令Claude Code 是 Anthropic 官方的终端 AI 编程助手,内置了/clear、/review、/permissions等斜杠命令。但实际工作中你总有一些高频、固定的诉求,比如:把任务交给另一个 AI CLI(Codex / DeepSeek)去做固定的代码审查流程每次开会前的项目状态汇报一键初始化新模块的目录结构如果每次都手动复述一堆提示词,又累又容易漏。自定义斜杠命令就是解决这个问题的:把一个 Markdown 文件变成一个命令,输入/命令名即可触发。二、原理:命令就是一个 Markdown 文件Claude Code 的斜杠命令本质是一个 Markdown 文件(经典 commands 格式;并入 Skills 后,入口同样是 Markdown YAML frontmatter),分为两部分:1. Frontmatter(元数据)用---包裹的 YAML,声明命令的描述、参数提示、可用工具等:---description:命令在 / 菜单里的说明文字argument-hint:提示用户该输入什么参数allowed-tools:允许 Claude 使用的工具,如 Bash(*)model:指定该命令使用的模型---2. 正文(给 Claude 的指令)Markdown 正文是注入给 Claude 的提示词,里面有特殊的占位符:占位符作用$ARGUMENTS你输入/命令 内容中的内容整体替换进来$1$2…按空格切分的位置参数:第一个是$1、第二个是$2,支持${3:-默认值}缺省写法$ARGUMENTS[N]0 起算的索引写法,$ARGUMENTS[0]即第一个参数${CLAUDE_SESSION_ID}当前会话 ID!命令注入命令输出,如!git status⚠️ 网上流传的$JSON_ARGS、$PROMPT_FILE等变量未见于官方文档,不要依赖。工作流程:你输入/codex 帮我重构这个模块→ Claude Code 读取codex.md内容,把$ARGUMENTS替换为帮我重构这个模块 → 作为指令注入 Claude → Claude 按指令执行。三、命令放在哪里?位置作用范围.claude/commands/xxx.md(项目目录内)仅当前项目可用,可随仓库提交共享~/.claude/commands/xxx.md(用户主目录)所有项目全局可用版本提示:commands/目录是兼容的旧格式。Claude Code 已把自定义命令并入 Agent Skills 标准,当前推荐写法是.claude/skills/命令名/SKILL.md(项目级)或~/.claude/skills/命令名/SKILL.md(用户级)。frontmatter 与正文写法一致,还支持disable-model-invocation、context: fork等新字段。本文案例基于经典 commands 格式,同样适用于 Skills。个人建议:通用的工具类命令放用户目录(全局),业务相关的放项目目录。四、实战案例:自定义/codex下面是我机器上的真实配置。分工很简单:开发任务全部在宿主机 Claude Code 里完成,/codex只做代码评审、不做代码修改。输入/codex 评审下刚才的修改,Claude 会自动调用 WSL 里的 Codex CLI 以另一个模型视角审查改动,再把结果汇报回来(命令模板本身也支持写码模式,但那是备用能力,不是我的日常用法)。4.1 前提Windows 上安装了 WSL,并在 WSL 里装好 Codex CLI、完成登录鉴权:npminstall-gopenai/codex codex login# 或配置 OpenAI API Keycodex--version# 确认可执行(本文验证环境:codex-cli 0.144.4)4.2 创建文件新建~/.claude/commands/codex.md,内容如下:--- description: Review code changes with OpenAI Codex CLI running in WSL (read-only by default) argument-hint: [your coding task] allowed-tools: Bash(*) --- Execute the following task using **Codex CLI** installed in WSL. ## Instructions 1. No path conversion needed: WSL inherits the current Windows directory as its working dir. 2. Run Codex (choose the right mode): **For review/analysis tasks (read-only, no writes):** bash wsl bash -c codex exec --sandbox read-only --skip-git-repo-check PROMPT **For coding tasks (writes code — reserved, not the default use):** bash wsl bash -c codex exec --sandbox workspace-write --skip-git-repo-check PROMPT 3. Report the Codex output. If it modified files, summarize the changes. ## Task $ARGUMENTS注:示例相对作者的真实配置做了三处微调——read-only 提到首位、去掉 faster 表述、命令去掉嵌套的cd $(wslpath ...)(原因见 4.3 避坑要点)。你的文件保持原样也能用,但建议按示例版本优化。几个关键点逐一拆解:allowed-tools: Bash(*):本次命令调用期间的免确认预授权,不是工具白名单——未列出的工具仍会按会话权限规则请求。Bash(*)把任意 Bash 命令都免确认,风险较高,建议按实际命令精确匹配(用/permissions验证),不要图省事全放开。正文分 “Instructions”(怎么做) “Task”(做什么):$ARGUMENTS放在最后,用户输入的任务会被替换到这里。指令部分写清步骤,Claude 才能稳定执行。--sandbox等参数属于 Codex CLI,不是 Claude Code 功能:--sandbox read-only表示禁止写入、适合分析任务、风险更低(并不保证更快);--skip-git-repo-check用于非 git 目录。两种模式,日常只用一种:模板同时给了workspace-write(写码)和read-only(评审)两种模式,但我的实际用法是评审专用——永远走read-only,Codex 只出意见、不动文件。开发任务留在宿主机 Claude Code(DeepSeek)做。有副作用、仅手动触发的命令建议加disable-model-invocation: true:否则在 Skills 机制下,Claude 可能因看起来相关而自动调用它。加上后只有你输入/codex才会触发。4.3 实际执行链路你输入 /codex 评审下刚才的修改 ↓ Claude Code 读取 codex.md,替换 $ARGUMENTS ↓ Claude 执行 Bash(无需 cd——WSL 自动继承 Windows 当前目录): wsl bash -c codex exec --sandbox read-only --skip-git-repo-check 评审 main.py 的改动 ↓ WSL 中的 Codex CLI 只读审查,输出分级意见 ↓ Claude 把 Codex 意见汇报给你(评审不动任何文件)可以看到,/codex本质上是一个**“中继命令”**:Claude Code 负责接收任务、桥接 Windows 与 WSL、汇报结果,真正干活的是 Codex CLI。Windows WSL 双环境的避坑要点WSL 继承 Windows 当前目录:Claude Code 在D:\projects\my-app启动时,WSL 的pwd直接就是/mnt/d/projects/my-app,不需要cd,也就不需要路径转换。确需切目录时,先在本机算好路径:wsl wslpath D:/xxx得到/mnt/d/xxx再拼进命令,不要在命令里嵌套$(wslpath ...)——Windows 侧 shell 可能吃掉内层引号导致失败(本案例实际踩过)。警惕嵌套引号:wsl bash -c ... PROMPT叠加了单双引号,任务里出现$、反引号、双引号时极易解析出错,提示词内尽量规避特殊字符。更彻底的方案:直接在 WSL 里安装 Claude Code Codex CLI,同环境运行,路径、目录、引号三类问题全部消失。4.4 使用效果# 评审专用(我的日常用法):让 Codex 以另一个模型视角审刚写完的代码/codex 评审下刚才的修改# 只读分析(read-only 禁止写入,风险更低)/codex 分析一下这个项目的模块依赖,输出一份报告# 模板里保留的 workspace-write 写码模式属备用能力,本文不展开——作者惯例:写码留在宿主机,/codex 不改码实录:本文作者环境为 Windows 11 Git Bash WSL codex-cli 0.144.4,输入/codex 评审下后,Codex 以 read-only 模式输出约 8.7 万 tokens 的分级评审,未改动任何文件。4.5 高频场景:写码交给 DeepSeek,评审交给 Codex在我这里,/codex是评审专用,不做代码修改——分工很明确:开发任务全部在宿主机 Claude Code(经网关路由到 DeepSeek)里完成,写完代码后输入:/codex 评审下刚才的修改Codex 以另一个模型、独立进程的身份在 WSL 里把改动过一遍。这不是炫技,而是实打实的第二个工程师:Claude/DeepSeek 写码时有自己的思维惯性,Codex 的审查视角往往能发现前者没注意到的问题——两个模型互审,比单个模型自查靠谱得多。三个实操要点先说清刚才的修改是什么。Codex 不会自己知道哪些文件是新改的,提示词里必须带上文件清单或 diff。在 git 仓库里,可以让 Claude 先跑git diff --stat把改动文件列进提示词;不在 git 仓库(比如本文写作目录),就直接在提示词里点名文件。更省心的做法是在codex.md正文里追加一条评审规则:## Reviewing recent changes (optional) If the task is to review recent changes: 1. First find out what changed: run git diff --stat (in a git repo), or ask the user for the file list 2. Include the file list / diff in the PROMPT so Codex knows what to review 3. Ask for findings ordered by severity (e.g. P0/P1/P2)评审务必用 read-only:--sandbox read-only禁止 Codex 改动文件,只输出意见。评审场景永远不该出现写操作。让 Codex 分级输出。实测中 Codex 会按 P0(不修会翻车)/ P1(影响可信度)/ P2(可优化)输出,直接照着改即可。上文 4.4 的实录就是一次完整的交叉评审:它揪出了三个 P0 硬伤(嵌套代码块、未验证的占位符变量、嵌套引号坑),其中嵌套引号那条我们后来实机复现、确实会挂——这就是交叉评审的价值:你写完以为没问题,Codex 替你踩了一遍坑。五、进阶:一个命令文件 一个模型切换器同目录下的flash.md和pro.md是更简化的玩法——只用 frontmatter 和一行占位符:--- description: Quick, cost-efficient task model: my-flash argument-hint: [your prompt] --- $ARGUMENTS--- description: Deep reasoning task model: my-pro[1m] argument-hint: [your prompt] --- $ARGUMENTS效果:/flash 总结这个仓库会用便宜的快模型快速跑,/pro 设计这个架构会用更强的深度推理模型——用命令把模型选择固化成了肌肉记忆,不用每次手选。⚠️前提说明:示例中的my-flash、my-pro[1m]不是官方模型名,是作者环境通过网关路由到第三方模型后配置的自定义 ID(已脱敏)。model字段只能填当前/model里可见的模型名,普通官方账户请改用claude-sonnet-5等官方 ID,或先配置好自定义网关再照抄。六、实用小贴士描述要写清楚:description会显示在/菜单里,这是你找命令的入口。参数提示别省:argument-hint提示用户输入格式,避免不知道填什么。分步指令优于一句话:告诉 Claude先做什么、再做什么、最后汇报什么,执行稳定性天差地别。allowed-tools慎用*:免确认授权范围太大有风险,建议按实际命令精确匹配,并在/permissions里验证生效情况。生效时机:Skills 新格式支持会话内热加载;经典 commands 格式保存后新开会话,/菜单里即可看到新命令。团队共享:把命令放进项目.claude/commands/,提交到 Git 仓库,队友 clone 后即得。七、总结Claude Code 的自定义命令看似简单——就是一个 Markdown 文件——但它把提示词 工具策略 环境桥接封装成了一个语义化入口:/codex:评审专用中继器——写码留在宿主机 Claude Code(DeepSeek),评审交给 WSL 里的 Codex,两个模型互审、Codex 永不改码/flash、/pro:模型切换器你的命令:任何你能想到的高频工作流你给 AI 的不是一行提示词,而是一个可复用、可分享、可持续演进的能力插件。这就是自定义命令的价值。如果您觉得有用欢迎点赞、转发、评论、关注。