1. 前言 oh-my-codex，简称 OMX，可以理解为 Codex CLI 的工作流增强层。它本身不是 VS Code 插件，也不是一个独立 IDE，而是在命令行里给 Codex CLI 增加 agents、skills、hooks、team runtime、tmux 管理、计划执行等能力。
在 Mac 上使用它做远程调试和开发，推荐的方式是：
1 2 3 4 5 6 Mac Terminal / iTerm2
也就是说，真正执行代码读取、修改、测试、调试命令的是远程服务器上的 omx 和 codex。Mac 只负责 SSH 连接和恢复会话。
2. Mac 本地最佳实践 Mac 本地建议使用 Terminal 或 iTerm2。VS Code 可以负责编辑代码，但不建议把 oh-my-codex 当成 VS Code 扩展使用。
安装基础依赖：
1 2 3 4 brew install node tmux
安装完成后做真实验证：
1 2 3 omx doctorexec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
omx doctor 只说明安装结构基本正常，omx exec 才能验证当前 shell、认证、模型路由和执行链路是否真的可用。
3. 远程服务器安装 以 Ubuntu/Debian 服务器为例：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ssh user@serverexec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
如果是生产服务器，不建议直接用 root 跑长期开发任务。更稳妥的方式是创建单独的 dev 用户，只给项目目录、日志目录和必要服务授权。
4. 远程日常开发方式 登录服务器后创建 tmux 会话：
1 2 ssh user@server
进入项目目录启动 OMX：
1 2 cd /srv/your-project
断线后恢复：
1 2 ssh user@server
小任务可以不用 team/tmux runtime：
1 2 cd /srv/your-project
更重的任务可以使用更高推理强度：
5. VS Code 配合方式 如果想在 VS Code 里使用，建议用两种方式之一：
1 2 方式一：VS Code 本地打开项目，Mac 终端 SSH 到服务器跑 omx
重点是 omx 应该运行在代码和运行环境所在的机器上。远程项目就让 omx 运行在远程服务器上，避免在 Mac 本地反复通过 ssh "command" 间接操作。
6. 调试任务怎么交给 OMX 可以先让它做只读调查：
1 检查当前服务为什么启动失败。先只读查看 package.json、日志、端口占用和环境变量，不要修改文件，最后给出修复计划。
如果问题明确，再让它修复：
1 按计划修复当前服务启动失败的问题，修复后运行测试和健康检查。
常见排查命令包括：
1 2 3 4 5 6 7 rg "error|listen|PORT" .test
在 OMX 会话中，大任务建议按这个顺序处理：
1 2 3 4 $deep-interview "澄清需求、现象、日志路径、复现方式和不能动的边界"
使用判断：
1 2 3 4 5 需求不清：先 $deep-interview
7. 项目内 AGENTS.md 建议每个项目根目录放一个 AGENTS.md，把项目约定写清楚。OMX 会把项目里的 AGENTS.md 注入 Codex。
示例：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 # AGENTS.md ## Commands - Install: npm install- Test: npm test- Lint: npm run lint- Build: npm run build- Dev: npm run dev## Runtime - App port: 3000- Health check: curl -I http://127.0.0.1:3000/health- Logs: docker compose logs --tail=200 app## Rules - Do not edit generated files.- Do not run destructive database commands.- Keep changes scoped to the current task.- Run tests before final response when practical.
.omx/ 通常不要提交到仓库：
.omx/ 里会保存计划、日志、状态、team runtime 和本地运行数据，适合留在本机。
8. 远程 omx doctor 状态说明 下面是一个远程服务器上的 omx doctor 结果：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 Resolved setup scope: user (from .omx/setup-scope.json)
0 failed 说明核心环境可以使用。这里两个 warning 的处理方式如下。
8.1 Explore Harness 警告 这个警告表示 omx explore 需要的 Rust harness 没有可用预编译版本，本机也没有 cargo。普通 omx、$ralph、$team 仍然可用，但 omx explore 可能不可用。
安装 Rust：
1 2 3 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shsource ~/.cargo/env
也可以使用已有 harness：
1 2 export OMX_EXPLORE_BIN=/path/to/omx-explore-harness
8.2 Model context recommendation 警告 这个警告表示当前 config.toml 里的上下文窗口配置超过了 OMX 对 gpt-5.5 的推荐值。
当前值：
1 2 model_context_window = 1000000 model_auto_compact_token_limit = 900000
建议值：
1 2 model_context_window = 250000 model_auto_compact_token_limit = 200000
编辑配置：
1 nano /root/.codex/config.toml
修改后验证：
1 2 3 omx doctorexec --skip-git-repo-check -C /root/outline "Reply with exactly OMX-EXEC-OK"
如果你确认当前 provider 支持更大的上下文，并且成本、速度和自动压缩行为都符合预期，也可以保留自定义值。但默认建议先按 OMX 推荐值配置。
9. 权限和安全边界 远程开发时不要给 Codex 无限制权限。建议遵守这些原则：
1 2 3 4 5 6 1. 不在生产机上直接用 root 长期运行 omx。
如果使用 $team，最好保证 git 工作区干净，或者至少清楚哪些文件是用户正在改的，避免多个 worker 改到同一批文件。
10. 更新和排错 更新 OMX：
1 2 3 4 5 npm install -g oh-my-codexexec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
查看基础环境：
1 2 3 4 5 6 7 8 echo $HOME echo $CODEX_HOME which omxwhich codex
查看 tmux/team 状态：
1 2 3 tmux ls
确认废弃 team 后再清理：
1 2 3 omx team shutdown <team-name> --force --confirm-issues
11. 推荐结论 Mac 命令行使用 oh-my-codex 的最佳实践是：
1 2 3 4 5 6 7 8 Mac 用 Terminal/iTerm2
这样可以让 Codex 在真实运行环境里读代码、改代码、跑测试、看日志和重启服务，同时保留可恢复的远程会话。