CodexPro 使用方法：把本地项目接到 ChatGPT 的轻量 MCP 服务

最近我在用 CodexPro 做一件很实用的事：把本地项目目录接到 ChatGPT，让它能围绕真实工程文件读代码、改代码、查日志、跑命令，而不是每次手动复制一段代码过去问。

这篇文章整理一下 CodexPro 的基本用法，以及我在 macOS 和 WSL 里配置自启动服务的实践。

CodexPro 是什么

CodexPro 可以理解成一个本地 MCP 启动器。它会在你的电脑上启动一个 MCP Server，然后把某个工作目录暴露给 ChatGPT。

默认本地地址通常是：

http://127.0.0.1:8787/mcp

连接之后，ChatGPT 就可以在你授权的目录里做这些事：

读取项目文件
搜索代码
创建或修改文件
执行受控 bash 命令
把任务计划交给本地 agent 执行
给不能直接调用 MCP 工具的模型导出上下文

重点不是“又多一个 AI 工具”，而是让 ChatGPT 真正进入项目上下文。

安装

前提是本机有 Node.js 20 以上版本。

npm install -g codexpro

安装后先看帮助：

codexpro --help

常用命令：

codexpro setup
codexpro start
codexpro start --root /path/to/repo
codexpro settings
codexpro doctor

doctor 很适合排查环境问题，它会检查 Node 版本、构建产物、保存的 profile、端口占用和 tunnel 配置。

指定工作目录

CodexPro 最重要的参数是 --root，它决定 ChatGPT 能访问哪个目录。

只暴露单个项目：

codexpro start --root /Users/yourname/Desktop/AllProjects/YourProject

暴露一个项目集合目录：

codexpro --root /Users/yourname/Desktop/AllProjects

个人建议：日常开发优先给具体项目目录，不要随手暴露整个 home。范围越小，越安全，也越不容易误改无关文件。

启动本地 MCP 服务

临时启动可以直接：

cd /path/to/repo
codexpro

或者显式指定 root：

codexpro --root /path/to/repo

默认会监听：

127.0.0.1:8787

启动成功后，通常会看到类似输出：

CodexPro ready
Local MCP ready at http://127.0.0.1:8787/mcp

如果用 curl 访问返回 401 Unauthorized，通常说明服务已经起来了，只是需要 token 鉴权。

curl -I http://127.0.0.1:8787/mcp

常用模式

agent 模式

默认模式。ChatGPT 可以通过 MCP 工具读写文件、搜索、执行安全 bash。

codexpro start --root /path/to/repo --mode agent

适合日常开发：修 bug、改 UI、跑测试、做小型重构。

handoff 模式

ChatGPT 不直接改源码，而是把计划写到 .ai-bridge 目录，再由本地实现 agent 执行。

codexpro start --root /path/to/repo --mode handoff

执行一次 handoff：

codexpro execute-handoff --agent opencode --model provider/model

持续监听 handoff：

codexpro watch-handoff --agent opencode --model provider/model --yes

适合“ChatGPT 负责规划，本地 agent 负责落地”的工作流。

pro 模式

如果当前模型不能直接调用 MCP 工具，可以用 pro 模式导出上下文：

codexpro pro-bundle --root /path/to/repo --copy

也可以应用已有计划：

codexpro pro-apply --root /path/to/repo --file plan.md

安全参数

几个值得优先理解的参数：

--bash <off|safe|full>
--write <off|handoff|workspace>
--tool-mode <minimal|standard|full>

日常开发可以先用：

codexpro --root /path/to/repo --bash safe --write workspace --tool-mode standard

如果只想让 ChatGPT 看代码，不允许改文件、不允许跑命令：

codexpro --root /path/to/repo --write off --bash off

如果是完全信任的本地开发环境，才考虑把 bash 放到 full。远程暴露时尤其要谨慎。

macOS：配置开机自启

在 macOS 上可以用 LaunchAgent 做自启动。

一个实践坑：不要让 launchd 直接把 WorkingDirectory 设到 ~/Desktop/...。macOS 的隐私权限可能会让后台服务卡在 getcwd()，表现为进程存在，但 8787 端口没有监听。

更稳的方式是：进程从 home 启动，再用 --root 指定工作目录。

示例启动脚本：

#!/bin/bash
set -euo pipefail
export HOME=/Users/yourname
export PATH=/Users/yourname/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
cd /Users/yourname
exec /Users/yourname/.npm-global/bin/codexpro --root /Users/yourname/Desktop/AllProjects

LaunchAgent 里调用这个脚本即可。

如果你还配置了 frp，把本机 8787 映射到服务器端口，例如 58787，那外部就可以通过服务器端口访问这个 MCP 服务。但这类服务具备本地文件操作能力，必须保证 token 不泄露，最好再叠加访问控制。

WSL：systemd 服务示例

在 WSL 里，我的一个项目示例是把 CodexPro 做成 systemd 服务，让它随 WSL 环境启动。

服务文件路径：

sudo nano /etc/systemd/system/codexpro-cfhumidity.service

示例内容：

[Unit]
Description=CodexPro MCP - CFHumiditySensor
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=wztong
WorkingDirectory=/mnt/c/Users/17489/Documents/研究生文件/毕业设计
Environment=CODEXPRO_BASH_MODE=full
Environment=HOME=/home/wztong
Environment=PATH=/home/wztong/.nvm/versions/node/v24.14.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/home/wztong/.nvm/versions/node/v24.14.0/bin/codexpro start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

几个点需要注意：

WorkingDirectory 指向实际项目目录。
User 要换成自己的 WSL 用户名。
PATH 要包含 Node / nvm 里的 bin 目录，否则 systemd 找不到 node 或 codexpro。
CODEXPRO_BASH_MODE=full 代表允许完整 bash 能力，只建议在自己可信的环境里使用。
如果不想给完整命令权限，可以改成 safe 模式，或者不要设置这个变量。

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable codexpro-cfhumidity.service
sudo systemctl start codexpro-cfhumidity.service

查看状态：

systemctl status codexpro-cfhumidity.service

看日志：

journalctl -u codexpro-cfhumidity.service -f

如果服务起不来，优先查这三件事：

which node
which codexpro
codexpro doctor

systemd 的环境和你手动打开 shell 的环境不一样，很多问题都是 PATH 不完整导致的。

排查端口占用

如果 codexpro doctor 提示：

FAIL Local port 8787 is already in use

说明 8787 已经被占用。可能是 CodexPro 已经在跑，也可能是别的服务占了端口。

macOS：

lsof -nP -iTCP:8787 -sTCP:LISTEN

Linux / WSL：

ss -ltnp | grep 8787

如果服务已经正常监听，再访问 MCP 地址却看到 401 Unauthorized，通常不是故障，而是鉴权生效。

总结

CodexPro 最适合解决一个老问题：AI 不知道你的真实项目上下文。

它把 ChatGPT 接到本地工程目录，让它能基于真实文件做判断，而不是靠你手动复制片段。配置好以后，修 bug、查代码、跑测试、写计划都会顺很多。

但它的能力也意味着边界要管住：

--root 不要给得太大
远程暴露要有鉴权
token 不要贴到公开环境
日志里最好做脱敏
full bash 只在可信环境开启

一句话：CodexPro 适合把 ChatGPT 变成你的本地开发搭子，但别忘了给它划好活动范围。