### Start services with Docker Compose

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

Starts the application stack using the Compose file at deploy/compose.yaml. The config --quiet step validates the configuration without exposing secrets. The up command waits for healthy containers before returning.

```bash
docker compose -f deploy/compose.yaml config --quiet
docker compose -f deploy/compose.yaml pull
docker compose -f deploy/compose.yaml up -d --no-build --wait
docker compose -f deploy/compose.yaml ps
```

--------------------------------

### POST /api/admin/plugins/artifacts/install

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Downloads and validates a plugin from a URL or a fixed GitHub Release, confirms trust, and completes installation. Requires `pluginId`, `version`, and `location.sha256` for remote installs.

```APIDOC
## POST /api/admin/plugins/artifacts/install

### Description
Downloads and validates a plugin from a URL or a fixed GitHub Release, confirms trust, and completes installation. Requires `pluginId`, `version`, and `location.sha256` for remote installs.

### Method
POST

### Endpoint
/api/admin/plugins/artifacts/install

### Parameters
#### Request Body
- **pluginId** (string) - Required - The plugin ID (publisher + "." + name).
- **version** (string) - Required - The plugin version.
- **credentialIds** (array of strings) - Optional - List of credential IDs for the source.
- **outboundProxyId** (string|null) - Optional - The outbound proxy ID.
- **location** (object) - Required - The source location.
  - **kind** (string) - Required - Either `url` or `github`.
  - **url** (string) - Required if kind is `url` - The download URL.
  - **sha256** (string) - Required - The 64-character lowercase hexadecimal SHA-256 digest of the package.
  - **repository** (string) - Required if kind is `github` - The GitHub repository in `owner/repo` format.
  - **tag** (string) - Required if kind is `github` - The release tag.
  - **asset** (string) - Required if kind is `github` - The asset name.
  - **allow_prerelease** (boolean) - Optional if kind is `github` - Whether to allow prerelease versions.

### Response
#### Success Response (200)
- **artifact** (object) - The installed artifact, containing `metadata`, `source`, `installedAt`, and `acceptedAt`.
- **configRevision** (integer) - The configuration revision after installation.
- **defaultInstanceId** (string|null) - The default instance ID if created, otherwise null.
- **configurationRequired** (boolean) - Whether the default instance requires configuration.

#### Response Example
```json
{
  "artifact": {
    "metadata": {},
    "source": { "kind": "url" },
    "installedAt": "2026-09-22T00:00:00Z",
    "acceptedAt": "2026-09-22T00:00:01Z"
  },
  "configRevision": 2,
  "defaultInstanceId": "<instance UUID or null>",
  "configurationRequired": false
}
```
```

--------------------------------

### GET /api/admin/plugins/instances/rollback-plan

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Lists current version, instance revision, and old version candidates in descending semantic version order. Does not start the plugin.

```APIDOC
## GET /api/admin/plugins/instances/rollback-plan

### Description
Lists current version, instance revision, and old version candidates in descending semantic version order. Does not start the plugin.

### Method
GET

### Endpoint
/api/admin/plugins/instances/rollback-plan?id=<实例 ID>

### Parameters
#### Query Parameters
- **id** (string) - Required - Instance ID

### Response
#### Success Response (200)
- **currentVersion** (string) - Current version
- **instanceRevision** (integer) - Instance revision
- **candidates** (array) - List of old version candidates (installed, accepted, and with configuration snapshot)

#### Response Example
```json
{
  "currentVersion": "string",
  "instanceRevision": 1,
  "candidates": []
}
```
```

--------------------------------

### GET /plugins/callbacks/{target}/{path}

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

公开回调入口，无须登录，但必须携带有效且未消费的 state 票据。

```APIDOC
## [GET] /plugins/callbacks/{target}/{path}

### Description
公开回调入口，无须登录，但必须携带有效且未消费的 state 票据。

### Method
GET

### Endpoint
/plugins/callbacks/{target}/{path}

### Parameters
#### Path Parameters
- **target** (string) - Required - 格式为 {instanceId}/{artifactSha256}/{revision}
- **path** (string) - Required - 包内已声明的相对路径

#### Query Parameters
- **state** (string) - Required - 一次性不透明票据，必须恰好一个

### Response
#### Success Response (200)
- 插件原始响应，不套管理信封
- 响应头包含 `X-CPR-Plugin-Response: 1`

#### Response Example
（插件原始响应）
```

--------------------------------

### GET /api/admin/plugins/instances

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Lists instance configurations, feature bindings, configuration completeness, and publication status. Does not return secret values.

```APIDOC
## GET /api/admin/plugins/instances

### Description
Lists instance configurations, feature bindings, configuration completeness, and publication status. Does not return secret values.

### Method
GET

### Endpoint
/api/admin/plugins/instances

### Response
#### Success Response (200)
- **id** (string) - Instance ID
- **name** (string) - Instance name
- **artifactSha256** (string) - Artifact SHA256
- **enabled** (boolean) - Whether the instance is enabled
- **configurationRequired** (boolean) - Whether required configuration is missing
- **configuration** (object) - Configuration object
- **secretFields** (array) - List of secret field names
- **bindings** (object) - Feature bindings
- **revision** (integer) - Configuration revision
- **running** (boolean) - Whether the instance is running
- **publishedRevision** (integer) - Published revision
- **runtime** (object) - Runtime status, may include failure
- **compatibilityWarning** (string|null) - Compatibility warning if any
- **loadError** (string|null) - Load error if any
- **apiDeprecations** (array) - List of API deprecation warnings

#### Response Example
```json
{
  "id": "string",
  "name": "string",
  "artifactSha256": "string",
  "enabled": true,
  "configurationRequired": false,
  "configuration": {},
  "secretFields": [],
  "bindings": {},
  "revision": 1,
  "running": true,
  "publishedRevision": 1,
  "runtime": {},
  "compatibilityWarning": null,
  "loadError": null,
  "apiDeprecations": []
}
```
```

--------------------------------

### GET /api/admin/plugins/instances/version-plan

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Generates a read-only version setting draft. Does not start the plugin and does not return secret values.

```APIDOC
## GET /api/admin/plugins/instances/version-plan

### Description
Generates a read-only version setting draft. Does not start the plugin and does not return secret values.

### Method
GET

### Endpoint
/api/admin/plugins/instances/version-plan?id=<实例 ID>&artifactSha256=<目标摘要>

### Parameters
#### Query Parameters
- **id** (string) - Required - Instance ID
- **artifactSha256** (string) - Required - Target artifact SHA256

### Response
#### Success Response (200)
- **instanceRevision** (integer) - Instance revision
- **artifactSha256** (string) - Target artifact SHA256
- **configuration** (object) - Configuration draft
- **secretFields** (array) - List of secret field names
- **bindings** (object) - Feature bindings
- **restored** (boolean) - Whether the target version's configuration snapshot was used

#### Response Example
```json
{
  "instanceRevision": 1,
  "artifactSha256": "string",
  "configuration": {},
  "secretFields": [],
  "bindings": {},
  "restored": true
}
```
```

--------------------------------

### GET /api/admin/plugins/update-sources

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Queries the allowed sources and update check policy for future plugin installations. Requires admin identity.

```APIDOC
## GET /api/admin/plugins/update-sources

### Description
Queries the allowed sources and update check policy for future plugin installations. Requires admin identity.

### Method
GET

### Endpoint
/api/admin/plugins/update-sources

### Response
#### Success Response (200)
- **allowedSources** (array) - List of allowed source types (e.g., `url`, `github`).
- **updatePolicy** (string) - The update check policy (e.g., `stable`, `all`).

#### Response Example
```json
{
  "allowedSources": ["url", "github"],
  "updatePolicy": "stable"
}
```
```

--------------------------------

### Plugin command-line help and invocation

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

Shows how to use the plugin CLI. Replace the instance ID, command, parameter name, and value with actual plugin content. The plugin command does not start the gateway or listen on HTTP.

```bash
codex-proxy-rs plugin --help
codex-proxy-rs plugin '实例ID' '命令' --help
codex-proxy-rs plugin '实例ID' '命令' --参数 '值'
```

--------------------------------

### 启动数据库、Redis 和后端网关

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/development.md

使用 Compose 启动 PostgreSQL 和 Redis，然后运行后端网关。后端从当前目录向上查找 deploy/config.yaml，本机运行时数据库与 Redis 地址应指向可访问的本机端口。

```bash
docker compose -f deploy/compose.yaml up -d postgres redis
cargo +1.99.1 run --manifest-path backend/Cargo.toml -p codex-proxy-rs --locked
```

--------------------------------

### GET /api/admin/plugins/artifacts

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Lists plugin artifacts with their metadata, source, installation time, and acceptance time. Requires admin identity.

```APIDOC
## GET /api/admin/plugins/artifacts

### Description
Lists plugin artifacts with their metadata, source, installation time, and acceptance time. Requires admin identity.

### Method
GET

### Endpoint
/api/admin/plugins/artifacts

### Response
#### Success Response (200)
- **artifacts** (array) - List of artifact objects, each containing `metadata`, `source`, `installedAt`, and `acceptedAt` (nullable).

#### Response Example
```json
{
  "artifacts": [
    {
      "metadata": {},
      "source": { "kind": "upload" },
      "installedAt": "2026-09-22T00:00:00Z",
      "acceptedAt": null
    }
  ]
}
```
```

--------------------------------

### 生成 SDK 文档（全部特性）

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/README.md

构建 SDK 文档，启用所有特性，并将警告视为错误。

```bash
RUST_MIN_STACK=16777216 RUSTDOCFLAGS='-D warnings' cargo +1.99.1 doc --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --no-deps --locked
```

--------------------------------

### 前端格式检查、构建与差异检查命令

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/CONTRIBUTING.md

从仓库根目录执行，用于前端验证。build 已包含类型检查，不维护独立前端测试代码。

```bash
pnpm --dir frontend format:check
pnpm --dir frontend build
git diff --check
```

--------------------------------

### GET /api/admin/accounts/connection-test

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Starts a Server-Sent Events (SSE) connection test for a specified account. The test does not participate in normal account rotation and emits events such as test_start, request, content, and test_complete, or an error event on failure.

```APIDOC
## [GET] /api/admin/accounts/connection-test

### Description
Starts a Server-Sent Events (SSE) connection test for a specified account. The test does not participate in normal account rotation and emits events such as test_start, request, content, and test_complete, or an error event on failure.

### Method
GET

### Endpoint
/api/admin/accounts/connection-test

### Response
#### Success Response (200)
- **type** (string) - Event type: test_start, request, content, test_complete
- **occurredAt** (string) - Server-side timestamp when the event was emitted
- **occurredAtDisplay** (string) - Full display of the occurredAt timestamp
- **timeDisplay** (string) - Short display of the occurredAt timestamp

#### Error Response
- **type** (string) - Event type: error
- **source** (string) - Source of the error: gateway, provider, or upstream
- **gatewayErrorCode** (string) - Stable machine value of GatewayErrorKind
- **sendState** (string) - Send state: not_sent, sent, ambiguous, or null for non-provider errors
- **error** (string) - Raw diagnostic error message, null if missing
- **providerErrorCode** (string) - Provider error code, null if missing
- **providerErrorType** (string) - Provider error type, null if missing
- **upstreamStatus** (integer) - Upstream HTTP status code, null if missing
- **upstreamContentType** (string) - Upstream content type, null if missing
- **upstreamBody** (string) - Upstream response body, null if missing

#### Response Example
{
  "type": "error",
  "source": "upstream",
  "gatewayErrorCode": "rate_limited",
  "sendState": "sent",
  "error": "upstream unavailable",
  "providerErrorCode": "usage_exhausted",
  "providerErrorType": "invalid_request_error",
  "upstreamStatus": 429,
  "upstreamContentType": "application/json",
  "upstreamBody": "{\"error\":{...}}"
}
```

--------------------------------

### Install cpr-plugin with cargo install

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/apps/plugin-cli/README.md

Installs the cpr-plugin CLI from the repository root to a local tools directory using the pinned Rust toolchain 1.99.1. After installation, add /path/to/local-tools/bin to PATH or use the full executable path.

```bash
cargo +1.99.1 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
```

--------------------------------

### 验证 SDK（无默认特性）

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/README.md

运行 SDK 测试，不启用默认特性。

```bash
RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --no-default-features --locked
```

--------------------------------

### 小内存优化 GLIBC_TUNABLES 配置

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

在 deploy/config.yaml 的 services.app-runtime.environment 中设置 GLIBC_TUNABLES，默认关闭，官方 Linux 镜像支持。空字符串表示不启用额外调优。

```yaml
services:
  app-runtime:
    environment:
      GLIBC_TUNABLES: 'glibc.malloc.mmap_threshold=131072:glibc.malloc.trim_threshold=131072'
```

--------------------------------

### GET /v1/realtime/calls/{call_id}

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Alternative path for the sideband WebSocket, equivalent to GET /v1/live/{call_id}.

```APIDOC
## [GET] /v1/realtime/calls/{call_id}

### Description
Alternative path for the sideband WebSocket, equivalent to GET /v1/live/{call_id}.

### Method
GET

### Endpoint
/v1/realtime/calls/{call_id}

### Parameters
#### Path Parameters
- **call_id** (string) - Required - The call identifier.

### Response
#### Success Response (101)
- WebSocket connection established; frames are relayed as-is.

#### Error Responses
- **403** - Client Key is not the creator of the call.
- **404** - Call ID unknown or expired.
- **409** - A sideband is already active for this call.
```

--------------------------------

### GET /v1/realtime?call_id=…

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

Query parameter form of the sideband WebSocket, equivalent to GET /v1/live/{call_id}.

```APIDOC
## [GET] /v1/realtime?call_id=…

### Description
Query parameter form of the sideband WebSocket, equivalent to GET /v1/live/{call_id}.

### Method
GET

### Endpoint
/v1/realtime?call_id=…

### Parameters
#### Query Parameters
- **call_id** (string) - Required - The call identifier.

### Response
#### Success Response (101)
- WebSocket connection established; frames are relayed as-is.

#### Error Responses
- **403** - Client Key is not the creator of the call.
- **404** - Call ID unknown or expired.
- **409** - A sideband is already active for this call.
```

--------------------------------

### 人工恢复数据库：gzip 解压并通过 psql 恢复到空目标库

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

用于将业务归档（gzip 压缩的 SQL）恢复到空目标数据库。需先核对文件 SHA-256 与备份记录一致，并执行 `gzip -t backup.sql.gz` 校验归档完整性。示例中的账号、空目标库和归档路径需按实际情况替换，密码由命令交互输入。

```bash
set -o pipefail
gzip -dc backup.sql.gz | psql -X --single-transaction --set=ON_ERROR_STOP=1 --password \
  --dbname='postgresql://restore_user@127.0.0.1:5432/restore_db'
```

--------------------------------

### 下载部署文件并设置目录权限（bash）

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

下载同一正式 Release 的 compose.yaml 与 config.example.yaml，并设置应用数据、日志和配置目录权限。需先准备 Docker Engine、Compose Plugin、curl 和 OpenSSL，当前用户需能访问 Docker 并可用 sudo 或 root 设置权限。

```bash
mkdir -p codex-proxy-rs/deploy && cd codex-proxy-rs

# 只解析一次最新正式版本，确保两个文件来自同一 Release。
CPR_RELEASE_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/zyycn/codex-proxy-rs/releases/latest)"
CPR_RELEASE_TAG="${CPR_RELEASE_URL##*/}"
curl -fsSL "https://github.com/zyycn/codex-proxy-rs/releases/download/${CPR_RELEASE_TAG}/compose.yaml" \
  -o deploy/compose.yaml
curl -fsSL "https://github.com/zyycn/codex-proxy-rs/releases/download/${CPR_RELEASE_TAG}/config.example.yaml" \
  -o deploy/config.example.yaml

install -d -m 0750 .runtime/postgres .runtime/redis
sudo install -d -m 0770 -o "$(id -u)" -g 10001 .runtime/data .runtime/logs
sudo install -m 0640 -o "$(id -u)" -g 10001 deploy/config.example.yaml deploy/config.yaml
```

--------------------------------

### 验证 SDK（全部特性）

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/README.md

运行 SDK 测试，启用所有特性。

```bash
RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --locked
```

--------------------------------

### 构建源码联调产物

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/development.md

build:source 用各项目的 tsconfig.source.json 检查源码类型，管理端构建到 frontend/node_modules/.vite/source-dist，示例构建到其前端项目的 .vite/source-dist。

```bash
pnpm --dir frontend build:source
pnpm --dir modules/plugins/examples/workbench/frontend build:source
```

--------------------------------

### GET /api/admin/accounts/reset-credits/automation

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

读取自动使用开关与本地计划，不查询上游。

```APIDOC
## GET /api/admin/accounts/reset-credits/automation

### Description
读取自动使用开关与本地计划，不查询上游。

### Method
GET

### Endpoint
/api/admin/accounts/reset-credits/automation

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回自动使用开关与计划

#### Response Example
{
  "enabled": false,
  "plan": {}
}
```

--------------------------------

### GET /api/admin/accounts/quota-forecast

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

按需读取周/月容量预测、源窗口剩余估算与采样依据，不刷新上游额度。

```APIDOC
## GET /api/admin/accounts/quota-forecast

### Description
按需读取周/月容量预测、源窗口剩余估算与采样依据，不刷新上游额度。

### Method
GET

### Endpoint
/api/admin/accounts/quota-forecast

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回容量预测信息

#### Response Example
{
  "forecast": {}
}
```

--------------------------------

### 配置二进制部署模式

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

在现有 config.yaml 的 host 下合并此配置以启用二进制部署模式和管理端自重启。

```yaml
host:
  system_update:
    deployment_mode: binary
    self_restart_enabled: true
    executable_path: '/opt/codex-proxy-rs/codex-proxy-rs'
```

--------------------------------

### 后端验证命令（fmt、clippy、nextest）

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/architecture.md

从 backend/Cargo.toml 执行，仓库根目录没有 Cargo manifest。使用 cargo +1.99.1，设置 RUST_MIN_STACK=16777216 与 CI 一致。测试使用 nextest，版本与质量工作流一致；未安装 nextest 时可使用 cargo test 替代。

```bash
cargo +1.99.1 fmt --all --manifest-path backend/Cargo.toml -- --check
RUST_MIN_STACK=16777216 cargo +1.99.1 clippy --manifest-path backend/Cargo.toml --all-targets --all-features --locked -- -D warnings
RUST_MIN_STACK=16777216 cargo +1.99.1 nextest run --manifest-path backend/Cargo.toml --test main --locked --no-tests fail
```

--------------------------------

### GET /api/admin/accounts/import-tasks/detail

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

获取任务摘要和逐条结果，不含原始凭据。

```APIDOC
## GET /api/admin/accounts/import-tasks/detail

### Description
获取任务摘要和逐条结果，不含原始凭据。

### Method
GET

### Endpoint
/api/admin/accounts/import-tasks/detail

### Parameters
#### Query Parameters
- **taskId** (string) - Required - 任务 ID

### Response
#### Success Response (200)
- 返回任务摘要和逐条结果

#### Response Example
{
  "summary": {},
  "results": []
}
```

--------------------------------

### PluginBuilder::command_line

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/docs/capabilities.md

Register a command-line command. Freezes command help and binds an execution function. Registration and execution JSON are in binary payload; control envelope is `{}`.

```APIDOC
## PluginBuilder::command_line

### Description
Register a command-line command. Freezes command help and binds an execution function. Registration and execution JSON are in binary payload; control envelope is `{}`.

### Method
- `command_line` - Register a CLI command

### Parameters
- **help** (string) - Required - Command help text
- **executor** (function) - Required - Execution function

### Response
- **void** - Registration complete

```

--------------------------------

### GET /api/admin/accounts/import-tasks

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

获取当前管理员仍保留的任务，按创建时间倒序。

```APIDOC
## GET /api/admin/accounts/import-tasks

### Description
获取当前管理员仍保留的任务，按创建时间倒序。

### Method
GET

### Endpoint
/api/admin/accounts/import-tasks

### Parameters
无

### Response
#### Success Response (200)
- 返回任务列表

#### Response Example
{
  "tasks": []
}
```

--------------------------------

### GET /api/admin/accounts/detail

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

查询账号详情、额度和本地用量。

```APIDOC
## GET /api/admin/accounts/detail

### Description
查询账号详情、额度和本地用量。

### Method
GET

### Endpoint
/api/admin/accounts/detail

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回账号详情、额度和本地用量

#### Response Example
{
  "account": {},
  "quota": {},
  "usage": {}
}
```

--------------------------------

### 校验并重建应用容器

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

校验 Compose 配置并重建应用容器使配置生效；docker compose restart 不会更新容器环境变量。

```bash
docker compose -f deploy/compose.yaml config --quiet
docker compose -f deploy/compose.yaml up -d --no-build --no-deps --force-recreate codex-proxy-rs
```

--------------------------------

### GET /api/admin/accounts/quota

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

读取当前额度，不强制访问上游；Provider 未提供额度能力时返回空额度投影。

```APIDOC
## GET /api/admin/accounts/quota

### Description
读取当前额度，不强制访问上游；Provider 未提供额度能力时返回空额度投影。

### Method
GET

### Endpoint
/api/admin/accounts/quota

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回额度信息

#### Response Example
{
  "quota": {}
}
```

--------------------------------

### OAuth start 请求体

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

用于发起 OAuth 授权流程。重新授权已有账号时，start 请求仍携带 `provider` 和展示用 `name`，只额外提供目标 `accountId`；客户端不得提交 `credentialRevision`、旧 token 身份或其他并发控制字段。

```json
{
  "provider": "openai",
  "name": "account name",
  "accountId": null
}
```

--------------------------------

### GET /plugins/resources/{target}/{path}

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

获取公开静态资源，无须登录，但资源须声明公开且制品已被接受。

```APIDOC
## [GET] /plugins/resources/{target}/{path}

### Description
获取公开静态资源，无须登录，但资源须声明公开且制品已被接受。

### Method
GET

### Endpoint
/plugins/resources/{target}/{path}

### Parameters
#### Path Parameters
- **target** (string) - Required - 格式为 {instanceId}/{artifactSha256}/{revision}
- **path** (string) - Required - 包内已声明的相对路径

### Response
#### Success Response (200)
- 已校验的静态字节
- 设置 `private, no-cache` 与内容 ETag

#### Response Example
（静态资源字节）
```

--------------------------------

### 验证本地 SDK 修改

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/development.md

在临时副本运行 Cargo patch 验证尚未发布的 SDK 修改，避免改写插件锁文件。命令从宿主根目录执行，使用 RUST_MIN_STACK 和 CARGO_TARGET_DIR 环境变量。

```bash
(
  set -e
  cpr_sdk_check_dir=$(mktemp -d)
  trap 'rm -rf "$cpr_sdk_check_dir"' EXIT
  mkdir "$cpr_sdk_check_dir/backend"
  cp modules/plugins/examples/workbench/backend/Cargo.{toml,lock} "$cpr_sdk_check_dir/backend/"
  cp -R modules/plugins/examples/workbench/backend/{src,tests} "$cpr_sdk_check_dir/backend/"
  cp modules/plugins/examples/workbench/plugin.json "$cpr_sdk_check_dir/"
  RUST_MIN_STACK=16777216 CARGO_TARGET_DIR="$PWD/backend/target/plugin-development" \
    cargo +1.99.1 test --manifest-path "$cpr_sdk_check_dir/backend/Cargo.toml" \
    --config "patch.\"https://github.com/zyycn/codex-proxy-rs.git\".gateway-plugin-sdk.path=\"$PWD/backend/crates/gateway-plugin/sdk\""
)
```

--------------------------------

### GET /api/admin/settings

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

读取当前运行设置。返回包含 configRevision 的设置对象，用于后续更新时的并发控制。

```APIDOC
## [GET] /api/admin/settings

### Description
读取当前运行设置。返回包含 configRevision 的设置对象，用于后续更新时的并发控制。

### Method
GET

### Endpoint
/api/admin/settings

### Response
#### Success Response (200)
- **configRevision** (string) - 当前配置版本，用于更新时的并发控制。

#### Response Example
{
  "configRevision": "..."
}
```

--------------------------------

### 直接运行二进制时设置 GLIBC_TUNABLES

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

Linux/glibc 二进制部署需由启动器在进程启动前设置同一环境变量。该变量由 glibc 在进程启动时读取，不支持管理端热更新。

```bash
GLIBC_TUNABLES=glibc.malloc.mmap_threshold=131072:glibc.malloc.trim_threshold=131072 ./codex-proxy-rs
```

--------------------------------

### GET /api/admin/accounts/reset-credits

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

查询支持该能力的 Provider 重置卡，不读取本地库存。

```APIDOC
## GET /api/admin/accounts/reset-credits

### Description
查询支持该能力的 Provider 重置卡，不读取本地库存。

### Method
GET

### Endpoint
/api/admin/accounts/reset-credits

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回重置卡列表

#### Response Example
{
  "cards": []
}
```

--------------------------------

### PluginBuilder::management

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/docs/capabilities.md

Register a management page. Freezes the `ManagementRegistration` and binds `management.handle`. Request metadata is in control parameters, raw HTTP body in binary payload; responses are similarly separated.

```APIDOC
## PluginBuilder::management

### Description
Register a management page. Freezes the `ManagementRegistration` and binds `management.handle`. Request metadata is in control parameters, raw HTTP body in binary payload; responses are similarly separated.

### Method
- `management` - Register a management page

### Parameters
- **registration** (ManagementRegistration) - Required - Registration configuration
- **handle** (function) - Required - Handler function

### Response
- **void** - Registration complete

```

--------------------------------

### GET /api/admin/accounts/concurrency

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

查询账号当前并发占用。每页最多 100 条。

```APIDOC
## GET /api/admin/accounts/concurrency

### Description
查询账号当前并发占用。每页最多 100 条。

### Method
GET

### Endpoint
/api/admin/accounts/concurrency

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID
- **page** (integer) - Optional - 页码，默认 1
- **pageSize** (integer) - Optional - 每页数量，默认 20，最大 100

### Response
#### Success Response (200)
- 返回并发占用列表

#### Response Example
{
  "items": [],
  "total": 0
}
```

--------------------------------

### host.auth.save

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/docs/capabilities.md

Creates or replaces an account. For creation, provider must be explicitly provided; for replacement, exact credential revision must be submitted.

```APIDOC
## host.auth.save

### Description
Creates or replaces an account. For creation, provider must be explicitly provided; for replacement, exact credential revision must be submitted.

### Method
SDK callback

### Endpoint
`host.auth.save`

### Parameters
#### Request Body
- **account_id** (string) - Optional - Account ID for replacement
- **provider_id** (string) - Required for creation - Provider ID
- **name** (string) - Optional - Account name
- **email** (string) - Optional - Account email
- **group_ids** (array) - Optional - Group IDs
- **enabled** (boolean) - Optional - Whether enabled
- **credentials** (object) - Required - Raw credentials
- **credential_revision** (string) - Required for replacement - Exact credential revision

### Request Example
```json
{
  "provider_id": "openai",
  "name": "string",
  "email": "string",
  "group_ids": ["string"],
  "enabled": true,
  "credentials": {}
}
```

### Response
#### Success Response
- **account_id** (string) - Account ID
- **provider_id** (string) - Provider ID
- **name** (string) - Account name
- **email** (string|null) - Account email
- **group_ids** (array) - Group IDs
- **enabled** (boolean) - Whether enabled
- **updated_at_ms** (integer) - Last update timestamp

#### Response Example
```json
{
  "account_id": "string",
  "provider_id": "string",
  "name": "string",
  "email": "string|null",
  "group_ids": ["string"],
  "enabled": true,
  "updated_at_ms": 1234567890
}
```
```

--------------------------------

### GET /api/admin/accounts

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

分页查询账号与汇总。支持按 provider、groupId、search、status 等条件过滤，并可指定排序字段。

```APIDOC
## GET /api/admin/accounts

### Description
分页查询账号与汇总。支持按 provider、groupId、search、status 等条件过滤，并可指定排序字段。

### Method
GET

### Endpoint
/api/admin/accounts

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 页码
- **pageSize** (integer) - Optional - 每页数量
- **provider** (string) - Optional - Provider ID，固定为内置 `openai`、`xai`
- **groupId** (string) - Optional - 分组 ID
- **search** (string) - Optional - 搜索关键词
- **status** (string) - Optional - 账号状态
- **排序字段** (string) - Optional - 排序字段

### Response
#### Success Response (200)
- 返回分页账号列表与汇总信息

#### Response Example
{
  "items": [],
  "total": 0
}
```

--------------------------------

### GET /api/admin/plugins/extensions/{target}/resources/{path}

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

获取已校验的静态资源字节，需要管理身份。

```APIDOC
## [GET] /api/admin/plugins/extensions/{target}/resources/{path}

### Description
获取已校验的静态资源字节，需要管理身份。

### Method
GET

### Endpoint
/api/admin/plugins/extensions/{target}/resources/{path}

### Parameters
#### Path Parameters
- **target** (string) - Required - 格式为 {instanceId}/{artifactSha256}/{revision}
- **path** (string) - Required - 包内已声明的相对路径

### Response
#### Success Response (200)
- 已校验的静态字节
- 响应头包含 `X-CPR-Plugin-Response: 1`
- 设置 `private, no-cache` 与内容 ETag

#### Response Example
（静态资源字节）
```

--------------------------------

### HttpCall.settings_sources

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/docs/capabilities.md

Returns the configuration revision, host baseline, overrides, and key-scoped execution and HTTP timeout settings. Each override record includes instance ID, order, and value; modifications to the query result do not persist.

```APIDOC
## HttpCall.settings_sources

### Description
Returns the configuration revision, host baseline, overrides, and key-scoped execution and HTTP timeout settings. Each override record includes instance ID, order, and value; modifications to the query result do not persist.

### Method
GET (read-only access)

### Endpoint
N/A (SDK property)

### Parameters
- **config_revision** (string) - Configuration revision identifier.
- **host** (object) - Host baseline settings.
- **overrides** (array) - List of override records.
- **execution** (object) - Key-scoped execution settings.
- **http_timeout** (object) - Key-scoped HTTP timeout settings.

### Response
#### Success Response
- **config_revision** (string) - Configuration revision.
- **host** (object) - Host baseline.
- **overrides** (array) - Override records.
- **execution** (object) - Execution settings.
- **http_timeout** (object) - HTTP timeout settings.

#### Response Example
```json
{
  "config_revision": "abc123",
  "host": {"timeout": 5000},
  "overrides": [{"instance_id": "inst-1", "order": 1, "value": "..."}],
  "execution": {"mode": "fast"},
  "http_timeout": {"timeout_ms": 3000}
}
```
```

--------------------------------

### 生成 PostgreSQL 与 Redis 密码（openssl）

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md

为 PostgreSQL 与 Redis 分别生成一个 48 位十六进制密码，结果需写入 config.yaml 的 store.database.password 和 store.redis.password。

```bash
openssl rand -hex 24
openssl rand -hex 24
```

--------------------------------

### GET /api/admin/settings/admin-api-key

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

只返回管理 API Key 是否存在。

```APIDOC
## [GET] /api/admin/settings/admin-api-key

### Description
只返回管理 API Key 是否存在。

### Method
GET

### Endpoint
/api/admin/settings/admin-api-key

### Response
#### Success Response (200)
- **exists** (boolean) - 管理 API Key 是否存在。
```

--------------------------------

### 启动管理端开发服务器

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/development.md

另开终端启动管理端开发服务器，后端代理由 frontend/vite.config.ts 配置，验证 WebSocket 时直接连接后端。

```bash
pnpm --dir frontend dev
```

--------------------------------

### GET /api/admin/accounts/models

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

优先读取该 Provider + 套餐的模型 cache，缺失时有限实时拉取。

```APIDOC
## GET /api/admin/accounts/models

### Description
优先读取该 Provider + 套餐的模型 cache，缺失时有限实时拉取。

### Method
GET

### Endpoint
/api/admin/accounts/models

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回模型列表

#### Response Example
{
  "models": []
}
```

--------------------------------

### GET /api/admin/accounts/profile-avatar

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

返回支持头像能力的 Provider 字节流，需要管理员会话；version 仅区分浏览器缓存。

```APIDOC
## GET /api/admin/accounts/profile-avatar

### Description
返回支持头像能力的 Provider 字节流，需要管理员会话；version 仅区分浏览器缓存。

### Method
GET

### Endpoint
/api/admin/accounts/profile-avatar

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID
- **version** (string) - Optional - 版本号，用于浏览器缓存

### Response
#### Success Response (200)
- 返回头像字节流

#### Response Example
(二进制数据)
```

--------------------------------

### 未安装 nextest 时的替代测试命令

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/architecture.md

未安装 nextest 时可使用此命令，同样设置 RUST_MIN_STACK=16777216。该入口只在单个测试二进制内并发，跨 crate 依次运行。

```bash
cargo +1.99.1 test --manifest-path backend/Cargo.toml --test main --locked
```

--------------------------------

### GET /api/admin/accounts/personal-info

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/api.md

按需汇聚 Provider 上游个人资料、累计活动与订阅信息，不更新额度或 credential。

```APIDOC
## GET /api/admin/accounts/personal-info

### Description
按需汇聚 Provider 上游个人资料、累计活动与订阅信息，不更新额度或 credential。

### Method
GET

### Endpoint
/api/admin/accounts/personal-info

### Parameters
#### Query Parameters
- **accountId** (string) - Required - 账号 ID

### Response
#### Success Response (200)
- 返回个人资料、累计活动与订阅信息

#### Response Example
{
  "profile": {},
  "activity": {},
  "subscription": {}
}
```

--------------------------------

### plugin.state.migrate

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/docs/capabilities.md

Migrate plugin state in batches during incompatible upgrades. The host deactivates and drains old sessions, then calls this method to migrate to staging state; the plugin returns keep, replace, or delete for each item.

```APIDOC
## plugin.state.migrate

### Description
Migrate plugin state in batches during incompatible upgrades. The host deactivates and drains old sessions, then calls this method to migrate to staging state; the plugin returns keep, replace, or delete for each item.

### Method
- `migrate` - Perform batch migration

### Parameters
- **batch** (array) - Required - List of state items to migrate

### Response
- **results** (array) - List of decisions: `keep`, `replace`, or `delete`

```

--------------------------------

### host.auth.list

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/backend/crates/gateway-plugin/sdk/docs/capabilities.md

Lists account projections with optional provider filter and pagination. Does not include raw credentials.

```APIDOC
## host.auth.list

### Description
Lists account projections with optional provider filter and pagination. Does not include raw credentials.

### Method
SDK callback

### Endpoint
`host.auth.list`

### Parameters
#### Query Parameters
- **provider_id** (string) - Optional - Filter by provider ID
- **cursor** (string) - Optional - Pagination cursor
- **limit** (integer) - Required - Number of results (1-200)

### Request Example
```json
{
  "provider_id": "openai",
  "cursor": null,
  "limit": 100
}
```

### Response
#### Success Response
- **accounts** (array) - List of account projections
- **next_cursor** (string|null) - Pagination cursor, null if end

#### Response Example
```json
{
  "accounts": [
    {
      "account_id": "string",
      "provider_id": "string",
      "name": "string",
      "email": "string|null",
      "group_ids": ["string"],
      "enabled": true,
      "updated_at_ms": 1234567890
    }
  ],
  "next_cursor": null
}
```
```

--------------------------------

### 克隆仓库并初始化子模块

Source: https://github.com/zyycn/codex-proxy-rs/blob/main/docs/development.md

首次检出时使用 --recurse-submodules 同时下载子模块。已有仓库运行 git submodule update --init --recursive 对齐子模块。

```bash
git clone --recurse-submodules https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs
```