# @clipboard-health/clearance 中文文档 规范地址：https://npmcn.com/package/%40clipboard-health/clearance/ 版本：1\.10\.15 npm 元数据更新时间：2026-11-05T04:55:25.800Z 中文译文更新时间：2026-11-10T02:49:09.017Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40clipboard-health/clearance 原文对照：https://npmcn.com/package/%40clipboard-health/clearance/?lang=original 项目主页：https://github.com/ClipboardHealth/core-utils#readme 源码仓库：https://github.com/ClipboardHealth/core-utils ## 关键信息（来自 npm 元数据） - 包体积（解压后）：109 kB，34 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-05-12T19:13:03.386Z - 最新版本发布：2026-11-05T04:55:25.636Z - 近 30 天下载量：3094（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：93（近 12 个月 93 个） ## 中文简介 Localhost HTTP/HTTPS Egress代理服务器,主机名允许上市,外加macOS Safehouse集成用于沙箱代理处理. ## 安装 ```sh npm install @clipboard-health/clearance ``` 也可以使用：`pnpm add @clipboard-health/clearance`、`yarn add @clipboard-health/clearance`、`bun add @clipboard-health/clearance` ## README # 清除 本地的 HTTP/ HTTPS 前置代理, 闸门网络对接 主机名许可列表 。 用于默认的沙盒——编码代理, CI工人, 孤立的建筑阶梯, 在那里你想要一个窒息点 沙盒可以允许,与通往网络的所有其他路线关闭. 代理船与 **零编译意见** 关于允许哪个主机. 提供自己的名单——通过内嵌或指向一个或多个 纯文本文件 。 团队通常将这些文件检查到他们的回放中 每个人都有同样的基线. ## 安装 ```bash npm install -g @clipboard-health/clearance ``` 安装两个二进制 : `clearance` (代理)和 `clearance-ensure` (独家守护进程发射器). ## 原始代理用户 ```bash CLEARANCE_ALLOW_HOSTS=api.example.com clearance ``` 然后点出工具 `http://127.0.0.1:19999` 与 `HTTP_PROXY` 财务报告和审定财务报表 `HTTPS_PROXY`。 。 。 . 默认代理监听 `127.0.0.1:19999`,允许目的端口 `443`,并屏蔽私有,回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回, 以及DNS分辨率后的其他非公共IP范围. 如果没有 `CLEARANCE_ALLOW_HOSTS` 也没有 `CLEARANCE_ALLOW_HOSTS_FILES` 实值 设置, 代理机拒绝启动 . ### 允许主机文件 文件是主机的纯文本列表,每行一个. 空行被忽略, `#` 引入一个对端的注释, 并跟踪点/ 通配符 前缀( e)`*.example.com`) 实现正常化. ```text # AI agents api.openai.com api.anthropic.com # Source code github.com api.github.com *.githubusercontent.com ``` 指向一个或多个文件通过 `CLEARANCE_ALLOW_HOSTS_FILES` 使用您的 平台的 PATH 分隔器 - `:` 关于macOS/Linux, `;` 在视窗上。 价值 从 `CLEARANCE_ALLOW_HOSTS`,所有引用的文件,以及任何重复 被装饰和去除. ```bash CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts:$HOME/.config/clearance/personal-hosts" \ clearance ``` 这就是团队共享基线的方式:检查a `team-allow-hosts` 文件输入 您的还本付息, 并让个人通过同一方式将个人文件上层 (原始内容存档于2018-10-21). env var. ### 配置参考 | 变量 | 默认 | 页:1 | | --- | --- | --- | | `CLEARANCE_ALLOW_HOSTS` | _(未设定)_ | 逗号 - 或白空分隔的精确主机和通配符后缀. | | `CLEARANCE_ALLOW_HOSTS_FILES` | _(未设定)_ | 路径限制( PATH )`:` macOS/Linux, (英语), `;` Windows)到纯文本主机文件(`#` 评论,空白行). | | `CLEARANCE_ALLOW_PORTS` | `443` | 逗号- 或白空分隔的 TCP 端口 . | | `CLEARANCE_LISTEN_HOST` | `127.0.0.1` | 宾德主机. | | `CLEARANCE_PORT` | `19999` | 宾德口. | | `CLEARANCE_DNS_TTL_MS` | `60000` | 在进程中的 DNS 缓存 TTL. | | `CLEARANCE_IDLE_TIMEOUT_MS` | `120000` | 空闲超时. | | `CLEARANCE_MAX_SOCKETS` | `1024` | 入站连接盖和出站HTTP代理盖. | | `CLEARANCE_ALLOW_PRIVATE_IPS` | _(未设定)_ | 设定为 `1` 以禁用私有/非公有IP屏蔽进行本地测试. | ## 管理代理 : `clearance-ensure` `clearance-ensure` 检查 `127.0.0.1:19999`; 如果没有代理正在监听 产出一个离子 使用相同的阴道 vars 等待它结合。 日志 住在这里 `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.log`, (中文(简体) ), 时长 `…/clearance.pid`。 。 。 . ```bash CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts" clearance-ensure ``` ### 生命周期子命令 `clearance-ensure` 接受可选的子命令。 没有,它默认为 `start` (上面的同能发射). 所有子命令都会发现运行 代理通过 pidfile . | 命令 | 行为 | | --- | --- | | `clearance-ensure` | 默认 `start`: 如果已经听不到, 启动代理 . | | `clearance-ensure start` | 和赤裸裸的引用一样. | | `clearance-ensure stop` | 信号pidfile进程终止,等待端口关闭,并去除pidfile. | | `clearance-ensure restart` | `stop` 现有代理(如果有),然后 `start` 一个新鲜的。 用此来取取已编辑的主机文件 . | | `clearance-ensure status` | 报告代理机是否在监听, 以及它的pid 。 不运行时退出非零. | 要获取已编辑的允许- 主机文件, 请在一步内重新启动 : ```bash CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts" clearance-ensure restart ``` ## 安全屋一体化(macOS) [安全之家](https://agent-safehouse.dev/) 使用 macOS 沙盒配置文件,所以 本节仅供macOS主机使用. 安全屋允许网络访问 默认代理兼容性. 要通过这个代理来强迫一个包裹的代理, 请在外边运行代理 安全屋,然后附加一个安全屋的简介,拒绝直接远程 离开时出走 `localhost` 打开 `http://127.0.0.1:19999`。 。 。 . 货包船a `safehouse-clearance` 包装外加匹配 `clearance.env` 财务报告和审定财务报表 `clearance-only.sb` 简介。 经过全球安装后, 包装者住在 `$(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance`。 。 。 . 它确保代理运行,然后 `exec`安全屋 与内存文件 沙盒侧面图 没错 **没有** 解析或重写 参数——您通过的任何文件都是逐字传送的,所以设置任何安全屋 代理命令前的旗帜 : ```bash SAFEHOUSE_CLEARANCE="$(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance" "$SAFEHOUSE_CLEARANCE" \ --enable=cloud-credentials --env-pass=AWS_PROFILE,AWS_REGION \ -- codex --dangerously-bypass-approvals-and-sandbox ``` 用于日常代理, 请配置您的允许主机文件并添加 shell 化名 : ```bash SAFEHOUSE="$(npm root -g)/@clipboard-health/clearance/safehouse" export CLEARANCE_ALLOW_HOSTS_FILES="$HOME/code//clearance-allow-hosts:$HOME/.config/clearance/personal-allow-hosts" alias codex-proxy="$SAFEHOUSE/safehouse-clearance codex --dangerously-bypass-approvals-and-sandbox" alias claude-proxy="$SAFEHOUSE/safehouse-claude-proxy" ``` `safehouse-claude-proxy` 克劳德通过安全屋 `--permission-mode auto`。当从 cmux 终端发射时,它保留 cmux 的 Claude shim 通过转发 cmux 会话环境和给予 只读访问 cmux app/ socket 状态并生成了 Codex 钩子. 这个 集成还允许 cmux 现有的 Sentry 缓存写入访问, 这样诊断 无法损坏 JSON 输出 。 它指向真正的克洛德二进制 他不会自相残杀. 集成不会给 cmux 控制套接字设置连接 : `resolveSafehouseCmuxIntegration().socketProfile` 总是 `undefined`。 。 。 . 这个套接字可以在Safehouse外创建终端和运行命令,所以授予 使用状态钩子也会让沙盒代码绕过其限制. 需要插座的钩子仍被封锁 恢复他们需要 仅接受指定对象所需的钩线操作的主机侧中继 工作空间; 消费者不得附加一个授予控制套接字的配置文件. Cmux环境通过是一个经过审查的明确许可列表. 如果一个cmux 更新后新增 `CMUX_*` claude包装合同的变量, `safehouse-claude-proxy` 打印未审查变量的警告 而不是自动通过每个 `CMUX_*` 值通过沙盒. 对于 AWS SSO 的工作,先登录主机,再分层安全屋云 通过包装的证书标记 : ```bash aws sso login --profile AWS_PROFILE= "$SAFEHOUSE/safehouse-clearance" \ --enable=cloud-credentials --env-pass=AWS_PROFILE,AWS_REGION,AWS_SDK_LOAD_CONFIG,AWS_CONFIG_FILE,AWS_SHARED_CREDENTIALS_FILE,AWS_CA_BUNDLE \ -- codex --dangerously-bypass-approvals-and-sandbox ``` 确保您的允许主机文件包含您需要的 AWS 端点 (通常为: `*.amazonaws.com`, (中文(简体) ), `*.api.aws`, (中文(简体) ), `*.awsapps.com`, (中文(简体) ), `*.ecr.aws`) (中文(简体) ). ### 手动设置 如果你宁愿不依赖捆绑的资产, 你可以建造同样的 手设. ```bash mkdir -p ~/.config/agent-safehouse ``` ```bash cat > ~/.config/agent-safehouse/clearance-only.sb <<'SB' ;; Force remote network egress through the local clearance while keeping ;; localhost available for local-only agent workflows. (deny network-outbound (remote ip "*:*") (remote tcp "*:*") (remote udp "*:*")) (allow network-outbound (remote ip "localhost:*") (remote tcp "localhost:*") (remote udp "localhost:*")) SB ``` ```bash cat > ~/.config/agent-safehouse/clearance.env <<'ENV' HTTP_PROXY="http://127.0.0.1:19999" HTTPS_PROXY="http://127.0.0.1:19999" ALL_PROXY="http://127.0.0.1:19999" NO_PROXY="localhost,127.0.0.1,::1" http_proxy="${HTTP_PROXY}" https_proxy="${HTTPS_PROXY}" all_proxy="${ALL_PROXY}" no_proxy="${NO_PROXY}" ENV ``` 然后用Safehouse管理包裹的指令: ```bash safehouse \ --env="$HOME/.config/agent-safehouse/clearance.env" \ --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \ -- ``` 不要仅仅为了代理而通过 API- key 环境变量 。 隐藏文件 仅提供代理服务器设置; 代理机应继续使用正常 auth/配置仓库. 快速检查 : ```bash # Should use the proxy and usually return 401 without auth. safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \ --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \ -- curl -I https://api.openai.com/v1/models # Should fail because this bypasses the proxy and tries direct egress. safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \ --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \ -- curl --noproxy '*' -I https://api.openai.com/v1/models # Should be denied by the proxy unless example.com is in your allow-host list. safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \ --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \ -- curl -I https://example.com ``` ## 清关打包 对于在软件包本身上工作的开发者,源代码生活在 [`ClipboardHealth/core-utils`](https://github.com/ClipboardHealth/core-utils)之后 `npm install` 在重播中,通过一个 `runCli` 用于检测未编译 JS 和重执行节点的助手 `--conditions @clipboard-health/source`,因此代理从 TypeScript 源头直接运行——没有构建步骤: ```bash cd ~/dev/c/core-utils CLEARANCE_ALLOW_HOSTS=api.example.com node ./packages/clearance/bin/run.js ``` 需要节点 \\ 24.3(本国) `.ts` 默认情况下已启用类型去除). ## 常见问题 ### @clipboard-health/clearance 是什么？ Localhost HTTP/HTTPS Egress代理服务器,主机名允许上市,外加macOS Safehouse集成用于沙箱代理处理\. ### 如何安装 @clipboard-health/clearance？ 在项目目录运行 npm install @clipboard-health/clearance，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 clearance、clearance-ensure，可以用 npx clearance 直接运行。 ### @clipboard-health/clearance 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @clipboard-health/clearance 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @clipboard-health/clearance 可以商用吗？ @clipboard-health/clearance 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @clipboard-health/clearance 的下载量有多少？ 根据 npm 官方下载统计，@clipboard-health/clearance 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,094 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @clipboard-health/clearance 还在维护吗？ 最新版本 1\.10\.15 发布于 2026/11/05（4 天前）；至今共发布 93 个版本，其中过去 12 个月发布了 93 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。