Codex Octopus

Codex Octopus

一个大脑，众多触手。

一个封装了 OpenAI Codex SDK 的 MCP 服务，让你可以从任意 MCP 客户端运行多个专用的 Codex Agent——每个 Agent 都有自己的模型、沙盒、推理力度和个性。

为什么选择它

Codex 功能强大，但单个实例做所有事情的方式都一样。有时，你可能需要一个在只读沙盒中工作的严格代码审查员，一个拥有工作区写入权限的测试编写者，一个采用最低推理力度的低成本快速助手，或者一个采用 xhigh 的深度思考者。

Codex Octopus 让你可以按需启动任意数量的这类实例。使用相同的二进制文件，配置各不相同。每个实例都会在 MCP 客户端中显示为一个独立工具。

前提条件

• Node.js >= 18
• Codex CLI — Codex SDK 会在底层启动 Codex CLI，因此你需要先安装它（@openai/codex）
• OpenAI API 密钥（CODEX_API_KEY 环境变量），或从父进程继承

安装

npm install codex-octopus

或者直接在 .mcp.json 中使用 npx（参见下文的快速入门）。

快速入门

将以下内容添加到 .mcp.json：

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_SANDBOX_MODE": "workspace-write",
        "CODEX_APPROVAL_POLICY": "never"
      }
    }
  }
}

这样你就会获得两个工具：codex 和 codex_reply。就这么简单——现在你可以将 Codex 用作工具了。

多个 Agent

真正强大的地方在于使用不同配置运行多个实例：

{
  "mcpServers": {
    "code-reviewer": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_TOOL_NAME": "code_reviewer",
        "CODEX_SERVER_NAME": "code-reviewer",
        "CODEX_DESCRIPTION": "Strict code reviewer. Read-only sandbox.",
        "CODEX_MODEL": "o3",
        "CODEX_SANDBOX_MODE": "read-only",
        "CODEX_APPEND_INSTRUCTIONS": "You are a strict code reviewer. Report real bugs, not style preferences.",
        "CODEX_EFFORT": "high"
      }
    },
    "test-writer": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_TOOL_NAME": "test_writer",
        "CODEX_SERVER_NAME": "test-writer",
        "CODEX_DESCRIPTION": "Writes thorough tests with edge case coverage.",
        "CODEX_MODEL": "gpt-5-codex",
        "CODEX_SANDBOX_MODE": "workspace-write",
        "CODEX_APPEND_INSTRUCTIONS": "Write tests first. Cover edge cases. TDD."
      }
    },
    "quick-qa": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_TOOL_NAME": "quick_qa",
        "CODEX_SERVER_NAME": "quick-qa",
        "CODEX_DESCRIPTION": "Fast answers to quick coding questions.",
        "CODEX_EFFORT": "minimal"
      }
    }
  }
}

现在，你的 MCP 客户端会看到三个不同的工具——code_reviewer、test_writer、quick_qa，每个工具都针对特定用途打造。

Agent 工厂

不想手动编写配置？添加一个工厂实例：

{
  "mcpServers": {
    "agent-factory": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_FACTORY_ONLY": "true",
        "CODEX_SERVER_NAME": "agent-factory"
      }
    }
  }
}

这会提供一个名为 create_codex_mcp 的工具——一个交互式向导。告诉它你想要什么（“一个在只读沙盒中工作的严格代码审查员”），它就会为你生成 .mcp.json 条目。

工具

每个非工厂实例都会提供：

工具	用途
<name>	向 Agent 发送任务并获取回复和 thread_id
<name>_reply	根据 thread_id 继续之前的对话

每次调用的参数（覆盖服务默认值）：

参数	说明
prompt	任务或问题（必填）
cwd	覆盖工作目录
model	覆盖模型
additionalDirs	Agent 可以访问的其他目录
effort	推理力度（从 minimal 到 xhigh）
sandboxMode	覆盖沙盒设置（只能收紧，不能放宽）
approvalPolicy	覆盖审批策略（只能收紧，不能放宽）
networkAccess	启用沙盒的网络访问
webSearchMode	网络搜索：disabled、cached、live
instructions	附加指令（置于提示词之前）

配置

所有配置都通过 .mcp.json 中的环境变量完成。所有环境变量均为可选。

身份

环境变量	说明	默认值
CODEX_TOOL_NAME	工具名称前缀（<name> 和 <name>_reply）	codex
CODEX_DESCRIPTION	向宿主 AI 显示的工具描述	generic
CODEX_SERVER_NAME	协议握手中的 MCP 服务名称	codex-octopus
CODEX_FACTORY_ONLY	仅提供工厂向导工具	false

Agent

Env Var	Description	Default
CODEX_MODEL	模型（gpt-5-codex、o3、codex-1 等）	SDK 默认值
CODEX_CWD	工作目录	process.cwd()
CODEX_SANDBOX_MODE	read-only、workspace-write、danger-full-access	read-only
CODEX_APPROVAL_POLICY	never、on-failure、on-request、untrusted	on-failure
CODEX_EFFORT	minimal、low、medium、high、xhigh	SDK 默认值
CODEX_ADDITIONAL_DIRS	额外目录（以逗号分隔）	无
CODEX_NETWORK_ACCESS	允许沙盒访问网络	false
CODEX_WEB_SEARCH	disabled、cached、live	disabled

指令

Env Var	Description
CODEX_INSTRUCTIONS	替换默认指令
CODEX_APPEND_INSTRUCTIONS	附加到默认指令之后（通常推荐使用此项）

高级选项

Env Var	Description
CODEX_PERSIST_SESSION	true/false — 启用会话恢复（默认：true）

身份验证

Env Var	Description	Default
CODEX_API_KEY	此 Agent 使用的 OpenAI API 密钥	从父级继承

安全性

• 沙盒默认设为 read-only — 除非明确设置为 workspace-write 或 danger-full-access，否则 Agent 无法写入文件。
• 覆盖 cwd 不会丢失 Agent 知识 — 当主机覆盖 cwd 时，Agent 配置的基目录会自动添加到 additionalDirectories。
• 安全覆盖只会收紧限制，绝不会放宽 — 每次调用的 sandboxMode 和 approvalPolicy 只能收紧限制（例如，从 workspace-write 改为 read-only），绝不会放宽。
• _reply 工具遵循持久化设置 — 当 CODEX_PERSIST_SESSION=false 时不会注册。
• API 密钥会被隐藏 — 工厂向导绝不会在生成的配置中暴露 CODEX_API_KEY。

架构

┌─────────────────────────────────┐
│  MCP Client                     │
│  (Claude Desktop, Cursor, etc.) │
│                                 │
│  Sees: code_reviewer,           │
│        test_writer, quick_qa    │
└──────────┬──────────────────────┘
           │ JSON-RPC / stdio
┌──────────▼──────────────────────┐
│  Codex Octopus (per instance)   │
│                                 │
│  Env: CODEX_MODEL=o3            │
│       CODEX_SANDBOX_MODE=...    │
│       CODEX_APPEND_INSTRUCTIONS │
│                                 │
│  Calls: Codex SDK thread.run()  │
└──────────┬──────────────────────┘
           │ in-process
┌──────────▼──────────────────────┐
│  Codex SDK → Codex CLI          │
│  Runs autonomously: reads files,│
│  writes code, runs commands     │
│  Returns result + thread_id     │
└─────────────────────────────────┘

已知限制

• minimal 推理强度 + web_search：OpenAI 不允许在 minimal 推理强度下使用 web_search 工具。如果需要网页搜索，请使用 low 或更高强度。

开发

pnpm install
pnpm build       # compile TypeScript
pnpm test        # run tests (vitest)
pnpm test:coverage  # coverage report

许可证

ISC - Xiaolai Li