cc-unlock v7.0.0 - Isolated Launchers

cc-unlock 通过一个统一命令运行 Claude Code 与 Codex，不再安装到真实 ~/.claude、~/.codex 或工作区配置。

主入口根据子命令选择产品，并自动识别 Windows、macOS、Linux：

• dist/cc-unlock.js
• dist/claude-sandbox.js
• dist/codex-sandbox.js

后两个文件保留为独立兼容入口。

目录结构

cc-unlock-v7.0.0/
├── package.json             npm 快捷启动指令
├── dist/                    可发布的混淆单文件启动器
│   ├── cc-unlock.js         统一自动检测入口
│   ├── claude-sandbox.js
│   └── codex-sandbox.js
├── windows/                 Windows 环境隔离后端
├── macos/                   macOS Seatbelt 后端
├── linux/                   Linux bubblewrap 后端
├── scripts/
│   ├── build.js             单文件打包与混淆构建器
│   ├── cc-unlock.js         统一源码入口
│   ├── claude-sandbox.js    Claude 源码入口
│   ├── codex-sandbox.js     Codex 源码入口
│   ├── lib/                 共享初始化与路径保护逻辑
│   └── tests/               沙盒 smoke tests
├── codex-files/             Codex bundle 明文维护源，不直接发布
├── claude-files/            Claude bundle 明文维护源，不直接发布
└── docs/                    文档

旧 GUI、安装、卸载、菜单、验证脚本及 cc-unlock-files/ 已删除。

要求

• Node.js 18+
• Claude Code 或 Codex CLI 已安装
• Linux 默认强隔离需要 bubblewrap (bwrap)；只有显式 --env-only 才允许弱隔离

CLI 必须位于非空 PATH 项中，或通过 --binary / CLAUDE_BINARY / CODEX_BINARY 明确指定。启动器不会把工作区里的同名文件当作 CLI；显式路径无效时也不会回退到其他安装。

快速开始

发布到 Registry 后，三平台均使用同一个 npm 包：

npx cc-unlock codex
npx cc-unlock claude

产品名之后的原生命令和参数会继续传给对应 CLI：

npx cc-unlock codex exec "分析当前项目"
npx cc-unlock claude -p "分析当前项目"

如果系统中只检测到其中一个 CLI，可以省略产品名；如果两个都存在则必须显式选择，避免误启动：

npx cc-unlock --workspace /path/to/project
CC_UNLOCK_PRODUCT=codex npx cc-unlock --workspace /path/to/project

原 package.json 中的运行类快捷指令也可以直接通过统一包调用：

npx cc-unlock claude:ccswitch --workspace /path/to/project
npx cc-unlock codex:ccswitch --workspace /path/to/project
npx cc-unlock claude:init --workspace /path/to/project
npx cc-unlock codex:init --workspace /path/to/project
npx cc-unlock claude:refresh --workspace /path/to/project
npx cc-unlock codex:refresh --workspace /path/to/project
npx cc-unlock claude:status --workspace /path/to/project
npx cc-unlock codex:status --workspace /path/to/project
npx cc-unlock claude:reset
npx cc-unlock codex:reset

需要显式关闭 Claude Code 权限确认时使用独立危险模式快捷指令：

npx cc-unlock claude:dangerous --workspace /path/to/project
npm run claude:dangerous -- --workspace /path/to/project

该快捷指令只为本次 Claude 进程添加 --dangerously-skip-permissions，普通 claude/claude:ccswitch 启动不会继承它。macOS/Linux 的外层文件系统沙盒仍按原规则生效，但 Claude 在可写工作区内不会再请求工具确认；Windows 普通进程没有等价强边界，只应对完全可信的工作区使用。

仓库内也保留 npm 快捷命令：

npm run claude -- --workspace /path/to/project
npm run codex -- --workspace /path/to/project

第一个 -- 由 npm 消费，后续参数原样传给对应启动器。例如，把参数继续传给原始 CLI：

npm run claude -- --workspace /path/to/project -- --help
npm run codex -- --workspace /path/to/project -- --help

也可以直接运行统一 Node.js 入口。

macOS / Linux

chmod +x dist/cc-unlock.js dist/claude-sandbox.js dist/codex-sandbox.js

./dist/cc-unlock.js codex --workspace /path/to/project
./dist/cc-unlock.js claude --workspace /path/to/project
./dist/claude-sandbox.js --workspace /path/to/project
./dist/codex-sandbox.js --workspace /path/to/project

Windows

node dist\cc-unlock.js codex --workspace "C:\work\project"
node dist\cc-unlock.js claude --workspace "C:\work\project"

三平台参数完全一致。传给原始 CLI 的参数放在 -- 后：

node dist/claude-sandbox.js --workspace /path/to/project -- --help
node dist/codex-sandbox.js --workspace /path/to/project -- --help

全局安装 npm 包后可使用统一命令，两个独立命令继续作为兼容别名：

cc-unlock codex --workspace /path/to/project
cc-unlock claude --workspace /path/to/project
cc-unlock-claude --workspace /path/to/project
cc-unlock-codex --workspace /path/to/project

构建与发布保护

npm install
npm run build

构建过程先递归读取 claude-files/ 和 codex-files/，拒绝符号链接、硬链接、非普通文件、Windows 非法文件名、大小写/Unicode 归一化冲突和其他不安全路径，按稳定顺序生成带逐文件 SHA-256 的资源清单，再在清单尺寸上限内使用 Brotli 压缩。esbuild 将资源解码器、共享核心和 Windows/macOS/Linux 后端打入统一入口及两个兼容入口，压缩资源作为校验型尾段写入每个单文件，最后用固定配置执行控制流、标识符和 RC4 字符串数组混淆。npm test 与 npm 快捷命令实际执行 dist/ 产物。

npm publish 会通过 prepublishOnly 强制重新构建；npm pack 不执行构建，使下载后的精简包不会尝试调用未发布的源码构建工具。发布前应先运行 npm test。

仓库中的源码入口会在开发态直接读取明文维护源；npm 快捷命令执行的则是 dist/。修改 claude-files/ 或 codex-files/ 后，必须先执行 npm run build（或直接运行会自动预构建的 npm test），否则本地快捷命令仍会使用上一次嵌入的资源。单独执行 npm pack 也不会刷新资源。

npm 发布白名单精确列出三个 dist/*.js 产物、文档和许可证，不直接发布 claude-files/、codex-files/，也不会带入 dist/ 临时文件、sourcemap、scripts/、平台后端源码、测试或构建依赖。启动器初始化时从自身尾段校验并解压资源，再按生命周期规则写入产品沙盒，不依赖安装目录旁的资源文件。

Brotli、Base64 和 JavaScript 混淆只减少静态明文暴露，不是密码学意义上的保密。获得安装权限的用户仍可恢复内嵌资源，初始化后的沙盒文件也必须是 Claude/Codex 可读取的明文；凭据、许可证私钥和真正不可公开的服务端逻辑不能写入这些资源或 npm 包。

CC Switch 中转配置

默认启动器不会读取真实 Claude/Codex 配置。需要跟随 CC Switch 当前选择的中转站时，使用显式快捷命令：

npm run claude:ccswitch -- --workspace /path/to/project
npm run codex:ccswitch -- --workspace /path/to/project

等价的直接参数是 --ccswitch-sync。启动器在进入 OS 沙盒前只读检查 ~/.cc-switch/cc-switch.db marker，并从 CC Switch 当前生成的 live 文件导入白名单字段：

• Claude：从 ~/.claude/settings.json 导入 endpoint、认证 token、模型映射和已知 Claude 运行参数
• Codex：从 ~/.codex/config.toml 导入 provider/model 根键与当前 [model_providers.*]，从 ~/.codex/auth.json 只导入 OPENAI_API_KEY
• 不导入 Codex MCP、plugins、projects、marketplaces、notify 或旧 model_instructions_file
• 不导入 Claude hooks、permissions、theme 或任意未知环境变量

Claude 的 live endpoint 或 Codex 当前 provider base_url 如果指向 loopback，状态会显示 proxy，此时 CC Switch 必须保持运行；普通 HTTP(S) 上游显示 direct，没有显式 base_url 的 Codex provider 显示 custom。存在但不是绝对 HTTP(S) URL 的 endpoint 会拒绝导入。每次用上述 *:ccswitch 命令启动都会重新读取当前 live 快照，因此切换 provider 后需重新执行对应命令；已经运行的会话不会热更新。

成功导入后，普通 npm run claude / npm run codex 会继续使用沙盒内最后一次快照，但不会再次读取真实配置。任何同步中新出现且尚未由桥接器管理的同名 setting/provider/auth 都会 fail closed；上次导入的受管字段若被手工修改，同样拒绝继续同步。要从干净状态接入可先重置对应产品沙盒。

导入状态写入产品隔离 state/ccswitch-sync.json，保存受管字段名、模式、时间、Codex provider 标识和 SHA-256 指纹，不保存明文凭据。--status 只显示模式与 12 位指纹。--ccswitch-home PATH 仅用于便携 CC Switch home 和隔离测试。

隔离目录

默认位置：

• macOS/Linux：$XDG_DATA_HOME/cc-unlock-sandbox，未设置时为 ~/.local/share/cc-unlock-sandbox
• Windows：%LOCALAPPDATA%\cc-unlock-sandbox

cc-unlock-sandbox/
├── claude/
│   ├── config/       独立 CLAUDE_CONFIG_DIR 与认证
│   ├── home/         独立 runtime HOME
│   ├── state/
│   └── tmp/
└── codex/
    ├── config/       独立 CODEX_HOME 与认证
    ├── home/         独立 runtime HOME
    ├── state/
    └── tmp/

可用 CC_UNLOCK_SANDBOX_ROOT 或 --sandbox-root 改变位置。启动器拒绝以下危险目标：

• 文件系统根目录
• 用户主目录
• 用户主目录的祖先
• 真实 .claude / .codex 及其子目录
• 通过符号链接逃出沙盒根目录的产品目录

工作区也不能是文件系统根、用户主目录、主目录的祖先或真实配置目录。~/project 这类主目录下的普通项目路径不受影响。

平台边界

macOS

自动加载 macos/backend.js 并使用系统 sandbox-exec：

• 普通文件写入仅允许当前产品沙盒目录和选定工作区；终端运行所需的 /dev 设备 I/O 另行开放
• 当前产品沙盒目录可写
• 选定工作区可写，即使它也是当前仓库
• Claude 的 CLAUDE_CODE_TMPDIR 强制指向产品隔离 tmp/，不会写共享 /tmp/claude-<uid>
• Claude/Codex 仅可对当前继承终端执行 TUI raw-mode 所需的 ioctl
• Codex 额外允许 TUI 所需的 AF_SYSTEM protocol 2 控制套接字和带动态扩展的新建伪终端
• 真实 HOME 下 .claude、.codex、.cc-switch、.agents、.ssh、.gnupg、云和集群凭据目录显式禁止读取
• 网络保持可用，用于认证与模型 API

Linux

自动加载 linux/backend.js。存在 bwrap 时：

• 根文件系统只读
• 当前产品沙盒目录与选定工作区可写
• 真实 HOME 下的已知敏感配置路径使用临时空视图或空文件屏蔽读取
• /tmp 使用临时文件系统

真实 HOME 下的 CLI、CC Switch、SSH、GnuPG、云和集群敏感配置目录不会暴露给子进程。没有 bwrap 或 OS 沙盒预检失败时默认终止，不会自动降级；只有明确理解弱隔离风险并显式传入 --env-only 才只使用配置和环境隔离。

Windows

自动加载 windows/backend.js，隔离：

• CLAUDE_CONFIG_DIR
• CODEX_HOME
• HOME / XDG_*
• USERPROFILE / APPDATA / LOCALAPPDATA
• TMP / TEMP
• 两个产品各自的认证和状态

普通 Windows 进程没有等同 Seatbelt/bubblewrap 的文件系统边界。需要强隔离时使用 Windows Sandbox、Hyper-V VM 或其他一次性虚拟机；--require-os-sandbox 会主动失败，避免误判隔离强度。

管理命令

npx cc-unlock claude:status --workspace /path/to/project
npx cc-unlock codex:status --workspace /path/to/project

npx cc-unlock claude:init --workspace /path/to/project
npx cc-unlock codex:init --workspace /path/to/project

npx cc-unlock claude:refresh --workspace /path/to/project
npx cc-unlock codex:refresh --workspace /path/to/project

npx cc-unlock claude:reset
npx cc-unlock codex:reset

--status 是只读操作，不创建或刷新沙盒，并分别显示目录所有权 owned: yes/no、关键配置完整性 initialized: yes/no 和脱敏 CC Switch 同步状态。

普通运行和 --init-only 会维护 bundle-owned 稳定指令，但 memory 与 rollout 只在缺失时播种，保留后续运行状态。--refresh 不启动真实 CLI，用仓库 bundle 显式恢复 memory/rollout 种子；用户额外创建的 rollout 文件保留。

--reset 只删除对应产品目录，并校验 marker 的完整内容。重置 Claude 不影响 Codex，反之亦然。

对应的跨平台 npm 管理别名为 claude:init、codex:init、claude:refresh、codex:refresh、claude:status、codex:status、claude:reset 和 codex:reset。需要工作区或自定义 sandbox root 时继续在 npm 的 -- 后传入参数：

npm run codex:refresh -- --workspace /path/to/project --sandbox-root /safe/cc-unlock

配置规则

• 默认模式不复制真实认证文件，首次使用需要分别登录；只有显式 --ccswitch-sync 会白名单导入当前中转认证
• 子进程使用独立 HOME 与 XDG_*；Windows 同时重定向 USERPROFILE/APPDATA/LOCALAPPDATA
• 不继承另一产品的 CLAUDE_CONFIG_DIR、CODEX_HOME、binary override、已知 API key/token、云凭据文件指针或 SSH/GPG agent socket
• Claude CLAUDE.md、Codex AGENTS.md 和 skill 属于稳定指令，普通启动会维护其 bundle 版本
• Memory 与 rollout 使用 seed-once 生命周期；普通启动保留已有内容，只有 --refresh 显式恢复仓库种子
• Claude settings.json 仅在首次初始化时创建，用户后续的合法 JSON 修改保留；损坏配置会明确报错而不会被覆盖
• Codex 通过 $CODEX_HOME/AGENTS.md 提供稳定指令，不再配置 model_instructions_file
• Codex config.toml 结构化维护 memories feature、use_memories = true 与 generate_memories = false，其他用户表和键保留
• CC Switch 导入在产品同步锁内执行；Codex config.toml/auth.json 使用短间隔双读校验，观测到切换中的不稳定内容时拒绝导入
• memory_summary.md 使用 v1 schema；rollout 是按需检索候选，不会被启动器全部拼入 prompt
• 工作区不会被创建 CLAUDE.md、AGENTS.md 或 .claude/skills
• 默认设置不启用 bypassPermissions；只有显式 claude:dangerous 快捷指令才向本次进程传入 --dangerously-skip-permissions
• 初始化不会接管已有的非空无 marker 目录，也拒绝受管路径上的符号链接和文件硬链接
• 配置同步使用同目录临时文件、fsync 和原子 rename，避免中断后留下半写文件
• 首次 ownership 初始化和各产品并发同步使用 PID/token 锁串行化，等待 15 秒并自动恢复陈旧锁
• macOS 每次启动使用独占的临时 Seatbelt profile，避免同一产品多开时互相覆盖终端权限；子进程正常返回后自动删除
• Unix 产品/配置目录使用 0700，受管配置文件和 marker 使用 0600

测试

三平台统一入口：

npm test

测试 runner 会自动选择 Bash 或 PowerShell。macOS 先在正式产品 Seatbelt profile 中执行真实 PTY raw-mode 契约，再把其余测试放入无网络外层 Seatbelt；Linux 必须先进入无网络 bubblewrap。缺少所需 OS sandbox 时测试拒绝运行，不会无沙盒降级。随后执行资源编解码与 npm tarball、仅含 dist/ 的独立初始化、后端、上下文生命周期、CC Switch 白名单/切换生命周期、并发同步/原子写入、越界写入、链接逃逸和独立重置测试。安装了 Codex CLI 时，还会通过 debug prompt-input 验证隔离 $CODEX_HOME/AGENTS.md 确实进入 model-visible developer context。

上下文契约只证明文件落盘、feature 配置和 seed 生命周期；Codex runtime contract 证明稳定 AGENTS.md 指令进入 prompt。两者都不声称某条 memory/rollout 已被模型检索。

Windows 测试验证配置与生命周期契约；文件系统 OS 边界仍需在 Windows Sandbox/VM 中验收。直接运行 scripts/tests/context-contract.js 不提供外层 OS 沙盒，因此仓库只把 npm test 作为完整测试入口。

使用范围

cc-unlock 面向 CTF、自建实验室、公开漏洞复现、用户自有软件分析和授权安全测试。使用者需确保目标和操作处于合法授权范围。