关键词

AI编程助手代码上下文服务LLM工具集成Claude Codex会话管理

项目简介

Codex AI助手服务是一个强大的中间层，允许大型语言模型 (LLM) 客户端（如Claude Code）通过标准化的Model Context Protocol (MCP) 与OpenAI Codex CLI进行交互。它提供了会话管理、工作区隔离、流式响应、工具调用等功能，使得LLM能够更有效地利用Codex的能力来辅助编程、代码分析和问题解决。

主要功能点

  • 会话管理: 保持AI交互的连贯性，支持创建、继续、取消和重启会话，每个会话都有独立的上下文。
  • 工作区隔离: 根据项目仓库路径自动隔离不同的会话，确保上下文信息与当前开发环境相关。
  • 工具调用: 提供多种Codex专用工具，如向Codex提问 ('ask')、开始/继续对话 ('chat_start', 'chat_msg')、检查会话状态 ('status')、管理代码计划 ('plan') 和应用代码修改 ('patch') 等，让LLM能执行具体操作。
  • 流式响应: 支持实时获取AI的思考过程和进度更新，提升用户体验。
  • 资源处理: 能够处理LLM客户端附加的文件和内容（例如代码片段或文档），将其作为Codex的输入上下文。
  • 动态能力检测: 自动识别并声明所集成的Codex CLI支持的功能，如JSON模式、可用的模型以及文件操作能力。
  • 错误处理和日志: 提供结构化的错误分类和详细日志记录，便于故障诊断和问题解决。
  • 响应分页: 自动将Codex生成的过长AI响应拆分为多个页面，便于客户端分批显示和处理。

安装步骤

  1. 安装 Node.js: 确保您的系统已安装 Node.js 18.0.0 或更高版本。您可以从 Node.js 官网 下载安装包。
  2. 安装 pnpm: 全局安装 pnpm 包管理器。在命令行中运行： 
    npm install -g pnpm
  3. 安装 Codex CLI: 全局安装 OpenAI Codex 命令行工具。在命令行中运行： 
    npm install -g @openai/codex
# 或者使用 Homebrew (macOS/Linux):
# brew install codex
  4. 下载并构建项目:
    • 首先，使用 Git 克隆本仓库到您的本地机器： 
      git clone https://github.com/andreahaku/codex_mcp.git
cd codex_mcp
    • 然后，运行自动化安装脚本。此脚本将检查依赖、安装Codex CLI（如果未安装）、构建项目并进行一些配置： 
      ./install.sh
    • 如果您更喜欢手动操作，可以跳过 './install.sh' 并执行以下命令： 
      pnpm install  # 安装项目依赖
pnpm run build # 构建项目，生成可执行文件到 'dist' 目录

服务器配置

MCP服务器是为MCP客户端提供服务的，其自身不需要复杂的JSON配置，而是由MCP客户端来配置如何启动和连接此服务器。以下是针对Claude Desktop这类MCP客户端的典型配置示例。请根据您的实际安装路径调整 'command' 的 'args' 部分。

{
  "mcpServers": {
    "codex-ai-assistant": {
      "command": "node",
      "args": [
        "/path/to/codex_mcp/dist/index.js"
        // 请将此路径替换为您的 Codex AI 助手服务仓库中 'dist/index.js' 文件的完整路径
        // 例如："/Users/YourUser/codex_mcp/dist/index.js"
      ],
      "env": {
        // 可选的环境变量配置，用于调整服务器行为。
        // 这些值将作为进程的环境变量传递给 MCP 服务器。
        "MAX_CONVERSATIONS": "50",           // 最大并发会话数 (默认: 50)
        "MAX_CONVERSATION_HISTORY": "100",   // 每个会话最大消息数 (默认: 100)
        "MAX_CONVERSATION_CONTEXT": "10",    // 发送给Codex的最大上下文消息数 (默认: 10)
        "LOG_LEVEL": "info",                 // 日志级别 (可选: debug, info, warn, error) (默认: info)
        "MAX_SESSIONS": "10",                // 最大并发Codex CLI进程数 (默认: 10)
        "SESSION_IDLE_TIMEOUT": "1800000"    // 会话空闲自动清理超时时间 (毫秒, 默认: 30分钟)
      }
    }
  }
}

说明：将上述JSON片段添加到您的MCP客户端配置文件（例如 'claude_desktop_config.json'）的 'mcpServers' 部分。配置完成后，请根据客户端的指示重启您的MCP客户端应用，以便加载新的服务器配置。

基本使用方法

一旦Codex AI助手服务配置并启动，您的MCP客户端（如Claude Code）将能够自动发现并使用其提供的工具。您可以通过客户端的用户界面或直接的命令来调用这些工具：

  • 提问 Codex (基本用法): 在您的MCP客户端中，您可以像与AI聊天一样，直接向Codex提问： '@codex-ai-assistant ask What is the best way to implement error handling in Node.js?' （您的客户端可能还会通过图形用户界面提供“询问”按钮，并自动调用此工具）

  • 带文件上下文提问 (工作区感知): 您可以附加文件或代码片段，让Codex根据文件内容提供帮助。客户端会自动将文件内容作为“资源”传递给服务器： '@codex-ai-assistant ask Based on this code: [attach my_file.js], how can I optimize the performance?' （Codex AI助手会根据客户端提供的当前工作区路径来管理会话，确保上下文的准确性）

  • 持续会话 (保持上下文): 通过指定 'sid' (Session ID)，您可以让AI在同一个会话中保持上下文，进行多轮交流： '@codex-ai-assistant ask {"sid": "my-project-feature", "prompt": "Help me implement user authentication"}' '@codex-ai-assistant ask {"sid": "my-project-feature", "prompt": "Now add password reset functionality to it."}' （后续的请求将利用 'my-project-feature' 会话的聊天历史来提供更连贯的回答）

  • 检查会话状态: 您可以随时检查当前活跃会话的状态和详细信息： '@codex-ai-assistant status' (查看所有活跃会话) '@codex-ai-assistant status {"sid": "my-project-feature"}' (查看特定会话)

  • 重启会话: 如果某个会话遇到问题或需要重置，您可以强制重启它： '@codex-ai-assistant restart {"sid": "my-project-feature"}'

信息

分类

开发者工具

访问项目