@mcex/cli

v1.11.9

Published

2 months ago

Cross-platform CLI for the MCE x internal developer platform with Keycloak authentication and MCP support.

Downloads

0High
0Medium
0Low

xclipse

MCE x CLI

公司内部研发平台的跨平台命令行入口。它同时面向研发人员、CI 和 AI 工具，提供：

无需登录即可使用的环境诊断、配置和命令发现；
沿用原项目的 Keycloak Authorization Code + PKCE 登录、离线刷新和本地安全缓存；
需要登录或指定 Keycloak 角色的命令门禁；
登录后自动进入只监听本机的网页控制台，并可随时重新打开；
网页控制台提供身份概览、基础配置、命令发现和非交互命令执行；
包含 Realm 角色、Client 角色和用户组的个人信息页；
使用服务端托管的 Codex 账号启动官方 Codex CLI，客户端不保存 refresh token；
通过领域化 media 命令安全调用平台托管的 TTS、视频、资产和素材库服务；
兼容原有 stdio MCP 服务。

环境与安装

支持 Windows、macOS 和 Linux，要求 Node.js 20 或更高版本。

默认从公共 npm registry 安装，无需修改用户级 npm 配置。如需显式固定 @mcex scope：

npm config set @mcex:registry=https://registry.npmjs.org/

公司私有 registry 仍受支持，可通过 mcex config --set registryUrl=<url> 或 shortcut 的 --registry-url <url> 显式选择。发布人员使用 npm run publish:all，脚本默认先把 patch 版本加一，再将同一 tarball 依次推送到公共 npm 和公司私有 registry；脚本会跳过已存在的同版本。若其中一个仓库失败，使用 --resume 以当前版本补推，不会再次修改版本号。可用 MCEX_PUBLIC_NPM_REGISTRY、MCEX_PRIVATE_NPM_REGISTRY 覆盖两个发布目标。旧版配置中作为默认值保存的私有 registry 会自动迁移到公共 npm；迁移后显式设置的私有地址会保留。

发布前需要在用户或 CI 的 .npmrc 中分别配置两个 registry 的令牌：

//registry.npmjs.org/:_authToken=${NPM_PUBLIC_TOKEN}
//packages.aliyun.com/60371955c4393f5ed3b7baa8/npm/npm-registry/:_authToken=${NPM_PRIVATE_TOKEN}

脚本会在修改版本号之前运行公共 npm 的 whoami 和 @mcex scope 权限检查。使用验证器 App 的本地交互发布会在公共 npm 推送前隐藏输入 6 位 OTP，并显式传给 npm publish；使用带 bypass 2FA 权限的 granular token 时直接回车即可。非交互环境可以临时提供 MCEX_PUBLIC_NPM_OTP，更推荐使用 bypass 2FA granular token 或 npm trusted publishing。

首次从本机发布公共包，或公共登录已经过期时，先运行：

npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
npm org ls mcex --registry=https://registry.npmjs.org/

双仓库发布命令：

# 仅预览：1.11.3 -> 1.11.4，不修改文件、不访问 registry
npm run publish:all -- --dry-run

# 默认 patch：自动修改 package.json 和 package-lock.json，然后推送两个仓库
npm run publish:all

# minor / major / 指定完整版本
npm run publish:all -- minor
npm run publish:all -- major
npm run publish:all -- 2.0.0

# 某个仓库失败后，用当前版本补推；不会再次升级版本
npm run publish:resume

# 等价写法（注意中间必须有独立的 --）
npm run publish:all -- --resume

脚本不会自动创建 Git commit 或 tag；发布成功后应提交版本文件。可先运行 npm whoami --registry=<registry-url> 分别检查两个仓库的发布身份。

macOS / Windows 日常启动 Codex 的推荐方式：

npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex shortcut install
mcex-codex
mcex-codex-app

需要直接使用完整 mcex 管理命令时，可选全局安装：

npm install --global --registry=https://registry.npmjs.org/ @mcex/cli
mcex --version

无需安装直接运行：

npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest doctor

本地开发：

npm install
npm run check
npm link
mcex help

旧命令 mcex-mcp-auth serve 仍保留为兼容别名；新代码应使用 mcex serve。

快速开始

# 公开命令，不需要登录
mcex doctor
mcex commands

# 登录；成功后浏览器自动跳转到本地网页控制台
mcex login

# 随时重新打开网页控制台
mcex console

# 终端内配置仍然保留
mcex config

# 查看包含角色信息的个人资料
mcex profile

# 调用研发平台 API
mcex request /api/projects

非交互环境可完全通过参数初始化：

mcex config \
  --set output=json \
  --set locale=zh-CN \
  --set apiBaseUrl=https://rd.example.internal

命令与访问控制

| 命令 | 访问级别 | 说明 | | --- | --- | --- | | mcex help [command] | 公开 | 详细帮助、参数和示例 | | mcex commands [--json] | 公开 | AI/脚本可读取的命令目录 | | mcex doctor | 公开 | 检查 Node、平台、配置和登录缓存 | | mcex config | 公开 | 打开配置页或参数化配置 | | mcex login | 公开 | Keycloak PKCE 登录，成功后默认进入网页控制台 | | mcex console | 公开 | 启动只监听本机的网页控制台 | | mcex auth status | 公开 | 查看本地会话状态，不输出令牌 | | mcex auth logout | 公开 | 删除本地登录缓存 | | mcex profile | 需登录 | 当前用户、角色和用户组 | | mcex request <path> | 需登录 | 携带令牌调用平台 API | | mcex request <path> --require-role <role...> | 需角色 | 调用前检查指定角色之一 | | mcex admin context | 需角色 | 要求 platform-admin 或 mcex-admin | | mcex media capabilities | 需登录 | 查询媒体 API、Provider 和版本能力 | | mcex media tts submit | 需登录 | 提交 TTS 异步任务 | | mcex media video submit | 需登录 | 提交视频生成异步任务 | | mcex media job inspect | 需登录 | 查询异步任务状态 | | mcex media job resolve | 需登录 | 按幂等键解析已有任务，避免重复付费提交 | | mcex media artifact pull | 需登录 | 流式下载并校验产物 | | mcex media asset upload | 需登录 | 流式 multipart 上传资产 | | mcex media library search/inspect/pull/publish | 需登录 | 查询、锁定、下载和发布素材 | | mcex codex list | 需登录 | 列出服务端账号元数据，不下载 refresh token | | mcex codex upload | 需登录 | 批量上传 codex-multi-auth 管理的账号池 | | mcex codex use | 需登录 | 选择账号并写入官方 ChatGPT 登录 | | mcex codex run | 需登录 | 使用所选账号启动官方 Codex CLI | | mcex codex app | 需登录 | 使用官方 ChatGPT 登录启动桌面 App | | mcex codex shortcut | 公开 | 安装或删除 macOS/Windows 快捷命令与桌面入口 | | mcex codex status | 公开 | 查看本地选择和官方登录状态 | | mcex codex reset | 公开 | 重置本地选择和登录并清理旧 provider 残留 | | mcex serve | 公开 | 启动兼容 MCP 服务 |

mcex codex list 的人类可读输出采用账号卡片：不显示账号服务地址和底层 ChatGPT UUID，只突出账号名称、当前选择以及短周期/长周期剩余额度。额度柱状图会随终端宽度缩放，高、中、低余额分别使用绿、黄、红提示；设置 NO_COLOR=1 可关闭颜色，设置 MCEX_ASCII=1 可在不支持 Unicode 的终端使用 ASCII 轨道。--json 保留完整账号元数据，但同样不会返回账号服务地址。服务端返回的空额度窗口不会显示成“长周期 100%”；只有带窗口长度、重置时间或实际用量的窗口才会进入账号卡片。这里的“刷新”是额度窗口重置，不是 ChatGPT 订阅续费或订阅到期。服务端确认 refresh token 已失效后，账号卡片会标记 “凭据已失效”，交互选择器会禁止选中该账号；显式指定该账号或凭据在启动期间失效时， CLI 会返回稳定错误码 codex_account_needs_reauth，需要管理员重新导入有效登录凭据。

CLI 的本地角色检查用于快速反馈和隐藏无权限入口，不能替代服务端授权。内部平台 API 必须继续在服务端校验访问令牌、资源和角色。

配置

网页控制台的“基础配置”和 mcex config 读写同一份配置。直接运行 mcex config 仍会打开终端配置页。当前基础配置包括：

locale：zh-CN 或 en-US；
output：text 或 json；
apiBaseUrl：内部研发平台 API 根地址，默认 https://apps-gw-prd.mcisaas.com/mci-devops-platform；
registryUrl：npm registry，默认公共 npm，也可配置公司私有 registry；
checkUpdates：是否检查 CLI 更新。

读取或脚本化修改：

mcex config --show
mcex config --show --json
mcex config --set output=json --set checkUpdates=false
mcex config --reset

配置位置遵循各平台约定：

Linux/macOS：${XDG_CONFIG_HOME:-~/.config}/mcex/config.json
Windows：%APPDATA%\mcex\config.json
测试/隔离环境：可通过 MCEX_CONFIG_DIR 覆盖

文件采用版本化 JSON 结构，后续可向后兼容地增加配置项。

本地网页控制台

mcex login 完成 Keycloak 登录后，回调页会自动跳转到本机控制台。已有登录状态时可直接运行：

mcex console

# 只启动服务，不自动打开浏览器
mcex console --no-open

# 登录后不保留网页控制台，适合脚本或 CI
mcex login --no-console --no-config --json

控制台展示当前身份、Realm/Client 角色、ChatGPT 账号、基础配置和机器可读命令目录。 ChatGPT 账号页先读取 codex-multi-auth 的本地账号与额度缓存并立即展示，再使用当前 Keycloak 会话连接平台补充当前用户可用账号、剩余 limit 和同步状态。平台不可用时页面保留本地结果并明确显示“远程同步失败”，不会把 access token 或 refresh token 返回给页面。命令执行器使用 JSON argv 调用同一版 CLI，不经过 shell，并自动要求结构化 --json 输出。删除登录缓存、重置 Codex 或配置等操作需要显式确认；serve、codex run、codex app、 codex auth-agent 等长驻、交互或会启动其他应用的命令仍应在终端运行。控制台由当前 mcex 进程托管，关闭使用时在终端按 Ctrl+C 停止。

控制台不是新的远程管理服务：它只允许绑定 127.0.0.1、::1 或 localhost，默认端口为 17654。页面使用随机 HttpOnly/SameSite 会话 Cookie、CSRF token、严格 Host 校验和 CSP。OIDC access/refresh token 始终保留在 CLI 进程及私有缓存中，不会返回给浏览器脚本；实际平台请求仍由服务端 Keycloak 授权决定。

平台媒体服务

自 1.8.0 起，mcex media 通过当前 Keycloak 会话调用 /api/v1/media。第三方 Seedance、语音和 OSS 凭据只存在于平台；CLI 不读取、不保存，也不输出这些凭据。这些命令直接调用平台 REST API，不经过 mcex_backend_request，也没有新增媒体 MCP Tool。

# 查询 API 版本、Provider 和功能开关
mcex media capabilities --json

# JSON 输入采用平台 lowerCamelCase 契约；重试时复用同一幂等键
mcex media tts submit \
  --input narration.json \
  --idempotency-key project-scene-01 \
  --json

mcex media video submit \
  --input seedance.json \
  --idempotency-key project-shot-01 \
  --json

mcex media job inspect job_123 --json

# 网络中断导致提交结果不明时，先解析幂等键，不要直接重提付费任务
mcex media job resolve \
  --type video \
  --idempotency-key project-shot-01 \
  --json

# 目标文件必须不存在。CLI 先写同目录临时文件，校验后再原子重命名
mcex media artifact pull artifact_123 \
  --output ./result.mp4 \
  --sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --json

# 文件以流式 multipart 上传，不编码进 JSON 或命令行参数；结果返回 artifactId
mcex media asset upload ./reference.png \
  --kind image \
  --project-id project_123 \
  --idempotency-key reference-01 \
  --json

素材库使用精确的 id@semver 引用。发布前先通过 asset upload 上传二进制，随后让 manifest 的 artifactId 引用上传结果：

mcex media library search --query product --cursor next_page --limit 20 --json
mcex media library inspect [email protected] --json
mcex media library pull [email protected] --output ./assets --json
mcex media library publish --manifest library-entry.json --json

library publish 首次创建接受 HTTP 201；同一 id@semver 和 SHA-256 的幂等重放接受 HTTP 200。相同版本对应不同 SHA-256 时，平台应返回带 code/message/requestId 的 409。

--json 的 CLI 外层是稳定的 snake_case envelope，例如 {"ok":true,"job":...}； job、capabilities、entry 等嵌套的平台 payload 原样保留 lowerCamelCase。首次提交任务成功时平台返回 HTTP 202；同一幂等键重放可返回 HTTP 200。两者都至少包含 jobId、status 和 requestId。

用户是否确认付费生成由上层 Skill 记录；真正的安全边界是平台 Grant、Quota 和服务端授权。CLI 不接受可伪造的 --approval-id。请求 JSON 可以包含只用于审计的 approvalContext，但平台不得把其中的布尔值作为授权依据。

apiBaseUrl 是服务根地址，可以是 https://host，也可以包含网关服务前缀，例如 https://host/mci-devops-platform。后一种配置会把媒体路径解析成 /mci-devops-platform/api/v1/media/...；已经带该前缀的兼容路径不会重复拼接。

所有媒体 HTTP 调用只允许发送到 apiBaseUrl 的同源、同服务前缀地址。绝对外部 URL、 //host 形式、反斜杠、路径穿越和内嵌 URL 凭据都会在附加 Bearer Token 前被拒绝。上传和下载错误会脱敏 Token 与常见签名参数；临时签名 URL 不进入稳定 JSON 输出。

Codex 远端账号

mcex codex 只使用官方 Codex 的 ChatGPT 文件登录模式。账号源主机或正式平台服务保管 OpenAI refresh token；客户端只获得 access_token、id_token、账号 ID 和到期时间，并写入官方 ~/.codex/auth.json。模型请求由官方 Codex 直接发送，不经过 MCE x 中转。

自 1.5.0 起，自定义 model_provider = "mcex-codex"、auth.command、动态 token helper 和桌面 provider 绑定已全部废弃。命令首次运行会安全清理旧版本留下的受管配置，不需要删除整个 ~/.codex。

自 1.7.0 起，职责进一步收敛：mcex 负责服务端账号分发、选择和短效凭据同步，codex-multi-auth/cli 负责把凭据应用到官方文件登录并返回脱敏状态。消费端不会调用 codex-multi-auth 的 OAuth 登录、本地账号池切换或 refresh token 刷新功能；真实 refresh token 仍只存在于服务端。升级期间 2.8.x 保留兼容写入路径，安装 codex-multi-auth 2.9.0 及以上后自动使用新的公共接口。

默认连接生产网关；也可通过以下任一种方式显式覆盖：

mcex codex list --server https://apps-gw-prd.mcisaas.com/mci-devops-platform/api
export MCEX_CODEX_SERVICE_URL=https://apps-gw-prd.mcisaas.com/mci-devops-platform/api
mcex config --set apiBaseUrl=https://apps-gw-prd.mcisaas.com/mci-devops-platform

选择账号并启动：

# 管理员：把当前 codex-multi-auth 账号池批量上传到平台
mcex codex upload --server https://platform.example/api

mcex codex list
mcex codex use acct_xxx
mcex codex run

# 每次启动前列出当前用户可用账号并交互选择
mcex codex run --select-account
mcex codex app . --select-account

# 非交互脚本直接指定平台账号 ID
mcex codex run --account acct_xxx

# 将参数原样交给官方 Codex
mcex codex run -- exec "完成这个长任务"
mcex codex run -- resume --last

macOS / Windows 快捷入口

日常使用优先安装快捷入口，无需全局安装 @mcex/cli。安装命令显式解析 @mcex/cli@latest，生成的快捷入口也会在每次启动时使用 --prefer-online 检查 npm 仓库中的最新客户端版本：

npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex shortcut install

# 日常首选；首次运行会自动完成公司登录和账号选择
mcex-codex

# 参数继续原样转发给官方 Codex
mcex-codex exec "完成这个任务"

# 启动官方 Codex 桌面 App
mcex-codex-app

--prefer-online 会在启动时强制检查仓库元数据，@latest 避免复用项目内可能存在的旧版 @mcex/cli；已经缓存的相同版本仍由 npm 复用。自动更新要求配置的 npm registry 可访问，并以仓库 latest dist-tag 指向的版本为准。已安装旧版快捷入口的用户重新执行一次上述安装命令，即可升级为自动检查最新版的包装脚本。快捷入口默认从公共 npm 获取 MCE x CLI；启动 Codex 时仍按 MCEX_CODEX_BIN、PATH 中可用版本、包内版本的顺序选择。

默认安装 run 和 app 两种入口。macOS 默认的 --scope auto 会先使用可写的 /usr/local/bin 与 /Applications；没有系统级权限时自动降级到 ~/.local/bin/mcex-codex* 与 ~/Applications/MCE x Codex.app，全程不会调用 sudo。可用 --scope system 或 --scope user 显式指定。Windows 写入用户 npm 命令目录，并在开始菜单创建 MCE x Codex。macOS App Bundle 使用 ChatGPT macOS 应用内置图标，Windows 开始菜单入口使用由同一图标转换的 Windows 图标；来源和商标说明见 THIRD_PARTY_NOTICES.md。桌面入口默认绑定安装命令执行时的当前目录，也可显式指定：

npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex shortcut install --target app --workspace /path/to/project
npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex shortcut install --target run --select-account
npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex shortcut install --account acct_xxx

安装是幂等的，并拒绝覆盖同名的用户文件；确需替换时使用 --force。删除只处理安装清单中由 mcex 管理的入口：

npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex shortcut remove

在 macOS/Windows 终端直接运行 codex run 且尚未安装默认快捷命令时，CLI 会用中文提示上述安装命令；检测到受管的 mcex-codex 后不再重复提示。

mcex codex upload 默认读取当前 codex-multi-auth 存储上下文，也可使用 --storage <path> 指定账号文件。整批上传会包含所有启用和停用账号；任一账号缺少 refresh token 时整批终止，避免服务端形成不完整快照。令牌只通过带 Keycloak Bearer 认证的 HTTPS 请求发送，不写入 CLI 输出。

@mcex/cli 直接依赖官方 @openai/codex，因此发布到 npm 后，新主机可以用一条命令安装并启动：

npx -y --prefer-online --registry=https://registry.npmjs.org/ @mcex/cli@latest codex run --server https://platform.example/api

启动时会先运行 codex --version 做健康检查，依次使用 MCEX_CODEX_BIN 指定的入口、 PATH 中已安装且可用的 Codex CLI、最后才使用 @mcex/cli 包内版本。这样已全局安装 Codex 的主机不会受包内平台可选依赖缺失影响；外部版本不可用时会自动回退。设置 MCEX_USE_BUNDLED_CODEX=1 可跳过 PATH 探测并强制使用包内版本。

如果本机没有 MCE x 会话，交互式 run 会先启动 Keycloak 登录。SSH 场景需要把登录回调端口转发到远端，例如 ssh -L 8765:127.0.0.1:8765 host。非交互环境必须预先运行 mcex login 或提供 MCEX_TOKEN_CACHE_PATH。

Codex 桌面 App

官方 Codex CLI、IDE 扩展和桌面 App 共享 ~/.codex/auth.json。macOS/Windows 可直接运行：

mcex codex app . \
  --server https://platform.example/api

该命令会：

选择并验证服务端账号；
从服务端领取不含 refresh token 的官方登录凭据；
原子更新 ChatGPT 模式 auth.json；
清理旧版 mcex-codex provider 残留；
直接启动官方 codex app。

如果桌面 App 已经运行，需要完全退出后重新打开。mcex codex status 可检查所选账号是否与官方登录文件匹配。

前台官方登录同步

需要验证官方订阅身份、插件目录和 personalAccessToken 认证效果时，可以让认证代理在前台运行：

mcex codex auth-agent acct_xxx --replace-login

该命令会替换当前官方 Codex 登录，因此必须显式传入 --replace-login。代理仅支持官方 CLI 的文件凭据存储，并在首次替换前把已有 ~/.codex/auth.json 备份为 ~/.codex/auth.json.mcex-backup。

进入该模式时，代理会自动清理旧版本遗留的 mcex-codex provider 和顶层选择。之后所有 CLI、IDE 和 App 都只读取官方登录文件。

账号服务会专门刷新并返回 access_token、id_token、账号 ID 和到期时间，但绝不返回 OpenAI refresh token。客户端使用原子替换和 0600 权限写入 ChatGPT 模式 auth.json；其中 refresh_token 是每次凭据安装时由本机生成的 48 字节高熵随机占位值，不使用真实 refresh token 的格式或固定公共字符串。真实 refresh token 始终只在服务器。写入后代理运行：

codex -c 'cli_auth_credentials_store="file"' login status

codex login --with-access-token 只接受 Codex Personal/Agent access token，不能用于这里的 ChatGPT OAuth access token，因此代理不会调用该命令。

前台会持续输出脱敏状态日志：

2026-07-30T07:00:00.000Z INFO  auth.backup  已备份当前 Codex 文件登录: ~/.codex/auth.json.mcex-backup
2026-07-30T07:00:00.010Z INFO  agent.start  前台认证代理已启动；账号=Primary (acct_xxx)...
2026-07-30T07:00:00.020Z INFO  token.fetch  正在从账号服务领取有效 access token
2026-07-30T07:00:00.100Z INFO  token.received  已收到短效凭据；剩余=237小时...
2026-07-30T07:00:00.110Z INFO  auth.write  正在原子更新 ChatGPT 模式 auth.json
2026-07-30T07:00:00.400Z INFO  codex.verify.output  Logged in using ChatGPT
2026-07-30T07:00:00.410Z INFO  token.installed  短效凭据已写入 auth.json 并经官方 Codex 验证

默认每 60 秒检查一次，剩余 1 小时时向服务端领取并安装新 token，从而尽量早于官方 App 自己的刷新尝试。token 本身不会出现在日志或命令参数中：

# 调整检查与提前刷新窗口
mcex codex auth-agent --replace-login \
  --interval 30 \
  --refresh-before 3600

# 只安装和验证一次
mcex codex auth-agent --replace-login --once

# JSON Lines 状态日志
mcex --json codex auth-agent --replace-login

# 恢复首次运行前的文件登录
mcex codex auth-agent --restore

按 Ctrl+C 可停止前台代理。运行中的桌面 App 可能缓存旧凭据；日志出现 app.reload 提示、账号仍未切换或发生 401 时，需要完全退出后重新打开 App。当前仅支持 --credential-store file，不写入 Keychain。

长任务与续期

mcex codex run 和 mcex codex app 不再承担运行时续期。需要覆盖超过当前 access token 有效期的长任务时，应在独立前台终端持续运行 mcex codex auth-agent --replace-login。代理默认每 60 秒检查一次，并在剩余 1 小时时向服务端领取新凭据、原子更新 auth.json。

服务短暂不可用时，官方 Codex 可继续使用尚未过期的当前 access token；服务持续不可用直到 token 过期，或服务端 refresh 失败时，任务仍可能中断。客户端不会自行刷新，也不会持有真实 refresh token。

本地敏感文件采用 0600 权限：

${XDG_CONFIG_HOME:-~/.config}/mcex/codex-selection.json：服务地址和账号选择，不含 token；
~/.codex/auth.json：官方 ChatGPT 登录文件，包含短效 access/id token 和本机随机 refresh 占位值；
~/.codex/auth.json.mcex-backup：首次替换前保留的原登录备份。

运行 mcex codex reset 会清理账号选择和旧 provider 残留；存在备份时恢复原登录，否则只在确认当前 auth.json 属于所选 mcex 账号时移除它。该命令不会删除源主机账号。也可单独使用 mcex codex auth-agent --restore 恢复备份。

登录、个人信息与角色

登录逻辑继续使用原项目的本地浏览器 PKCE 回调：

http://127.0.0.1:8765/callback

成功后访问令牌和刷新令牌只写入本地令牌缓存，不会由 CLI 或 MCP 工具输出。mcex profile 会聚合：

OIDC 用户资料；
realm_access.roles；
各客户端的 resource_access.<client>.roles；
用户组 groups。

Keycloak 客户端需要允许：

Valid redirect URIs:
http://127.0.0.1:8765/callback
http://localhost:8765/callback

Web origins:
http://127.0.0.1:8765
http://localhost:8765

如需长期会话，还要允许 offline_access。

认证环境变量

| 变量 | 默认值 | 用途 | | --- | --- | --- | | MCEX_KEYCLOAK_DISCOVERY_URL | production numa realm | OIDC discovery，优先级最高 | | MCEX_KEYCLOAK_ISSUER_URL | 未设置 | 用于推导 discovery URL | | MCEX_KEYCLOAK_BASE_URL + MCEX_KEYCLOAK_REALM | 未设置 | 用于推导 issuer | | MCEX_KEYCLOAK_CLIENT_ID | mcp-client | OIDC client ID | | MCEX_KEYCLOAK_CLIENT_SECRET | 未设置 | 仅供 confidential client | | MCEX_KEYCLOAK_REDIRECT_URI | localhost callback | 完整回调覆盖 | | MCEX_KEYCLOAK_SCOPES | openid profile email offline_access | OAuth scopes | | MCEX_TOKEN_CACHE_PATH | ~/.config/mcex-mcp/keycloak-token.json | 保留原项目缓存位置 | | MCEX_AUTH_OPEN_BROWSER | true | 是否自动打开浏览器 | | MCEX_CONSOLE_HOST | 127.0.0.1 | 网页控制台监听地址，只接受回环地址 | | MCEX_CONSOLE_PORT | 17654 | 网页控制台监听端口 | | MCEX_BACKEND_BASE_URL | 配置中的 apiBaseUrl | 平台 API 根地址，环境变量优先 | | MCEX_BACKEND_ALLOW_ABSOLUTE_URLS | false | 是否接受绝对 URL 输入；即使开启也严格限制为平台同源 | | MCEX_CODEX_BIN | 自动探测 | 显式指定官方 Codex CLI 可执行文件，优先级最高 | | MCEX_USE_BUNDLED_CODEX | false | 设为 1 时跳过 PATH 探测，强制使用 CLI 包内 Codex |

AI 和自动化调用

所有命令都有 --help、访问级别、参数说明和示例：

mcex help
mcex help request
mcex commands --json

AI 或 CI 应优先：

运行 mcex commands --json 发现能力；
为业务命令添加全局 --json，获得稳定结构化结果；
根据退出码处理错误：1 通用失败、3 需要登录、4 缺少角色；
不读取或传播本地令牌文件。

示例：

mcex --json profile
mcex --json request /api/projects
mcex --json request /api/admin --require-role platform-admin

MCP 兼容

{
  "mcpServers": {
    "mcex": {
      "command": "mcex",
      "args": ["serve"]
    }
  }
}

MCP 工具：

mcex_command_catalog
mcex_auth_status
mcex_auth_start_login
mcex_auth_complete_login
mcex_auth_whoami
mcex_auth_logout
mcex_backend_request

mcex_backend_request 可传 required_roles 做 CLI 侧预检查；服务端仍须执行最终授权。