内容
# Akeyless 可信访问层，用于 OpenAI Codex
一个 MCP 服务器，使 [Akeyless](https://www.akeyless.io) 成为 [OpenAI Codex](https://developers.openai.com/codex/) 的**可信访问层**。
Codex 协调。Akeyless 持有秘密。**秘密值从不进入模型上下文。**
## 为什么存在
像 Codex 这样的编码代理需要凭证来运行应用程序、调用 API 和部署代码。今天，这些凭证通常存在于 `.env` 文件、shell 历史记录或存储库中硬编码 - 容易外泄，难以审计。
此集成提供给 Codex 安全、可审计的访问权限，而无需将秘密放入提示或代码中：
| 功能 | Codex 看到的内容 | 实际发生的情况 |
|---|---|---|
| 列出环境 | 变量**名称** + Akeyless 路径 | 不会获取值 |
| 运行环境 | 命令 stdout/stderr（已编辑） | 秘密注入到子进程环境中 |
| ARA 查询/执行 | 查询或操作结果仅 | 服务器端通过网关使用凭证 |
| 存储秘密 | 路径 + 环境变量名称 | 值仅写入 Akeyless |
| 扫描秘密 | 文件 + 行 + 编辑后的代码段 | 从不返回完整值 |
## 架构
```mermaid
sequenceDiagram
participant Dev as 开发者
participant Codex as OpenAI Codex
participant MCP as akeyless-codex-mcp
participant AKL as Akeyless Vault
participant GW as Akeyless Gateway
participant App as 子进程
Dev->>Codex: "用正确的环境运行我的应用程序"
Codex->>MCP: list_environment_variables
MCP->>AKL: list-items (仅元数据)
AKL-->>MCP: 名称 + 路径
MCP-->>Codex: DATABASE_URL, API_KEY (无值)
Codex->>MCP: run_with_environment(npm, start)
MCP->>AKL: get-secret-value (服务器端)
AKL-->>MCP: 值（从不发送到 Codex）
MCP->>App: 生成并注入环境
App-->>MCP: stdout/stderr
MCP-->>Codex: 编辑后的输出
Dev->>Codex: "查询生产数据库"
Codex->>MCP: list-secrets
MCP->>AKL: list-items (仅 ARA，元数据)
Codex->>MCP: query-db
MCP->>GW: /config/target_query
GW-->>MCP: 查询结果（无凭证）
MCP-->>Codex: JSON 结果
```
## 快速入门
### 1. 安装
```bash
npm install -g @akeyless-community/codex-mcp
```
或在不安装的情况下运行：
```bash
npx -y @akeyless-community/codex-mcp
```
### 2. 配置 Akeyless 身份验证
为 MCP 服务器进程设置凭证（不在 Codex 提示中）：
```bash
export AKEYLESS_ACCESS_ID="p-xxxxx"
export AKEYLESS_ACCESS_KEY="your-access-key"
export AKEYLESS_ENVIRONMENT_PREFIX="/codex/my-app/local"
export AKEYLESS_GATEWAY_URL="https://api.akeyless.io"
# ARA 工具所需（query-db, service-execute）：
export AKEYLESS_ARA_GATEWAY_URL="https://your-gateway.example.com:8000"
export AKEYLESS_AGENT_ID="codex-agent"
```
参见 [`.env.example`](.env.example) 获取所有身份验证选项。
## 作为 Codex 插件（市场）安装
通过 Codex 插件目录浏览和安装，使用此存储库中的插件包装器：
```bash
codex plugin marketplace add akeyless-community/codex-akeyless-mcp
```
然后在 Codex 中：`/plugins` → **Akeyless 社区** → 安装 **Akeyless Trusted Access**。
或通过社区市场 CLI：
```bash
npx codex-marketplace add akeyless-community/codex-akeyless-mcp --plugin --project
```
安装后，在 Codex MCP 设置中配置 Akeyless 凭证（参见 [市场指南](docs/MARKETPLACE.md)）。
### 3. 连接 Codex（直接 MCP）
添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.akeyless]
command = "npx"
args = ["-y", "@akeyless-community/codex-mcp"]
enabled = true
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 120
[mcp_servers.akeyless.env]
AKEYLESS_ACCESS_ID = "p-xxxxx"
AKEYLESS_ACCESS_KEY = "your-access-key"
AKEYLESS_ENVIRONMENT_PREFIX = "/codex/my-app/local"
AKEYLESS_GATEWAY_URL = "https://api.akeyless.io"
AKEYLESS_ARA_GATEWAY_URL = "https://your-gateway.example.com:8000"
AKEYLESS_AGENT_ID = "codex-agent"
[mcp_servers.akeyless.tools.store_secret]
approval_mode = "approve"
[mcp_servers.akeyless.tools.run_with_environment]
approval_mode = "prompt"
[mcp_servers.akeyless.tools.query-db]
approval_mode = "prompt"
[mcp_servers.akeyless.tools.service-execute]
approval_mode = "prompt"
```
或使用 CLI：
```bash
codex mcp add akeyless \
--env AKEYLESS_ACCESS_ID=p-xxxxx \
--env AKEYLESS_ACCESS_KEY=your-key \
--env AKEYLESS_ENVIRONMENT_PREFIX=/codex/my-app/local \
--env AKEYLESS_ARA_GATEWAY_URL=https://your-gateway.example.com:8000 \
-- npx -y @akeyless-community/codex-mcp
```
对于项目范围的配置，将 [`examples/.codex/config.toml`](examples/.codex/config.toml) 复制到您的存储库中（需要受信任的项目）。
### 4. 在 Akeyless 中组织秘密
应用程序启动的静态环境变量：
```
/codex/my-app/local/DATABASE_URL
/codex/my-app/local/STRIPE_SECRET_KEY
/codex/my-app/local/OPENAI_API_KEY
```
用于运行时权限（ARA）的动态秘密：
```
/prod/dynamic-secrets/postgres-readonly
/prod/dynamic-secrets/aws-devops
```
### 5. 询问 Codex
> "列出我的环境变量并使用 Akeyless 中的秘密运行 `npm test`。"
> "列出 ARA 秘密并在 postgres 动态秘密上运行 `SELECT count(*) FROM users` 查询。"
> "扫描此存储库中硬编码的秘密并将它们迁移到 Akeyless。"
## MCP 工具
### 环境工具
| 工具 | 用途 |
|---|---|
| `list_environment_variables` | 列出 Akeyless 前缀下的环境变量名称 |
| `describe_environment` | 活动环境的摘要 |
| `create_environment` | 启动新的 `/codex/{project}/{stage}` 前缀 |
| `store_secret` | 将秘密迁移到 Akeyless（建议批准） |
| `run_with_environment` | 使用 JIT 秘密注入运行命令 |
| `write_env_reference` | 生成带有 `akeyless://` 引用的 `.env.example` |
| `scan_for_exposed_secrets` | 在存储库中查找硬编码凭证 |
### 运行时权限（ARA）工具
| 工具 | 用途 |
|---|---|
| `list-secrets` | 列出可用于无秘密访问的动态/轮换秘密 |
| `query-db` | 运行数据库查询（MySQL，PostgreSQL，MSSQL，Oracle，Snowflake 等） |
| `service-execute` | 运行 AWS，GCP，Azure，Kubernetes 或 GitHub 操作 |
ARA 执行工具需要启用了运行时权限的 [Akeyless 网关](https://docs.akeyless.io/docs/about-akeyless-gateway)。将 `AKEYLESS_ARA_GATEWAY_URL` 设置为您的网关配置端口（例如 `http://127.0.0.1:8000`）。
## 安全模型
**设计无秘密：**
- 读取工具仅返回元数据
- `run_with_environment` 从 stdout/stderr 中编辑注入的值
- ARA 工具在服务器端使用凭证 - 仅返回操作结果
- `scan_for_exposed_secrets` 仅返回编辑后的代码段
**需要 Codex 批准：**
- `store_secret` - 迁移期间值会经过 MCP
- `run_with_environment` - 使用真实凭证生成命令
- `query-db` / `service-execute` - 对实时基础设施执行
**建议：**
- 在 Codex 配置中设置 `default_tools_approval_mode = "prompt"`
- 在 Akeyless 中将 RBAC 范围限定为 `/codex/*` 用于环境工具和 ARA 路径用于执行工具
- 优先使用动态秘密和 ARA 进行数据库和云 API 操作
- 永远不要提交 `.env` 文件 - 而是使用 `write_env_reference`
## 开发
```bash
cd codex-akeyless-integration
npm install
npm run build
npm test
```
本地运行：
```bash
AKEYLESS_ACCESS_ID=... AKEYLESS_ACCESS_KEY=... npm start
```
## 发布
参见 [docs/PUBLISHING.md](docs/PUBLISHING.md) 获取 npm 发布说明。
## 市场
参见 [docs/MARKETPLACE.md](docs/MARKETPLACE.md) 获取 Codex 插件目录提交信息。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。所有更改都需要 `@akeyless-community/cs-admin` 的批准。
## 相关项目
- [`@akeyless-community/vercel-runtime`](../vercel-akeyless-runtime) - Vercel 上的运行时秘密获取
- [`akeyless mcp-runtime-authority`](../akeyless-main-repo/go/src/client/commands/mcp_runtime_authority.go) - CLI ARA MCP 服务器
- [`bedrock-agentcore-akeyless-runtime`](../bedrock-agentcore-akeyless-runtime) - AWS AgentCore 集成
## 许可证
Apache-2.0 - 参见 [LICENSE](LICENSE)。
