CodexShare

当前状态： 0.12.19 是 CodexShare v2 closed beta。v2 使用本地 Buyer Adapter、 Seller Credential Broker 和无工具能力的 Seller Worker，把卖家机器上的 Codex 容量按请求 接入中心 Relay。Stripe 当前固定在 Test 模式；卖家只获得不可提现、不可转让的 POOL_ONLY 服务额度。详见 v2 设计、 Phase 0 真实账号证据 和 0.12.19.0 变更记录。

CodexShare 让 Provider 把本机已登录的 Codex 容量加入公共池，由中心调度给 Consumer：

• Provider 直接运行 codexshare share；CLI 读取当前主机上同一用户的 Codex 登录， 不需要单独 enrollment
• Consumer 运行 codexshare borrow
• Consumer 继续使用官方 codex CLI；模型响应中的 tool call 只有在终态校验通过后才交给 Buyer 机器上的 Codex 执行，Seller Worker 不具备工具、Shell 或工作区能力
• Provider 的 OAuth access token、refresh token 和账户 ID 不离开 Provider 机器

本项目不修改 OpenAI Codex 源码。它用 Provider daemon、Consumer loopback gateway 和 Codex 已支持的自定义 Responses provider 完成转发。

CodexShare 不是 OpenAI 官方产品。订阅共享可能受服务条款、组织政策或风控限制。

CodexShare v2 只代理 Codex Responses 模型面：

• GET /v1/models
• POST /v1/responses
• POST /v1/responses/compact 不在当前 closed-beta 边界内

因此 Consumer 的 Git、npm、curl、MCP 和 Shell 网络流量不会经过 Provider。Buyer Adapter 只转发模型请求与 SSE；tool call 在完整终态到达前不会交给 Codex，执行结果作为下一次 Responses 请求重新报价、冻结和转发。Seller Worker 从不执行买家的工具。

GPT-6 Astra 可通过 codexshare borrow --model gpt-6-astra 选择。需要平台已启用 GPT-6 价格簿，且有运行 0.12.18 或更高兼容版本的 Worker 提供该模型；默认模型仍为 gpt-5.5。有管理员模型限制的账号还需将 gpt-6-astra 纳入允许范围。

安装

运行要求：Node.js 22.15 或更高版本（Consumer 与 Gateway 需要原生 zstd 支持）。

从源码安装：

git clone <this-repository>
cd codexshare
pnpm install
pnpm build
pnpm link --global

也可以用 npm：

npm install
npm run build
npm link

公网 Alpha 推荐直接从 npmjs.org 安装：

npm install -g @codexshare/cli --registry=https://registry.npmjs.org

如果公司 npm 镜像仍返回旧版本，运行 npm install -g @codexshare/cli@latest --registry=https://registry.npmjs.org 强制从官方源升级，再用 codexshare --version 确认版本。

CLI 每次启动都会读取本地版本检查缓存，最多每 24 小时访问一次官方 npm registry； 发现新版后会在后续每次启动时提示，但不会自动安装。显式升级可使用任一等价命令：

codexshare update
codexshare upgrade

也可以安装由官网托管、经过校验的固定版本 tarball：

npm install -g https://api.codexshare.codes/downloads/codexshare-cli-0.12.19.tgz

对应的 SHA-256 校验文件：

curl -fsS https://api.codexshare.codes/downloads/codexshare-cli-0.12.19.tgz.sha256

要求：

• Node.js 22.15+
• macOS 或 Linux
• Provider 已安装官方 Codex CLI，并完成 codex login
• Consumer 已安装官方 Codex CLI

怎么用

Cloud 模式按 CLI 进程注册、调度和计量。Control Plane 和 Gateway/Relay 是中心服务； Provider 的 OpenAI OAuth 只在 Provider 本机读取和注入，中心不保存也不分发 Token。

首次使用先在 codexshare.codes/register 创建账号，然后在 CLI 中选择使用账号密码或邮件验证码登录。CLI 只登录已有账号， 不会自动注册新账号：

codexshare login
# 或直接指定登录方式
codexshare login --method password --email [email protected]
codexshare login --method otp --email [email protected]

密码只通过交互式隐藏输入读取，不支持命令行参数，避免进入 shell 历史。 登录会自动为当前设备创建一份可撤销 Access Bundle，不需要复制任何 csc_... 凭据。贡献容量与借用容量分别使用：

codexshare share --max-concurrency 1
codexshare borrow
codexshare borrow --strategy ifPossible
codexshare borrow --max-output-tokens 4096
codexshare usage
codexshare status
codexshare logout
codexshare update
# upgrade 是 update 的等价别名
codexshare upgrade

官方安装包只提供一个 codexshare 可执行文件。codexshare --help 列出的公开子命令为 login、share-login、worker、share、borrow、usage、status、logout、 update 和 upgrade。

share/worker 默认直接读取当前进程看到的官方 Codex 登录（遵循 CODEX_HOME，默认 ~/.codex），不会执行 shell alias 或启动 codex login 子进程。只要该系统用户已经登录 Codex，即可直接贡献容量：

codexshare share --max-concurrency 1
# worker 是 share 的显式 v2 名称，适合无交互运行
codexshare worker --max-concurrency 1 --json

share-login --auth-file 仅作为旧版显式隔离凭据流程的兼容入口，不是普通 share 的前置 条件，且不会删除源文件。已有隔离 auth 文件也可以直接启动兼容 Worker；share 故意不接受 该参数，避免把兼容路径误当成默认路径：

codexshare worker --auth-file /path/to/auth.json --max-concurrency 1

share/worker 是前台长驻进程；出现 READY 后仍会继续阻塞， 按 Ctrl-C 才会 drain 并退出。普通账号不需要管理员预先授权容量，可自行选择 --max-concurrency 1..8；默认账号上限和签名 Worker release 上限均为 8。管理员可把账号 上限收紧到 0..8，其中 0 会立即 drain 当前进程、撤销 claim、释放 reservation，并通过 Relay 硬停止正在贡献的 Worker。

borrow 与原生 Codex 共用同一份会话列表。Codex 会给每个会话打上创建时的 provider id， 且 codex resume 只列出与当前 provider 相同的会话；borrow 在启动时把 Codex 线程索引 （$CODEX_HOME/state_*.sqlite 的 threads.model_provider）里的原生会话标成 codexshare， 退出时再把所有 codexshare 会话标回 openai，并把借用会话 rollout 首行的标签同样改成 openai（等长改写）。于是借用时产生的会话可以用原生 codex resume 继续，原生会话也可以在 codexshare borrow -- resume 下继续。borrow 被 kill -9、崩溃时由一个独立的守护小进程完成 同样的恢复；断电等极端情况下，下一次运行任意 codexshare 命令时自动修复。 共享会话列表需要 Codex CLI 0.110 及以上；borrow 启动前会运行一次 codex --version， 过旧或无法解析的版本只打印警告，不阻塞借用。

borrow 不带 --model 时使用 Pool 推荐的 Price Book 模型（启动时会打印所选模型），不会沿用 Codex 自己的默认模型；传入 Price Book 之外的模型会得到 MODEL_NOT_IN_PRICE_BOOK 和可用模型列表。 borrow 默认使用 --strategy required；没有兼容的在线 Seller、余额不足或请求无法 形成有效 quote/hold 时会明确失败。--strategy ifPossible 需要本机已有自己的 Codex 订阅登录，且只会在平台明确证明请求尚未派发时回退到本机账号；已派发或 UNKNOWN 请求永不会自动重放。--max-output-tokens 允许买家在发出请求前收紧报价和冻结上限。

打开 v2 Dashboard 后使用同一账号查看 Pool、 Share、Billing、Activity 和 Devices。管理员仍使用普通登录入口；Control Plane 根据服务端 角色开放 /dashboard/v2/admin 的元数据操作台。 官网首页和登录后的 v2 Dashboard 都通过 Control Plane 的 /v2/pool/status 突出显示 Pool 总 Share 并发槽位、当前可用槽位和匹配状态，并且都每 15 秒自动刷新；登录后的 Share Capacity 还会每 5 秒刷新当前账号的 Worker facts，无需用户刷新页面。 匹配开关暂停或缺失、状态源不可用时会显示暂停或不可用，不会把它们冒充成零容量。 官网首页和每个登录后的 v2 Dashboard 页面还会显示同一条管理员公告流：最多 3 条已发布 置顶公告优先，其余公告按发布时间倒序排列，展开后只显示纯文本详情。管理员可在 /dashboard/v2/admin 的 Notifications 区域创建、编辑、发布、取消发布、置顶和删除公告。 每台 CLI 设备可在网页撤销；macOS 默认把登录会话、Access Bundle 和 Credential Broker 的 专用分享凭据放在 Keychain，Linux 使用 ~/.codex-share 下权限为 0600 的本地文件，详见 Linux 支持说明。API 不返回 Prompt 或 Response 正文。

新账号初始余额为 $0，不自动赠送礼金。v2 分开显示现金支持的充值额度、在途 hold、成熟中的 POOL_ONLY 和可消费的 POOL_ONLY。Stripe 当前固定使用 Test account/livemode=false； 浏览器 success URL 不入账，只有签名 Webhook 经过 event inbox 和 Financial Worker 的幂等 校验后才发行充值额度。当前不提供活动码、用户间转账、现金提现或礼品卡兑换。

每次启动生成新的 process_id，用短租约、持久 WSS Relay、请求级 quote/hold、单一 armed attempt、可恢复 delivery 和幂等 settlement 完成闭环。当前架构与信任边界以 v2 设计 为准。当前 v2 的整机恢复流程见 灾备与整机恢复； 旧 Cloud 部署指南 与 公网 Alpha 快速上手 保留的是 v1/0.6 历史资料。

查看状态和用量

codexshare usage
codexshare usage --json
codexshare status
codexshare status --json

usage 从中心账本读取当前账号累计的 Borrow/Share 请求和 Token；status 同时展示登录 账号、当前设备、余额和 Dashboard 地址。平台不提供提现、转账或礼品卡兑换命令。

安全模型

• OAuth token 仅由 Provider 进程读取和刷新，不写入中心账本或 Consumer 环境变量。
• 每台登录设备有独立 Provider/Consumer 凭据，可在 Dashboard 单独撤销。
• Buyer 只能通过中心 Scheduler 获取短期 Assignment，不能指定 Seller 地址。
• 服务端只允许 Responses 模型路由，Provider 并发由 --max-concurrency 限制。
• Relay 记录请求状态、摘要、字节和终态 usage；业务数据库不保存 Prompt、Response 或工具参数正文。
• 本地日志写到 ~/.codex-share/logs/，敏感字段脱敏并按 5 MiB 轮转。
• Consumer 本地 gateway 只监听 127.0.0.1，并要求每次启动随机生成的 Bearer key。
• Consumer 对请求 ID、Assignment、模型、档位、参数语义哈希和允许转发的请求头摘要签名； Responses query string 和未列入白名单的上游请求头会被拒绝或移除。每个转发请求再使用 平台签发、绑定 Provider、路由和最终正文哈希的一次性 Request Capability。Gateway 不持有平台签名私钥，也不能静默改写 Prompt 或非预算参数。
• tool call 只有在完整合法的 terminal event 到达后才交给 Buyer Codex；工具仍只在 Buyer 机器执行。
• v2 回执证据等级为 CLIENT_ATTESTED，不宣称 PLATFORM_VERIFIED。

信任边界仍然存在：模型 Prompt 必须经过中心 Gateway 和被调度的 Provider 进程。

故障排查

No Codex login found

: 在 Provider 机器运行 codex login。如果自定义了 CODEX_HOME，启动 codexshare share 时也要带相同环境变量。

No READY Provider process has an available slot

: 当前公共池没有空闲且兼容所选模型的 Provider，稍后重试。

Credit balance is empty

: 当前账号没有可消费额度。请在 v2 Dashboard 的 Credits & Billing 中完成 Test Checkout， 并等待签名 Webhook 把订单推进到 CREDIT_ISSUED。

需要完整诊断

: 查看 ~/.codex-share/logs/share.log 或 connect.log。日志不包含 OAuth、设备密钥和 请求正文。

Seller Worker 输出 READY 后没有退出

: 这是预期行为。Seller Worker 是前台长驻进程，必须保持运行才会进入 Pool；按 Ctrl-C 执行 drain 并退出。

开发与验收

pnpm build
pnpm test
pnpm run test:postgres
pnpm run test:disaster-recovery-docker
pnpm run test:real-v2-account

PostgreSQL 与真实账号测试需要显式配置隔离环境；灾备 Docker 测试需要可用的 Docker daemon。真实账号测试会调用本机安装的官方 Codex CLI，不应在没有请求预算和专用 Seller 登录时运行。

v2 的架构、产品和信任边界见 docs/design/codexshare-v2-design.md，真实 Phase 0 验收见 docs/releases/v2-phase0-evidence-2026-08-14.md。 docs/product-strategy.md、docs/process-pool-mvp-design.md 和 docs/parity-checklist.md 是 v1 之前的历史快照。定期商业化与交互评审基线见 docs/commercialization-product-prototype-spec-2026-08-07.md。