CodeGraph 是什么

CodeGraph是一个面向 AI 编程助手的代码图谱工具。它会扫描你的项目代码，建立本地代码索引和代码关系图，让 AI 不只是按文件名和关键字搜索代码，而是可以更结构化地理解项目。
简单说：

• 普通搜索：查“某个词在哪些文件出现”
• CodeGraph：查“这个方法在哪里定义、被谁调用、调用链怎么走、改它可能影响哪些地方”

CodeGraph 通过 MCP 接入 Codex 后，会给 Codex 提供额外的代码理解工具。Codex 在分析复杂项目时，可以利用这些工具查询项目结构、符号关系、上下文源码和影响范围。

为什么需要安装 CodeGraph

Codex 本身已经可以读取文件、搜索代码、修改代码、运行测试。
但在大型项目里，仅靠普通搜索有几个问题：

1. 跨文件调用链不好追
   比如一个 Java 项目里，从 Controller 到 Service，再到 DAO、SQL、配置项，可能分散在很多文件里。普通搜索只能找到关键词出现的位置，但不一定能准确知道真实调用链。

2. 容易漏掉间接影响
   修改一个方法、字段、接口、配置项时，影响范围可能不在当前文件。CodeGraph 可以帮助 Codex 更快定位调用方、被调用方和相关上下文。

3. 减少反复读文件的成本
   对于小项目，直接 rg 搜索就够了。
   但对于几十万行代码的大项目，Codex 如果每次都靠搜索和逐个打开文件，会比较慢，也更容易绕路。

4. 更适合复杂代码理解任务
   CodeGraph 特别适合这些场景：

• 分析一个接口完整业务流程
• 查某个方法被哪些地方调用
• 判断修改某个类会影响哪些功能
• 理解一个模块的入口、核心类、数据流
• 在大项目中定位应该改哪里

5. 让 Codex 多一个“代码地图”
   可以把 CodeGraph 理解成给 Codex 配了一张项目地图。
   没有 CodeGraph 时，Codex 也能走路找代码；有了 CodeGraph 后，Codex 可以先看地图，再决定从哪里切入。

CodeGraph 和 Codex 的关系

CodeGraph 不是 Codex 的替代品，而是 Codex 的辅助工具。

安装前：

Codex -> 读取文件 / 搜索代码 / 修改代码 / 运行测试

安装后：

Codex -> 读取文件 / 搜索代码 / 修改代码 / 运行测试
      -> CodeGraph MCP 查询代码图谱

也就是说，CodeGraph 只是给 Codex 增加了一类 MCP 工具。
Codex 是否使用它，会根据任务判断。

一般规律是：

• 单文件、小范围修改：Codex 可能不会用 CodeGraph
• 跨模块、调用链、影响范围分析：Codex 更可能使用 CodeGraph
• 你明确要求“请优先使用 CodeGraph MCP”：Codex 会优先考虑使用它

安装 CodeGraph CLI

CodeGraph 官方推荐 Windows 使用以下命令安装：
(如果你电脑已经安装 Node.js，也可以选择 npm 方式； irm(Invoke-RestMethod)是 windwos powershell的专属安装指令)

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

安装完成后，关闭当前 PowerShell，重新打开一个新的 PowerShell。
然后验证：

codegraph --help

如果能看到帮助信息，说明 CLI 安装成功。

把 CodeGraph 接入 Codex MCP

安装 CLI 只是第一步，还需要把 CodeGraph 配置到 Codex 的 MCP server 中。
推荐执行：

codegraph install

这个命令会检测并配置你正在使用的 agent，包括 Codex CLI。
如果它要求你选择目标，请选择： Codex CLI

手动检查 Codex 配置

Codex 的全局配置文件默认在：

C:\Users\John\.codex\config.toml

检查里面是否有类似配置：

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]

如果 codegraph install 已经自动写入，就不用重复添加。

为具体代码项目建立 CodeGraph 索引

CodeGraph 需要在每个项目里初始化索引。
进入你的代码项目根目录，例如：

cd E:\developSpace\your-project

执行

codegraph init

执行完成后检查状态：

codegraph status

如果状态正常，并且项目下生成了.codegraph文件夹，说明这个项目已经可以被 CodeGraph 查询。

重启 Codex 并验证 MCP

完成安装和配置后，重启 Codex。
如果你使用 Codex CLI/TUI，可以输入

/mcp

查看当前激活的 MCP server，确认是否能看到：codegraph

Codex 如何使用 CodeGraph MCP

强制codex使用示例

安装成功后，你可以这样要求 Codex：

请优先使用 CodeGraph MCP 分析xxxx功能的调用链。

请用 CodeGraph 看一下修改 XXX 方法会影响哪些地方。

请先用 CodeGraph 理解xxx模块结构，再决定修改方案。

请用 CodeGraph 分析xxx接口从 Controller 到 DAO 的完整流程。

codex自动使用示例

自动使用会提示 这个仓库有 .codegraph，可以直接用索引追代码，后续如果真正用到了也会提示

CodeGraph MCP 适合查询：

• 某个类或方法在哪里定义
• 某个方法被谁调用
• 某个接口的完整业务流程
• 修改某个方法可能影响哪些调用方
• 某个模块有哪些核心入口
• 某个文件或符号相关的上下文源码

常用维护命令

查看版本：

codegraph version

检查状态：

codegraph status

同步或更新索引：

codegraph sync

升级 CodeGraph：

codegraph upgrade

卸载 CodeGraph：

codegraph uninstall

只移除 agent 配置但保留 CLI：

codegraph uninstall --keep-cli

移除某个项目的索引：

codegraph uninit