JetBrains Context 配置 Codex 与 Claude Code 教程

本文介绍如何安装 JetBrains Context CLI，并将它接入 OpenAI Codex 与 Claude Code，为 AI 编程助手提供代码索引和语义搜索能力。

一、功能说明

完成配置后：

• Codex 和 Claude Code 可以通过 jbcontext search 按代码含义查找实现，而不只依赖关键词。
• 进入或退出会话时可以自动更新项目索引。
• Codex 会获得 context-search Skill、MCP 服务和只读命令规则。
• Claude Code 会获得 context-search Skill、context-explorer 子代理、MCP 服务和 Hooks。
• 配置默认安装到当前用户目录，不会修改项目业务代码。

二、环境要求

• 已安装 Codex CLI 或 Claude Code。
• macOS 或 Linux 使用 Bash/Zsh 终端。
• 能访问 JetBrains 下载和登录服务。
• JetBrains Context CLI 当前需要登录 JetBrains 账号并接受相关用户协议。确认现有工具：

codex --version
claude --version

只使用其中一个 AI 编程工具时，另一个命令不存在不影响配置。

三、安装 JetBrains Context CLI

执行官方安装脚本：

curl -fsSL https://download.jetbrains.com/jetbrains-context/release/download-jbcontext.sh | bash

安装程序通常会将 CLI 写入：

~/.jbcontext/bin

重新加载 Shell 配置：

source ~/.zshrc

使用 Bash 时执行：

source ~/.bashrc

验证安装：

command -v jbcontext<br>jbcontext --version<br>jbcontext --help

如果仍提示 command not found: jbcontext，可以先使用完整路径：

~/.jbcontext/bin/jbcontext --help

也可以手动将目录加入 PATH：

echo 'export PATH="$PATH:$HOME/.jbcontext/bin"' >> ~/.zshrc<br>source ~/.zshrc<br>rehash

四、登录 JetBrains Context

执行：

jbcontext login

按照终端和浏览器提示完成以下操作：

1. 登录 JetBrains 账号。
2. 授权 JetBrains Context CLI。
3. 阅读并确认 JetBrains Context CLI 用户协议。成功后终端会显示登录成功信息。

五、配置 Codex

推荐使用用户级自动配置：

jbcontext setup-agent --agent codex --auto --scope user

需要在脚本或无人值守环境中执行时：

jbcontext setup-agent --agent codex --auto --scope user --non-interactive

该命令通常会配置：

• ~/.codex/config.toml：MCP 服务和 Hooks。
• ~/.codex/AGENTS.md：语义搜索使用说明。
• ~/.agents/skills/context-search/SKILL.md：语义搜索 Skill。
• ~/.codex/rules/jbcontext.rules：只读搜索命令放行规则。配置完成后，完全退出并重新启动 Codex，使 MCP、Hooks 和 Skill 生效。在 Codex 中可以这样提问：

使用 context-search 查找项目中的用户登录和 Token 校验流程。

先用 jbcontext 语义搜索定位订单退款逻辑，再分析调用链。

六、配置 Claude Code

推荐使用用户级自动配置：

jbcontext setup-agent --agent claude --auto --scope user

需要非交互执行时：

jbcontext setup-agent --agent claude --auto --scope user --non-interactive

该命令通常会配置：

• ~/.claude/settings.json：会话索引和语义搜索提醒 Hooks。
• ~/.claude/CLAUDE.md：Context 使用说明。
• ~/.claude/skills/context-search/SKILL.md：语义搜索 Skill。
• ~/.claude/agents/context-explorer.md：代码探索子代理。
• ~/.claude.json：用户级 jbcontext MCP 服务。配置完成后，完全退出并重新启动 Claude Code。在 Claude Code 中可以这样提问：

调用 context-explorer 查找权限校验的入口和核心实现。

使用 context-search 定位消息重试机制，并列出相关文件。

七、手动索引与搜索

进入需要分析的 Git 项目目录：

cd /path/to/project

建立或更新索引：

jbcontext index

查看状态：

jbcontext status

执行语义搜索：

jbcontext search "用户登录、身份认证和 Token 校验流程"

限定搜索目录：

jbcontext search -p src/auth "JWT Token 的生成与刷新逻辑"

建议使用描述完整意图的自然语言，而不是只输入一个模糊关键词。

八、配置前预览

如果不希望直接修改配置，可以先查看安装计划。

预览 Codex：

jbcontext setup-agent --agent codex --scope user --dump-auto --print-instructions

预览 Claude Code：

jbcontext setup-agent --agent claude --scope user --dump-auto --print-instructions

九、更新与重新配置

更新 JetBrains Context CLI：

jbcontext upgrade

升级后可以重新执行 setup-agent。安装器会刷新自己管理的配置块，并尽量保留用户原有配置：

jbcontext setup-agent --agent codex --auto --scope user --non-interactive<br>jbcontext setup-agent --agent claude --auto --scope user --non-interactive

十、移除配置

移除 Codex 集成：

jbcontext remove-agent --agent codex

移除 Claude Code 集成：

jbcontext remove-agent --agent claude

执行移除前可以先查看帮助，确认当前版本支持的参数：

jbcontext remove-agent --help

十一、常见问题

1. 安装后找不到命令

报错：

zsh: command not found: jbcontext

处理方式：

source ~/.zshrc
rehash
command -v jbcontext

仍未找到时检查 PATH：

echo "$PATH"
ls -la ~/.jbcontext/bin

2. 安装日志显示二进制为 0B

jbcontext_binary 可能是指向版本目录中真实二进制文件的符号链接，某些安装日志只显示链接本身的大小。使用以下命令确认实际文件：

ls -l ~/.jbcontext/bin/jbcontext_binary
wc -c ~/.jbcontext/bin/jbcontext_binary
file ~/.jbcontext/bin/jbcontext_binary

如果 file 能识别为当前平台的可执行文件，并且 jbcontext --help 能正常运行，则不需要重新安装。

3. 登录一直等待

• 检查浏览器是否打开了 JetBrains 授权页面。
• 检查终端是否正在等待用户协议确认。
• 暂时关闭可能拦截本地 OAuth 回调的代理或防火墙后重试。
• 执行 jbcontext login 重新发起登录。

4. AI 工具没有使用 Context

1. 完全退出并重新启动 Codex 或 Claude Code。
2. 确认当前目录是需要分析的项目目录。
3. 执行 jbcontext status 查看索引状态。
4. 在提示词中明确要求使用 context-search 或 context-explorer。
5. 再次执行对应的 setup-agent 命令刷新配置。

5. 搜索结果不准确

• 先执行 jbcontext index 更新索引。
• 用完整自然语言描述功能、行为和目标代码。
• 已知大致目录时使用 -p 缩小范围。
• 获得首个有效文件后，改用文件读取和精确关键词搜索检查邻近代码。

十二、团队快速安装清单

macOS/Zsh 用户可以依次执行：

curl -fsSL https://download.jetbrains.com/jetbrains-context/release/download-jbcontext.sh | bash
source ~/.zshrc<br>jbcontext login
jbcontext setup-agent --agent codex --auto --scope user
jbcontext setup-agent --agent claude --auto --scope user

只使用 Codex 或 Claude Code 时，只执行对应的 setup-agent 命令即可。配置完成后重启相应 AI 编程工具。