.env.example

# ============================================================
# Codex2API Docker 环境变量配置
# 复制此文件为 .env 并修改对应值
# ============================================================

# HTTP 服务端口
# Note: the standard compose files bind to all interfaces (0.0.0.0).
# Set BIND_HOST=127.0.0.1 in .env to restrict to localhost only.
# BIND_HOST=0.0.0.0
CODEX_PORT=8080

# 监听地址（默认 0.0.0.0，兼容 Docker 端口映射 / 反向代理 / 公网部署）
# 如希望仅本机访问，可设置为 127.0.0.1
# CODEX_BIND=0.0.0.0

# 进程内 HTTP/WS 正文总预算，默认至少 128 MiB；不能小于单请求体上限。
# 超载 HTTP 返回 503 + Retry-After，WS 返回 1013；这是逻辑正文预算，不是 RSS 上限。
# CODEX_REQUEST_MEMORY_BUDGET_MB=128

# 管理后台登录密钥
# - 未设置时，首次访问 /admin 会进入“首次初始化”页面，请在浏览器内设置一个强随机密钥并妥善保存
# - 初始化页面需要填写服务日志里打印的一次性令牌（docker compose logs codex2api | grep "bootstrap token"），
#   令牌仅当前进程有效，重启后重新生成，初始化成功后立即作废
# - 未初始化之前，所有 /api/admin/* 接口（除 bootstrap 端点外）均返回 503
# - 如需以环境变量方式下发（如 CI/CD），可取消下面设置后重启，环境变量优先于浏览器初始化
# ADMIN_SECRET=your-admin-password

# 页面初始化来源 IP 白名单（逗号分隔 CIDR，可选；在一次性令牌之外的纵深防御）
# 判断的是与服务直连的 TCP 对端地址，不读取 X-Forwarded-For；经反向代理访问时对端是反代本身。
# 默认允许 loopback 与私有网段（兼容 Docker 网桥：宿主机访问容器时源 IP 是 172.17.0.1 这类网桥地址）。
# - 公网部署需要从外网 IP 完成页面初始化时，在这里放行你的来源网段，例如 203.0.113.0/24
# - 设为 none 则只允许 loopback（最严格；Docker 场景请改用 ADMIN_SECRET 跳过页面初始化）
# BOOTSTRAP_ALLOWED_CIDR=

# /v1/* 匿名访问开关（默认 false，强烈建议保持默认）
# 设置为 true 时：未配置任何对外 API Key 也允许 /v1/* 直接调用——仅限内网测试场景！
# CODEX_ALLOW_ANONYMOUS=false

# API Key 鉴权 L1/L2（默认启用）；false 恢复旧缓存策略，修改后重启
# CODEX_API_KEY_AUTH_CACHE_ENABLED=true

# 可信反向代理 CIDR/IP（影响 X-Forwarded-For / X-Real-IP 真实客户端 IP 解析）
# 默认信任本机回环与常见私有网段，兼容同机或 Docker 部署的雷池 WAF / Nginx / Caddy -> Codex2API。
# 如需收紧范围，请改成实际前置代理 IP/CIDR；设为 none 可完全禁用代理头。
# CODEX_TRUSTED_PROXIES=127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

# 全局代理（可选）
# CODEX_PROXY_URL=http://host.docker.internal:7890

# Codex 上游传输：默认 http；可设 ws 强制使用 WebSocket；auto 在 HTTP 入站下仍走 http
# CODEX_UPSTREAM_TRANSPORT=http

# Codex Multi-Agent v2 第三方子 Agent 明文兼容（实验性，默认关闭）。
# 仅对官方 Codex 客户端、原生 Codex 账号、且请求含 collaboration 下的
# spawn_agent / send_message / followup_task 时生效：移除 message 的
# encrypted 标记并把命名空间临时改名为 collaboration-optimize，响应再还原。
# 开启后无法区分子 Agent 提供方，匹配的 v2 协作消息都会走明文；上游可能按
# 非标准 schema 拒绝或触发风控，请先在隔离实例/账号池灰度。不解密历史密文；
# 冲突、无效 JSON 或工具数量超限时保持原生路径。
# 详见 docs/CODEX_MULTI_AGENT_V2_COMPAT.md。
# CODEX_MULTI_AGENT_V2_COMPAT=false

# WS 逐帧用量快照落库的节流间隔（秒），默认 30。内存快照每帧实时更新；
# 跨阈值、5pp 变化和 100% 仍会强制落库。大号池可按数据库承压情况调大。
# CODEX_WS_USAGE_FRAME_PERSIST_SECONDS=30

# WS 逐帧用量摄入开关，默认 true；设为 false 回退到 WHAM 探针与 HTTP 响应头
# CODEX_WS_USAGE_FRAME_INGEST=true

# 旧版 WebSocket 开关（兼容保留；推荐改用 CODEX_UPSTREAM_TRANSPORT=ws）
# USE_WEBSOCKET=true

# Codex HTTP TLS 指纹：默认 standard；如需回滚旧行为可设 utls_chrome
# CODEX_TRANSPORT_MODE=utls_chrome

# 下游 HTTP/SSE 保活周期；Go duration，0 关闭。流式端点从首个心跳起提交 SSE：
# Responses/Chat/Images 使用注释，Messages 使用原生 ping；非流式端点使用 HTTP 102。
# DOWNSTREAM_HTTP_KEEPALIVE_INTERVAL=30s

# 下游 WebSocket Ping 周期；Go duration，0 关闭。覆盖 Responses、Realtime 和 Live Sideband。
# DOWNSTREAM_WS_KEEPALIVE_INTERVAL=45s

# WS 握手默认发送 Codex User-Agent/Version；如需关闭可设 false
# CODEX_WS_SEND_USER_AGENT=true

# Codex 会话黏性 TTL，支持 Go duration（如 1h、90m）或秒数
# CODEX_SESSION_AFFINITY_TTL=1h

# bounded 亲和的空闲逃逸阈值：绑定空闲超过该时长才允许换号（活跃会话不轮换，
# 保住上游 prompt cache）。支持 Go duration 或秒数
# CODEX_SESSION_AFFINITY_IDLE_ESCAPE=10m

# X-Codex-Turn-State 模板缓存：主开关在管理后台系统设置
# 「Turn-State 模板缓存（实验性）」(codex_turn_state_template_cache_enabled)，默认关闭。
# 账号规则 codex_turn_state_account_mode=personal|team|auto（默认 auto）。
# 以下环境变量仅为可选调参，不再作为主开关（长度需对应合法 Fernet blocks）：
# CODEX_TURN_STATE_TEMPLATE_LENGTH=292
# CODEX_TURN_STATE_REPLACE_LENGTH=312
# CODEX_TURN_STATE_INJECT_MODE=replace-only
# CODEX_TURN_STATE_TTL=1h
# CODEX_TURN_STATE_MAX_ENTRIES=256
# CODEX_TURN_STATE_LOG_DECISIONS=false
# CODEX_TURN_STATE_DRY_RUN=false

# 加密压缩状态的来源亲和 TTL；仅缓存 SHA-256 摘要与来源元数据
# CODEX_COMPACTION_AFFINITY_TTL=168h

# 脱敏输出 Codex 指纹策略诊断日志
# CODEX_FINGERPRINT_DEBUG=false

# Codex 客户端遥测（实验性，事件为模拟生成）默认关闭，由管理后台开关开启；
# 设为 false 可在部署层强制关闭，无视后台开关
# CODEX_TELEMETRY_ENABLED=false

# 可选：覆盖 Codex Desktop/CLI 共用的公开 Statsig SDK Key
# CODEX_STATSIG_API_KEY=

# 临时计时探针：管理后台「遥测计时探针」开关或本变量任一开启即生效。开启后额外
# 打印 [TELEMETRY-TIMING] 日志（请求入口 setup、启动指标构建、流式解析累计耗时）；
# 默认关闭，关闭时不采集、无额外开销
# CODEX_TELEMETRY_TIMING_DEBUG=false

# 快速调度器（可选，也可在管理后台运行时开启）
# FAST_SCHEDULER_ENABLED=true

# 生图工作台图库目录；Docker 标准版 compose 已将 /data 挂载为持久化卷
IMAGE_ASSET_DIR=/data/images

# 日志目录；只允许写临时盘的平台可改为 /tmp/logs
LOG_DIR=logs
# 禁用文件日志（上游错误日志与安全审计日志）；只读文件系统可设为 true
LOG_DISABLED=false
# 安全审计日志目录；留空则使用 LOG_DIR/security
# SECURITY_LOG_DIR=/tmp/logs/security

# ---- PostgreSQL ----
DATABASE_DRIVER=postgres
DATABASE_HOST=postgres
DATABASE_PORT=5432
DATABASE_USER=codex2api
DATABASE_PASSWORD=codex2api
DATABASE_NAME=codex2api
# 可选：自定义 schema（适用于 Supabase 等多项目共享 database 的场景）
# 启动时会自动 CREATE SCHEMA IF NOT EXISTS，并在所有连接上 SET search_path 到该 schema
# 仅允许字母/数字/下划线，长度 ≤63；留空时使用数据库默认 search_path（通常是 public）
# DATABASE_SCHEMA=codex2api

# ---- Redis ----
CACHE_DRIVER=redis
# 支持 host:port、redis://...、rediss://...；Aiven / Upstash 通常使用 rediss://
REDIS_ADDR=redis:6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DB=0
REDIS_TLS=false
REDIS_INSECURE_SKIP_VERIFY=false

# ---- 时区 ----
# 决定自然日限额(cost_limit_daily/token_limit_daily)的零点重置时刻等本地时间语义。
# 写在本文件即可生效(进程环境变量里的 TZ 优先级更高);Windows 亦支持(时区库已内嵌)。
TZ=Asia/Shanghai

# ---- Grok 上游 OAuth client_id（可选）----
# 默认使用官方 Grok CLI 公开 client_id；留空即默认，默认行为零变化。
# 用于多 client_id 部署、灰度对照或端点测试：设为自定义 client_id 即覆盖所有 Grok OAuth 落点
# （浏览器授权、授权码兑换、refresh、device flow、SSO→Build 转换链）。
# GROK_OAUTH_CLIENT_ID=

# Optional durable image queue (0/unset keeps legacy admission behavior).
# For a 2 GiB single-instance deployment, begin with 2 and measure peak memory.
# IMAGE_JOB_WORKERS=2
# IMAGE_UPSCALE_CACHE_MB=64
# IMAGE_THUMB_CACHE_MB=16
# GOMEMLIMIT=768MiB
# Optional image retention. 0/unset disables the corresponding automatic purge.
# Generated assets are deleted after 3 days; completed text history after 30.
# IMAGE_ASSET_RETENTION_DAYS=3
# IMAGE_JOB_RETENTION_DAYS=30

# Opt-in image pipeline: total waiting jobs vs simultaneous memory-heavy work.
# Set IMAGE_JOB_WORKERS=10 and IMAGE_JOB_MEMORY_WORKERS=1 on a small single instance.
# 0/unset preserves the existing worker behavior. Memory workers must not exceed workers.
IMAGE_JOB_MEMORY_WORKERS=0