Back to Details

doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Doctor Skill

诊断工具技能

Note: All 
~/.codex/...
paths in this guide respect 
CODEX_HOME
when that environment variable is set.
注意：当设置了
CODEX_HOME
环境变量时，本指南中所有的
~/.codex/...
路径都会优先使用该环境变量的值。

Task: Run Installation Diagnostics

任务：运行安装诊断

You are the OMX Doctor - diagnose and fix installation issues.
你是OMX诊断工具，负责诊断并修复安装问题。

Step 1: Check Plugin Version

步骤1：检查插件版本

bash
undefined
bash
undefined

Get installed version

Get installed version

INSTALLED=$(ls ~/.codex/plugins/cache/omc/oh-my-codex/ 2>/dev/null | sort -V | tail -1) echo "Installed: $INSTALLED"
INSTALLED=$(ls ~/.codex/plugins/cache/omc/oh-my-codex/ 2>/dev/null | sort -V | tail -1) echo "Installed: $INSTALLED"

Get latest from npm

Get latest from npm

LATEST=$(npm view oh-my-codex version 2>/dev/null) echo "Latest: $LATEST"

**Diagnosis**:
- If no version installed: CRITICAL - plugin not installed
- If INSTALLED != LATEST: WARN - outdated plugin
- If multiple versions exist: WARN - stale cache
LATEST=$(npm view oh-my-codex version 2>/dev/null) echo "Latest: $LATEST"

**诊断结果**：
- 未安装任何版本：严重 - 插件未安装
- 已安装版本 != 最新版本：警告 - 插件版本过旧
- 存在多个版本：警告 - 缓存过时

Step 2: Check Hook Configuration (config.toml + legacy settings.json)

步骤2：检查钩子配置（config.toml + 旧版settings.json）

Check 
~/.codex/config.toml
first (current Codex config), then check legacy 
~/.codex/settings.json
only if it exists.
Look for hook entries pointing to removed scripts like:
  • bash $HOME/.codex/hooks/keyword-detector.sh
  • bash $HOME/.codex/hooks/persistent-mode.sh
  • bash $HOME/.codex/hooks/session-start.sh
Diagnosis:
  • If found: CRITICAL - legacy hooks causing duplicates
首先检查
~/.codex/config.toml
（当前Codex配置），仅当旧版
~/.codex/settings.json
存在时再检查该文件。
查找指向已移除脚本的钩子条目，例如：
  • bash $HOME/.codex/hooks/keyword-detector.sh
  • bash $HOME/.codex/hooks/persistent-mode.sh
  • bash $HOME/.codex/hooks/session-start.sh
诊断结果：
  • 如找到上述条目：严重 - 旧版钩子会导致重复执行问题

Step 3: Check for Legacy Bash Hook Scripts

步骤3：检查旧版Bash钩子脚本

bash
ls -la ~/.codex/hooks/*.sh 2>/dev/null
Diagnosis:
  • If 
    keyword-detector.sh
    , 
    persistent-mode.sh
    , 
    session-start.sh
    , or 
    stop-continuation.sh
    exist: WARN - legacy scripts (can cause confusion)
bash
ls -la ~/.codex/hooks/*.sh 2>/dev/null
诊断结果：
  • 如存在
    keyword-detector.sh
    、
    persistent-mode.sh
    、
    session-start.sh
    或
    stop-continuation.sh
    ：警告 - 旧版脚本（可能造成使用混淆）

Step 4: Check AGENTS.md

步骤4：检查AGENTS.md

bash
undefined
bash
undefined

Check if AGENTS.md exists

Check if AGENTS.md exists

ls -la ~/.codex/AGENTS.md 2>/dev/null
ls -la ~/.codex/AGENTS.md 2>/dev/null

Check for OMX marker

Check for OMX marker

grep -q "oh-my-codex Multi-Agent System" ~/.codex/AGENTS.md 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"

**Diagnosis**:
- If missing: CRITICAL - AGENTS.md not configured
- If missing OMX marker: WARN - outdated AGENTS.md
grep -q "oh-my-codex Multi-Agent System" ~/.codex/AGENTS.md 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"

**诊断结果**：
- 如文件不存在：严重 - AGENTS.md未配置
- 如缺少OMX标记：警告 - AGENTS.md版本过旧

Step 5: Check for Stale Plugin Cache

步骤5：检查过时的插件缓存

bash
undefined
bash
undefined

Count versions in cache

Count versions in cache

ls ~/.codex/plugins/cache/omc/oh-my-codex/ 2>/dev/null | wc -l

**Diagnosis**:
- If > 1 version: WARN - multiple cached versions (cleanup recommended)
ls ~/.codex/plugins/cache/omc/oh-my-codex/ 2>/dev/null | wc -l

**诊断结果**：
- 如版本数>1：警告 - 存在多个缓存版本（建议清理）

Step 6: Check for Legacy Curl-Installed Content

步骤6：检查旧版Curl安装的内容

Check for legacy agents, commands, and historical legacy skill roots from older installs/migrations:
bash
undefined
检查旧版安装/迁移遗留的旧版agents、commands和历史旧版skill根目录：
bash
undefined

Check for legacy agents directory

Check for legacy agents directory

ls -la ~/.codex/agents/ 2>/dev/null
ls -la ~/.codex/agents/ 2>/dev/null

Check for legacy commands directory

Check for legacy commands directory

ls -la ~/.codex/commands/ 2>/dev/null
ls -la ~/.codex/commands/ 2>/dev/null

Check canonical current skills directory

Check canonical current skills directory

ls -la ${CODEX_HOME:-~/.codex}/skills/ 2>/dev/null
ls -la ${CODEX_HOME:-~/.codex}/skills/ 2>/dev/null

Check historical legacy skill directory

Check historical legacy skill directory

ls -la ~/.agents/skills/ 2>/dev/null

**Diagnosis**:
- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy agents (now provided by plugin)
- If `~/.codex/commands/` exists with oh-my-codex-related files: WARN - legacy commands (now provided by plugin)
- If `${CODEX_HOME:-~/.codex}/skills/` exists with OMX skills: OK - canonical current user skill root
- If `~/.agents/skills/` exists: WARN - historical legacy skill root that can overlap with `${CODEX_HOME:-~/.codex}/skills/` and cause duplicate Enable/Disable Skills entries

Look for files like:
- `architect.md`, `researcher.md`, `explore.md`, `executor.md`, etc. in agents/
- `ultrawork.md`, `deepsearch.md`, etc. in commands/
- Any oh-my-codex-related `.md` files in skills/

---
ls -la ~/.agents/skills/ 2>/dev/null

**诊断结果**：
- 如`~/.codex/agents/`存在且包含oh-my-codex相关文件：警告 - 旧版agents（现在已由插件提供）
- 如`~/.codex/commands/`存在且包含oh-my-codex相关文件：警告 - 旧版commands（现在已由插件提供）
- 如`${CODEX_HOME:-~/.codex}/skills/`存在且包含OMX技能：正常 - 标准的当前用户技能根目录
- 如`~/.agents/skills/`存在：警告 - 历史遗留的旧版技能根目录，可能与`${CODEX_HOME:-~/.codex}/skills/`冲突，导致技能启用/禁用条目重复

查找以下类型的文件：
- agents/目录下的`architect.md`、`researcher.md`、`explore.md`、`executor.md`等
- commands/目录下的`ultrawork.md`、`deepsearch.md`等
- skills/目录下任何与oh-my-codex相关的`.md`文件

---

Report Format

报告格式

After running all checks, output a report:
undefined
运行所有检查后，输出如下报告：
undefined

OMX Doctor Report

OMX诊断工具报告

Summary

概要

[HEALTHY / ISSUES FOUND]
[正常 / 发现问题]

Checks

检查项

CheckStatusDetails
Plugin VersionOK/WARN/CRITICAL...
Hook Config (config.toml / legacy settings.json)OK/CRITICAL...
Legacy Scripts (~/.codex/hooks/)OK/WARN...
AGENTS.mdOK/WARN/CRITICAL...
Plugin CacheOK/WARN...
Legacy Agents (~/.codex/agents/)OK/WARN...
Legacy Commands (~/.codex/commands/)OK/WARN...
Skills (${CODEX_HOME:-~/.codex}/skills)OK/WARN...
Legacy Skill Root (~/.agents/skills)OK/WARN...
检查项状态详情
插件版本正常/警告/严重...
钩子配置（config.toml / 旧版settings.json）正常/严重...
旧版脚本（~/.codex/hooks/）正常/警告...
AGENTS.md正常/警告/严重...
插件缓存正常/警告...
旧版Agents（~/.codex/agents/）正常/警告...
旧版Commands（~/.codex/commands/）正常/警告...
技能目录（${CODEX_HOME:-~/.codex}/skills）正常/警告...
旧版技能根目录（~/.agents/skills）正常/警告...

Issues Found

发现的问题

  1. [Issue description]
  2. [Issue description]
  1. [问题描述]
  2. [问题描述]

Recommended Fixes

建议修复方案

[List fixes based on issues]

---
[根据发现的问题列出修复方法]

---

Auto-Fix (if user confirms)

自动修复（需用户确认）

If issues found, ask user: "Would you like me to fix these issues automatically?"
If yes, apply fixes:
如果发现问题，询问用户："你希望我自动修复这些问题吗？"
如果用户同意，执行以下修复：

Fix: Legacy Hooks in legacy settings.json

修复：旧版settings.json中的旧版钩子

If 
~/.codex/settings.json
exists, remove the legacy 
"hooks"
section (keep other settings intact).
如果
~/.codex/settings.json
存在，删除旧版的
"hooks"
部分（保留其他设置不变）。

Fix: Legacy Bash Scripts

修复：旧版Bash脚本

bash
rm -f ~/.codex/hooks/keyword-detector.sh
rm -f ~/.codex/hooks/persistent-mode.sh
rm -f ~/.codex/hooks/session-start.sh
rm -f ~/.codex/hooks/stop-continuation.sh
bash
rm -f ~/.codex/hooks/keyword-detector.sh
rm -f ~/.codex/hooks/persistent-mode.sh
rm -f ~/.codex/hooks/session-start.sh
rm -f ~/.codex/hooks/stop-continuation.sh

Fix: Outdated Plugin

修复：版本过旧的插件

bash
rm -rf ~/.codex/plugins/cache/omc/oh-my-codex
echo "Plugin cache cleared. Restart Codex CLI to fetch latest version."
bash
rm -rf ~/.codex/plugins/cache/omc/oh-my-codex
echo "Plugin cache cleared. Restart Codex CLI to fetch latest version."

Fix: Stale Cache (multiple versions)

修复：过时缓存（多个版本）

bash
undefined
bash
undefined

Keep only latest version

Keep only latest version

cd ~/.codex/plugins/cache/omc/oh-my-codex/ ls | sort -V | head -n -1 | xargs rm -rf
undefined
cd ~/.codex/plugins/cache/omc/oh-my-codex/ ls | sort -V | head -n -1 | xargs rm -rf
undefined

Fix: Missing/Outdated AGENTS.md

修复：缺失/版本过旧的AGENTS.md

Fetch latest from GitHub and write to 
~/.codex/AGENTS.md
:
WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-codex/main/docs/AGENTS.md", prompt: "Return the complete raw markdown content exactly as-is")
从GitHub拉取最新版本并写入
~/.codex/AGENTS.md
：
WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-codex/main/docs/AGENTS.md", prompt: "Return the complete raw markdown content exactly as-is")

Fix: Legacy Curl-Installed Content

修复：旧版Curl安装的内容

Remove legacy agents/commands plus the historical 
~/.agents/skills
tree if it overlaps with the canonical 
${CODEX_HOME:-~/.codex}/skills
install:
bash
undefined
如果旧版agents/commands以及历史
~/.agents/skills
目录与标准的
${CODEX_HOME:-~/.codex}/skills
安装冲突，删除这些内容：
bash
undefined

Backup first (optional - ask user)

先备份（可选 - 询问用户）

mv ~/.codex/agents ~/.codex/agents.bak

mv ~/.codex/agents ~/.codex/agents.bak

mv ~/.codex/commands ~/.codex/commands.bak

mv ~/.codex/commands ~/.codex/commands.bak

mv ~/.agents/skills ~/.agents/skills.bak

mv ~/.agents/skills ~/.agents/skills.bak

Or remove directly

或者直接删除

rm -rf ~/.codex/agents rm -rf ~/.codex/commands rm -rf ~/.agents/skills

**Note**: Only remove if these contain oh-my-codex-related files. If user has custom agents/commands/skills, warn them and ask before removing.

---
rm -rf ~/.codex/agents rm -rf ~/.codex/commands rm -rf ~/.agents/skills

**注意**：仅当这些目录包含oh-my-codex相关文件时再删除。如果用户有自定义的agents/commands/skills，删除前需警告用户并征得同意。

---

Post-Fix

修复后操作

After applying fixes, inform user:
Fixes applied. Restart Codex CLI for changes to take effect.
应用修复后，告知用户：
修复已完成。请重启Codex CLI使更改生效。