Codex Bridge

🚀 Codex Bridge

Codex Bridge 是一個輕量級的 MCP（模型上下文協議）服務器，它能讓 AI 編碼助手通過官方 CLI 與 OpenAI 的 Codex AI 進行交互。它可與 Claude Code、Cursor、VS Code 等支持 MCP 的客戶端配合使用，具備簡單、可靠和無縫集成的特點。

🚀 快速開始

前提條件

1. 安裝 Codex CLI：

   npm install -g @openai/codex-cli
   

2. 使用 Codex 進行身份驗證：

   codex
   

3. 驗證安裝：

   codex --version
   

安裝

🎯 推薦：通過 PyPI 安裝

# 從 PyPI 安裝
pip install codex-bridge

# 使用 uvx 將其添加到 Claude Code（推薦）
claude mcp add codex-bridge -s user -- uvx codex-bridge

替代方案：從源碼安裝

# 克隆倉庫
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge

# 構建並在本地安裝
uvx --from build pyproject-build
pip install dist/*.whl

# 添加到 Claude Code
claude mcp add codex-bridge -s user -- uvx codex-bridge

開發環境安裝

# 克隆並以開發模式安裝
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
pip install -e .

# 添加到 Claude Code（開發環境）
claude mcp add codex-bridge-dev -s user -- python -m src

✨ 主要特性

• 直接集成 Codex CLI：使用官方 Codex CLI，無需 API 成本。
• 簡單的 MCP 工具：具備兩個核心功能，可進行基本查詢和文件分析。
• 無狀態操作：無需會話、緩存或複雜的狀態管理。
• 可用於生產環境：具備強大的錯誤處理能力，可配置超時時間（默認 90 秒）。
• 依賴極少：僅需 mcp>=1.0.0 和 Codex CLI。
• 易於部署：支持 uvx 和傳統的 pip 安裝方式。
• 通用 MCP 兼容性：可與任何支持 MCP 的 AI 編碼助手配合使用。

🌐 多客戶端支持

Codex Bridge 可與任何支持 MCP 的 AI 編碼助手配合使用 —— 同一服務器可通過不同的配置方法支持多個客戶端。

支持的 MCP 客戶端

• Claude Code ✅（默認）
• Cursor ✅
• VS Code ✅
• Windsurf ✅
• Cline ✅
• Void ✅
• Cherry Studio ✅
• Augment ✅
• Roo Code ✅
• Zencoder ✅
• 任何支持 MCP 的客戶端 ✅

配置示例

# 推薦安裝方式
claude mcp add codex-bridge -s user -- uvx codex-bridge

# 開發環境安裝方式
claude mcp add codex-bridge-dev -s user -- python -m src

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "servers": {
    "codex-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-bridge"]
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "codex-bridge", 
      "command": "uvx", 
      "args": ["codex-bridge"],
      "env": {}
    }
  ]
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "command": "uvx",
  "args": ["codex-bridge"],
  "env": {}
}

{
  "command": "codex-bridge",
  "args": [],
  "env": {}
}

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/codex-bridge"
}

{
  "command": "npx",
  "args": ["codex-bridge"],
  "env": {}
}

通用用法

與任何客戶端完成配置後，可使用以下兩個相同的工具：

1. 提出常規問題：“此代碼庫中使用了哪些身份驗證模式？”
2. 分析特定文件：“審查這些身份驗證文件，查找安全問題”

服務器的實現方式是相同的 —— 僅客戶端配置有所不同！

⚙️ 配置

超時配置

默認情況下，Codex Bridge 對所有 CLI 操作使用 90 秒的超時時間。對於較長的查詢（大文件、複雜分析），可使用 CODEX_TIMEOUT 環境變量配置自定義超時時間。

Git 倉庫檢查

默認情況下，Codex CLI 要求在 Git 倉庫或受信任的目錄中使用。如果需要在非 Git 倉庫的目錄中使用 Codex Bridge，可設置 CODEX_SKIP_GIT_CHECK 環境變量。

⚠️ 安全警告：僅在你能控制目錄結構的受信任環境中啟用此標誌。

示例配置：

# 添加自定義超時時間（120 秒）
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge

# 禁用 Git 倉庫檢查（用於非 Git 目錄）
claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

# 同時添加兩種配置
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {
        "CODEX_TIMEOUT": "120",
        "CODEX_SKIP_GIT_CHECK": "true"
      }
    }
  }
}

配置選項：

CODEX_TIMEOUT：

• 默認值：90 秒（未配置時）
• 範圍：任何正整數（秒）
• 推薦值：大多數查詢為 60 - 120 秒，大文件分析為 120 - 300 秒
• 無效值：回退到 90 秒並給出警告

CODEX_SKIP_GIT_CHECK：

• 默認值：false（啟用 Git 倉庫檢查）
• 有效值："true"、"1"、"yes"（不區分大小寫），用於禁用檢查
• 使用場景：在非 Git 倉庫的目錄中工作
• 安全性：僅在你能控制的受信任目錄中使用

🛠️ 可用工具

consult_codex

這是一個直接的 CLI 橋接工具，默認以結構化的 JSON 格式輸出簡單查詢結果。

參數：

• query（字符串）：要發送給 Codex 的問題或提示
• directory（字符串）：查詢的工作目錄（默認：當前目錄）
• format（字符串）：輸出格式 —— "text"、"json" 或 "code"（默認："json"）
• timeout（整數，可選）：超時時間（秒）（推薦：60 - 120，默認：90）

示例：

consult_codex(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    format="json",  # 默認格式
    timeout=90      # 默認超時時間
)

consult_codex_with_stdin

這是一個支持通過標準輸入內容進行管道式執行的 CLI 橋接工具。

參數：

• stdin_content（字符串）：作為標準輸入管道的內容（文件內容、差異、日誌）
• prompt（字符串）：處理標準輸入內容的提示信息
• directory（字符串）：查詢的工作目錄
• format（字符串）：輸出格式 —— "text"、"json" 或 "code"（默認："json"）
• timeout（整數，可選）：超時時間（秒）（推薦：60 - 120，默認：90）

consult_codex_batch

用於批量處理多個查詢，非常適合 CI/CD 自動化。

參數：

• queries（列表）：包含查詢字典的列表，每個字典包含 'query' 和可選的 'timeout'
• directory（字符串）：所有查詢的工作目錄
• format（字符串）：輸出格式 —— 目前批量處理僅支持 "json"

示例：

consult_codex_with_stdin(
    stdin_content=open("src/auth.py").read(),
    prompt="Analyze this auth file and suggest improvements",
    directory="/path/to/project",
    format="json",  # 默認格式
    timeout=120     # 複雜分析的自定義超時時間
)

💻 使用示例

基礎代碼分析

# 簡單的研究查詢
consult_codex(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

詳細文件審查

# 分析特定文件
with open("/Users/dev/my-project/src/auth.py") as f:
    auth_content = f.read()
    
consult_codex_with_stdin(
    stdin_content=auth_content,
    prompt="Review this file and suggest security improvements",
    directory="/Users/dev/my-project",
    format="json",  # 結構化輸出
    timeout=120     # 為詳細分析留出更多時間
)

批量處理

# 一次性處理多個查詢
consult_codex_batch(
    queries=[
        {"query": "Analyze authentication patterns", "timeout": 60},
        {"query": "Review database implementations", "timeout": 90},
        {"query": "Check security vulnerabilities", "timeout": 120}
    ],
    directory="/Users/dev/my-project",
    format="json"  # 批量處理始終使用 JSON 格式
)

🏗️ 架構

核心設計

• 以 CLI 為先：直接通過子進程調用 codex 命令
• 無狀態：每個工具調用都是獨立的，無會話狀態
• 可配置超時：默認執行時間為 90 秒（可配置）
• 結構化輸出：默認使用 JSON 格式，便於更好地集成
• 簡單的錯誤處理：採用快速失敗策略，提供清晰的錯誤信息

項目結構

codex-bridge/
├── src/
│   ├── __init__.py              # 入口點
│   ├── __main__.py              # 模塊執行入口點
│   └── mcp_server.py            # 主要的 MCP 服務器實現
├── .github/                     # GitHub 模板和工作流
├── pyproject.toml              # Python 包配置
├── README.md                   # 本文件
├── CONTRIBUTING.md             # 貢獻指南
├── CODE_OF_CONDUCT.md          # 社區標準
├── SECURITY.md                 # 安全策略
├── CHANGELOG.md               # 版本歷史
└── LICENSE                    # MIT 許可證

🔧 開發

本地測試

# 以開發模式安裝
pip install -e .

# 直接運行
python -m src

# 測試 CLI 可用性
codex --version

與 Claude Code 集成

通過 MCP 協議正確配置後，服務器會自動與 Claude Code 集成。

🔍 故障排除

CLI 不可用

# 安裝 Codex CLI
npm install -g @openai/codex-cli

# 進行身份驗證
codex auth login

# 測試
codex --version

連接問題

• 驗證 Codex CLI 是否已正確進行身份驗證
• 檢查網絡連接
• 確保 Claude Code 的 MCP 配置正確
• 檢查 codex 命令是否在你的 PATH 中

常見錯誤信息

• "CLI not available"：Codex CLI 未安裝或不在 PATH 中
• "Authentication required"：運行 codex auth login
• "Timeout after X seconds"：查詢耗時過長，嘗試增加超時時間或將其拆分為更小的部分

🤝 貢獻

我們歡迎社區的貢獻！請閱讀我們的 貢獻指南，瞭解如何開始貢獻。

快速貢獻指南

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 如有必要，添加測試
5. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證 —— 詳情請參閱 LICENSE 文件。

🔄 版本歷史

詳細的版本歷史請參閱 CHANGELOG.md。

🆘 支持

• 問題反饋：通過 GitHub 問題 報告錯誤或請求功能
• 討論：加入社區討論
• 文檔：可在 docs/ 目錄中創建額外的文檔

重點：通過官方 CLI，在 Claude Code 和 Codex AI 之間建立一個簡單、可靠的橋樑。