oh-my-codex Demo 实战指南从安装到多智能体团队编排的完整演示【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex本指南围绕 oh-my-codex 官方 DEMO.md 展开系统覆盖从「2 分钟安装初始化」到「9 个可复制演示」的全过程包括 Agent 关键词调用、AGENTS.md 编排大脑、MCP 状态管理、tmux 多智能体团队编排与omx team apiCLI 互操作。读完本文你将掌握 oh-my-codex 的完整安装验证流程、逐条可运行的演示命令及其预期输出并理解每个演示背后的源码实现位置可直接照搬用于自己的项目验证。前置条件在开始之前请确保环境满足以下要求Node.js 20Codex CLI已安装npm install -g openai/codexOpenAI API key已配置安装与初始化Setup 2 分钟oh-my-codex 的安装分为「克隆并构建」与「运行 setup」两个阶段# Clone and install git clone https://gitcode.com/GitHub_Trending/oh/oh-my-codex.git cd oh-my-codex npm install npm run build npm link # Run setup (installs prompts, skills, configures Codex CLI) omx setupomx setup的执行逻辑位于 src/cli/setup.ts它会依次创建目录、安装 Agent prompts、安装 skills、更新config.toml、验证 Team MCP 通信工具、生成 AGENTS.md、配置通知钩子与 HUD。预期输出如下oh-my-codex setup [1/7] Creating directories... Done. [2/7] Installing agent prompts... Installed 30 agent prompts. [3/7] Installing skills... Installed 40 skills. [4/7] Updating config.toml... Done. [4.5/7] Verifying Team MCP comm tools... omx_state exports: team_send_message, team_broadcast, team_mailbox_list, team_mailbox_mark_delivered [5/7] Generating AGENTS.md... Generated AGENTS.md in project root. # (or: AGENTS.md already exists, use --force to overwrite) [6/7] Configuring notification hook... Done. [7/7] Configuring HUD... HUD config created (preset: focused). StatusLine configured in config.toml via [tui] section. Setup complete! Run omx doctor to verify installation.从源码结构看setup 通过 config/generator.ts 中的buildMergedConfig合并写入 Codex CLI 配置HUD 预设则通过 hud/types.ts 的DEFAULT_HUD_CONFIG定义支持minimal、focused、full三种预设见 setup.ts 的 resolveStatusLinePresetForSetup。若 AGENTS.md 已存在setup 默认不会覆盖需显式传入--force。验证安装omx doctor预期输出oh-my-codex doctor [OK] Codex CLI: installed [OK] Node.js: v20 [OK] Codex home: ~/.codex [OK] Config: config.toml has OMX entries [OK] Prompts: 30 agent prompts installed [OK] Skills: 40 skills installed [OK] AGENTS.md: found in project root [OK] State dir: .omx/state [OK] MCP Servers: 4 servers configured (OMX present) Results: 9 passed, 0 warnings, 0 failedDemo 1Agent / Skill 关键词调用在任意项目目录启动 Codex CLIomx然后在会话中使用角色与工作流关键词 $architect analyze the authentication module预期效果architect agent 会输出带 file:line 引用、根因诊断与取舍trade-off分析。 $security-reviewer review the API endpoints预期效果输出 OWASP Top 10 分析按严重度排序并附带修复代码示例。 $explore find all database query patterns预期效果结构化代码库搜索返回文件清单与模式摘要。这些角色关键词来自 setup 阶段安装到~/.codex/prompts/*.md的 30 个 Agent prompts仓库中的角色定义集中在 src/agents/definitions.ts。Demo 2AGENTS.md 编排大脑setup 在项目根目录生成的AGENTS.md充当编排大脑提供委派规则何时使用哪个 AgentAGENTS.md 中的模型路由指引按复杂度 / 角色路由30 个 Agent 的目录与描述40 个 Skill 的描述与触发模式常见工作流的团队组合验证协议Codex CLI 会在会话启动时自动加载该文件。其生成与合并逻辑位于 src/utils/agents-md.jsupsertManagedAgentsBlock、preserveUserOmxPolicyBlocks等意味着 setup 会保留用户自定义的策略块、只管理 OMX 托管的段落。Demo 3CLI 状态命令# Check version omx version # Check all active modes omx status # Cancel any active mode omx cancelomx version预期输出oh-my-codex vX.Y.Z Node.js v20 Platform: linux x64omx status无活动模式时预期输出No active modes.omx status/omx cancel背后是 mode 状态管理相关实现见 src/modes/base.tsupdateModeState、startMode、readModeState状态文件路径由 src/mcp/state-paths.ts 的getStatePath解析。Demo 4Codex CLI 中的 SkillsSkills 会被 Codex CLI 自动发现。在 Codex 会话中 $autopilot build a REST API for task management预期效果完整自主流水线需求分析 - 技术设计 - 并行实现 - QA 循环 - 多视角验证。 $team 3:executor fix all TypeScript errors预期效果生成 3 个协调工作的 executor agent共享任务列表运行分阶段流水线plan - prd - exec - verify - fix 循环。Skill 定义位于~/.codex/skills/*/SKILL.md仓库中的技能源在 skills/ 目录如 skills/autopilot/SKILL.md、skills/team/SKILL.md。Demo 5MCP 状态管理MCP 服务器配置在config.toml中为 Agent 提供状态 / 记忆工具 Use state_read to check if any modes are active Use project_memory_read to see project context Use notepad_write_working to save a note about current progress预期效果Agent 通过 MCP 工具调用访问.omx/state/与.omx/project-memory.json。config.toml中的 MCP 注册块由 setup 写入首次方 MCP 注册逻辑见 src/config/omx-first-party-mcp.ts状态读写对应 src/mcp/state-server.ts、src/mcp/memory-server.ts 等 4 个 MCP server。Demo 6E2E Team CLI5 并行 Worker混合 Codex/Claude该演示展示基于tmux 的多智能体编排系统在单个 tmux 会话中跨不同 AI CLI 工具Codex Claude生成并行 Worker。架构总览┌─────────────────────────────────────────────────────────────┐ │ tmux Session omx-team │ │ ┌──────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Leader │ │ Worker 1 │ │ Worker 2 │ │ Worker N │ │ │ │ (main pane) │ │ (codex) │ │ (codex) │ │ (claude) │ │ │ └──────────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ └───────────────┴──────────────┴──────────────┘ │ │ │ │ │ ┌──────────┴──────────┐ │ │ │ Shared Task Queue │ │ │ │ (durable state) │ │ │ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘关键特性混合 CLI Worker同一团队内组合 OpenAI Codex 与 Anthropic Claude Agent持久化状态Durable State任务分配在会话中断后仍然保留Claim-Safe 生命周期通过带版本的任务认领versioned task claims防止竞态信箱通信MailboxWorker 之间结构化消息传递快速开始使用确定性的任务 slug使团队名可预测export TEAM_TASKe2e team demo export TEAM_NAMEe2e-team-demo # slugified from TEAM_TASK # Mixed worker CLIs (5 workers, codex claude) export OMX_TEAM_WORKER_CLIauto export OMX_TEAM_WORKER_CLI_MAPcodex,codex,codex,claude,claude,claude export OMX_TEAM_WORKER_LAUNCH_ARGS-c model_reasoning_effortlow # 5-worker baseline omx team 5:executor parallel team smoke # 6-worker mixed-CLI E2E run omx team 6:executor $TEAM_TASK # Discover team command help omx team --help omx team api --help # Lifecycle commands omx team status $TEAM_NAME omx team resume $TEAM_NAME omx team shutdown $TEAM_NAME预期效果团队以 5 Worker 启动打印Team started: team-name及 Worker 数量混合 CLI map 在同一团队中运行 Codex Worker 与 Claude Workerstatus展示任务分配与 Worker 健康状态shutdown清理 Worker 与团队状态团队编排的实现入口在 src/team/runtime.tsstartTeam、resumeTeam、shutdownTeam、monitorTeam任务分配策略见 src/team/allocation-policy.ts。Demo 7omx team api丰富的 CLI 互操作演示所有变更操作都应通过 CLI 互操作omx team api ... --json执行并使用稳定的 JSON envelope。相关实现见 src/team/api-interop.tsTEAM_API_OPERATIONS、resolveTeamApiOperation、executeTeamApiOperation。7.1 任务生命周期claim-safeCREATE_JSON$(omx team api create-task --input {team_name:e2e-team-demo,subject:Demo lifecycle,description:Claim-safe lifecycle demo,owner:worker-1} --json) TASK_ID$(echo $CREATE_JSON | jq -r .data.task.id) CLAIM_JSON$(omx team api claim-task --input {\team_name\:\e2e-team-demo\,\task_id\:\$TASK_ID\,\worker\:\worker-1\,\expected_version\:1} --json) CLAIM_TOKEN$(echo $CLAIM_JSON | jq -r .data.claimToken) omx team api transition-task-status --input {\team_name\:\e2e-team-demo\,\task_id\:\$TASK_ID\,\from\:\in_progress\,\to\:\completed\,\claim_token\:\$CLAIM_TOKEN\} --json核心流程为create-task创建任务-claim-task带expected_version认领-transition-task-status携带claim_token迁移状态从机制上保证只有持有效 claim token 的 Worker 才能推进任务状态。7.2 信箱 / 消息流omx team api send-message --input {team_name:e2e-team-demo,from_worker:leader-fixed,to_worker:worker-1,body:ACK: worker-1 ready} --json omx team api broadcast --input {team_name:e2e-team-demo,from_worker:leader-fixed,body:Sync checkpoint} --json MAILBOX_JSON$(omx team api mailbox-list --input {team_name:e2e-team-demo,worker:worker-1} --json) MESSAGE_ID$(echo $MAILBOX_JSON | jq -r .data.messages[0].message_id // empty) omx team api mailbox-mark-notified --input {\team_name\:\e2e-team-demo\,\worker\:\worker-1\,\message_id\:\$MESSAGE_ID\} --json omx team api mailbox-mark-delivered --input {\team_name\:\e2e-team-demo\,\worker\:\worker-1\,\message_id\:\$MESSAGE_ID\} --json7.3 完整操作矩阵广覆盖omx team api read-task --input {team_name:e2e-team-demo,task_id:TASK_ID} --json omx team api list-tasks --input {team_name:e2e-team-demo} --json omx team api update-task --input {team_name:e2e-team-demo,task_id:TASK_ID,description:Updated via CLI interop} --json omx team api release-task-claim --input {team_name:e2e-team-demo,task_id:TASK_ID,claim_token:CLAIM_TOKEN,worker:worker-1} --json omx team api read-config --input {team_name:e2e-team-demo} --json omx team api read-manifest --input {team_name:e2e-team-demo} --json omx team api read-worker-status --input {team_name:e2e-team-demo,worker:worker-1} --json omx team api read-worker-heartbeat --input {team_name:e2e-team-demo,worker:worker-1} --json omx team api update-worker-heartbeat --input {team_name:e2e-team-demo,worker:worker-1,pid:12345,turn_count:12,alive:true} --json omx team api write-worker-inbox --input {team_name:e2e-team-demo,worker:worker-1,content:# Inbox update\nProceed with task 2.} --json omx team api write-worker-identity --input {team_name:e2e-team-demo,worker:worker-9,index:9,role:executor} --json omx team api append-event --input {team_name:e2e-team-demo,type:task_completed,worker:worker-1,task_id:TASK_ID,reason:demo} --json omx team api get-summary --input {team_name:e2e-team-demo} --json omx team api write-shutdown-request --input {team_name:e2e-team-demo,worker:worker-1,requested_by:leader-fixed} --json omx team api read-shutdown-ack --input {team_name:e2e-team-demo,worker:worker-1} --json omx team api read-monitor-snapshot --input {team_name:e2e-team-demo} --json omx team api write-monitor-snapshot --input {team_name:e2e-team-demo,snapshot:{taskStatusById:{1:completed},workerAliveByName:{worker-1:true},workerStateByName:{worker-1:idle},workerTurnCountByName:{worker-1:12},workerTaskIdByName:{worker-1:1},mailboxNotifiedByMessageId:{},completedEventTaskIds:{1:true}}} --json omx team api read-task-approval --input {team_name:e2e-team-demo,task_id:TASK_ID} --json omx team api write-task-approval --input {team_name:e2e-team-demo,task_id:TASK_ID,status:approved,reviewer:leader-fixed,decision_reason:demo approval,required:true} --json omx team api cleanup --input {team_name:e2e-team-demo} --json7.4 验证预期# Envelope checks (schema_version operation ok) omx team api get-summary --input {team_name:e2e-team-demo} --json | jq -e .schema_version 1.0 and .operation get-summary and (.ok true or .ok false) # Team lifecycle checks omx team status e2e-team-demo omx team shutdown e2e-team-demo成功标准所有omx team api示例均返回合法 JSON envelope任务生命周期遵循create-task - claim-task - transition-task-status消息生命周期遵循send-message/broadcast - mailbox-list - mailbox-mark-*团队生命周期演示omx team、omx team status、omx team resume、omx team shutdownDemo 8One-Shot E2E 脚本复制即用使用仓库内置的辅助脚本源码位于 src/scripts/demo-team-e2e.sh安装后位于scripts/下chmod x scripts/demo-team-e2e.sh ./scripts/demo-team-e2e.sh可选覆盖项TEAM_TASKe2e team demo \ TEAM_NAMEe2e-team-demo \ WORKER_COUNT6 \ OMX_TEAM_WORKER_LAUNCH_MODEprompt \ ./scripts/demo-team-e2e.sh等价的纯手工 one-shot 命令块set -euo pipefail export TEAM_TASKe2e team demo export TEAM_NAMEe2e-team-demo export OMX_TEAM_WORKER_CLIauto export OMX_TEAM_WORKER_CLI_MAPcodex,codex,codex,claude,claude,claude export OMX_TEAM_WORKER_LAUNCH_ARGS-c model_reasoning_effortlow echo [1/8] start team (6 workers mixed codex/claude) omx team 6:executor $TEAM_TASK echo [2/8] lifecycle status omx team status $TEAM_NAME echo [3/8] create task CREATE_JSON$(omx team api create-task --input {\team_name\:\$TEAM_NAME\,\subject\:\one-shot lifecycle\,\description\:\demo task\,\owner\:\worker-1\} --json) TASK_ID$(echo $CREATE_JSON | jq -r .data.task.id) echo [4/8] claim task CLAIM_JSON$(omx team api claim-task --input {\team_name\:\$TEAM_NAME\,\task_id\:\$TASK_ID\,\worker\:\worker-1\,\expected_version\:1} --json) CLAIM_TOKEN$(echo $CLAIM_JSON | jq -r .data.claimToken) echo [5/8] transition task - completed omx team api transition-task-status --input {\team_name\:\$TEAM_NAME\,\task_id\:\$TASK_ID\,\from\:\in_progress\,\to\:\completed\,\claim_token\:\$CLAIM_TOKEN\} --json echo [6/8] mailbox flow omx team api send-message --input {\team_name\:\$TEAM_NAME\,\from_worker\:\leader-fixed\,\to_worker\:\worker-1\,\body\:\ACK one-shot\} --json MAILBOX_JSON$(omx team api mailbox-list --input {\team_name\:\$TEAM_NAME\,\worker\:\worker-1\} --json) MESSAGE_ID$(echo $MAILBOX_JSON | jq -r .data.messages[0].message_id // empty) omx team api mailbox-mark-notified --input {\team_name\:\$TEAM_NAME\,\worker\:\worker-1\,\message_id\:\$MESSAGE_ID\} --json omx team api mailbox-mark-delivered --input {\team_name\:\$TEAM_NAME\,\worker\:\worker-1\,\message_id\:\$MESSAGE_ID\} --json echo [7/8] summary envelope check omx team api get-summary --input {\team_name\:\$TEAM_NAME\} --json | jq -e .schema_version 1.0 and .operation get-summary and .ok true echo [8/8] shutdown cleanup omx team shutdown $TEAM_NAME omx team api cleanup --input {\team_name\:\$TEAM_NAME\} --json echo E2E demo complete.预期效果团队以 6 个混合 Worker 启动Claim-safe 生命周期端到端成功summary envelope 校验返回退出码 0团队干净关闭且状态清理完成Demo 9Autoresearch Showcase HubOMX 内置了一个轻量级研究展示中心用于可复现的 autoresearch 演示索引见 playground/README.md。快速开始# list bundled showcase missions ./scripts/run-autoresearch-showcase.sh --list # run one showcase ./scripts/run-autoresearch-showcase.sh bayesopt # run several showcases back-to-back ./scripts/run-autoresearch-showcase.sh omx-self ml-tabular bayesopt展示中心按「playground 演示代码 missions 任务契约 eval 评估脚本」组织。例如bayesopt对应 missions/noisy-bayesopt-highdim/ 与 playground/bayesopt_highdim_demo/omx-self对应 missions/in-action-cat-shellout-demo/sorting对应 missions/adaptive-sort-optimization/ 等。也可以绕过 supervisor 直接运行评估器例如python3 scripts/eval-noisy-bayesopt-highdim.py。运行时产物含.omx/logs/下的迭代账本应保持本地化不提交进仓库。Demo 脚本参考scripts/demo-team-e2e.sh该内置 E2E 脚本提供了对 tmux claude workers demo 的完整自动化测试全面覆盖主要特性。源码位于 src/scripts/demo-team-e2e.sh脚本通过set -euo pipefail严格模式运行并在 EXIT trap 中兜底执行omx team api cleanup以保证资源释放。脚本特性特性描述混合 CLI Workers自动在 Codex 与 Claude CLI 之间分配 WorkerClaim-Safe 生命周期演示正确的 task claim - transition - completion 流程信箱通信测试消息发送与信箱操作Envelope 校验校验所有 API 调用的 JSON 响应 schema自动清理基于 trap 的清理保证退出时释放资源环境变量变量默认值描述WORKER_COUNT6生成的 Worker 数量最小5TEAM_TASKe2e team demo timestamp团队的任务描述TEAM_NAME由 TEAM_TASK slug 化而来唯一团队标识OMX_TEAM_WORKER_CLIautoWorker CLI 选择模式OMX_TEAM_WORKER_CLI_MAP自动生成每个 Worker 的 CLI 分配逗号分隔OMX_TEAM_WORKER_LAUNCH_ARGS-c model_reasoning_effortlow传给 Worker CLI 的参数Worker 模型回退到OMX_DEFAULT_SPARK_MODEL脚本会在启动时校验WORKER_COUNT必须是正整数且 5若显式提供OMX_TEAM_WORKER_CLI_MAP其条目数必须与WORKER_COUNT一致。默认 CLI map 的分配逻辑在build_default_cli_map中对 6 个 Worker 生成 2 个 codex 4 个 claude突出混合演示效果。团队名通过slugify小写化 非字母数字替换为- 截断至 30 字符从TEAM_TASK推导。演示流程[1/8] Start team → Creates tmux session with N mixed workers [2/8] Status check → Verifies all workers are healthy [3/8] Create task → Creates a test task in the shared queue [4/8] Claim task → Worker-1 claims the task with version token [5/8] Complete task → Transitions task to completed status [6/8] Mailbox flow → Sends message and validates delivery [7/8] Summary check → Validates JSON envelope schema [8/8] Cleanup → Graceful shutdown and state cleanup退出码代码含义0所有检查通过1缺少依赖或输入无效1任务生命周期或 API 调用失败自定义配置示例# Run with 8 workers and custom task WORKER_COUNT8 \ TEAM_TASKload test $(date %s) \ OMX_TEAM_WORKER_CLI_MAPcodex,codex,codex,codex,claude,claude,claude,claude \ ./scripts/demo-team-e2e.sh文件清单组件数量位置Agent prompts30~/.codex/prompts/*.mdSkills40~/.codex/skills/*/SKILL.mdMCP servers4配置于~/.codex/config.tomlCLI commands11omx (launch), setup, doctor, team, version, tmux-hook, hud, status, cancel, reasoning, helpAGENTS.md1项目根目录由 setup 生成各组件在仓库中的对应源码Agent prompts 定义于 prompts/ 与 src/agents/definitions.tsSkills 位于 skills/MCP server 实现位于 src/mcp/CLI 命令入口位于 src/cli/。故障排查Codex CLI 未找到使用npm install -g openai/codex安装。Slash 命令未出现运行omx setup --force重装 prompts。MCP servers 未连接检查~/.codex/config.toml中的[mcp_servers.omx_state]、[mcp_servers.omx_memory]、[mcp_servers.omx_code_intel]与[mcp_servers.omx_trace]条目。Doctor 显示警告运行omx setup安装缺失组件。以上 9 个演示覆盖了 oh-my-codex 从单 Agent 关键词、AGENTS.md 编排、MCP 状态管理到 tmux 多 Worker 团队编排与omx team apiCLI 互操作的完整能力面。建议按顺序执行先omx setupomx doctor确认环境再以 Demo 6/7/8 验证团队运行时最后用 Demo 9 体验 autoresearch 的可复现研究闭环。所有命令均可在本仓库源码中找到对应实现便于深入阅读与二次开发。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考