尧图网站建设 
Headroom 持久化安装实战用 headroom install 把 8787 端口常驻代理变成可管理的本地运行时【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom本篇指南基于 Headroom 仓库的 persistent-installs 文档展开讲清楚headroom install子系统的三大持久化预设persistent-service / persistent-task / persistent-docker、--scope与--providers的完整参数语义、部署清单manifest的存储位置与结构以及headroom wrap如何自动复用或恢复常驻部署。读完并对照仓库源码后你将掌握三种常驻运行时的选型依据、每个 CLI 命令的底层行为以及 manifest 原子写入与损坏恢复等工程细节。从临时代理到常驻运行时persistent install 要解决什么问题此前运行 Headroom 只有两种方式临时起一个headroom proxy进程退出即消失或headroom wrap ...包一层工具会话代理生命周期与会话绑定。这两种方式都要求代理在需要时恰好活着。Persistent Installs 让 Headroom 以持久本地运行时的形式安装到机器上受支持的编码工具Claude Code、Codex、Copilot 等持续访问http://127.0.0.1:8787上一直开着的代理而headroom wrap ...会复用或恢复这个部署而不是再启一个第二套临时代理。文档明确建议当你希望工具长期对接一个 always-on 代理时使用 Python 原生的headroom installCLI。整个子系统位于 headroom/install/ 包内从源码结构看各模块职责划分如下模块职责models.py预设、运行时、supervisor、作用域等枚举与DeploymentManifest数据类planner.py目标探测、参数解析、生成规范化 manifeststate.pymanifest 的原子写入、加载与删除paths.py部署状态目录、runner 脚本路径、各工具的配置文件路径supervisors.pysystemd / launchd / 计划任务等 supervisor 的渲染与启停providers.py对工具配置的可逆修改mutation与应用/回滚runtime.py前台/后台运行、端口探测、健康等待、Docker 启动health.pyreadyz/health端点探测对应的回归测试位于 tests/test_install/覆盖 planner、state、supervisors、runtime、health、providers、native installers 等每个模块如 test_planner.py、test_supervisors.py。运行时矩阵先选对模式再执行命令原文档给出的运行时矩阵是选型的核心依据完整继承如下ModeWhat stays runningPrimary entrypointPersistent ServiceNative background serviceheadroom install apply --preset persistent-servicePersistent TaskScheduled watchdog on-demand runnerheadroom install apply --preset persistent-taskPersistent DockerRestartable Docker containerheadroom install apply --preset persistent-dockerOn-Demand CLI (Python)Nothing after command exitsheadroom proxyOn-Demand CLI (Docker)Nothing after container exitsDocker-native wrapper / compose CLIWrapped (Python)Proxy lasts for wrapped sessionheadroom wrap ...Wrapped (Docker)Containerized proxy host tool sessionDocker-native wrapper三种持久化预设的区别本质在于谁来保证代理活着persistent-service交给操作系统原生服务管理器Linux 上是 systemd unitmacOS 上是 launchd LaunchAgentpersistent-task用定时任务cron / 计划任务跑一个 watchdog周期性探测并按需拉起适合不允许注册系统服务的场景persistent-docker则把存活责任完全交给 Docker 的 restart policy不引入额外 OS 层监督。快速上手三种预设的最短命令本机持久服务headroom install apply --preset persistent-service --providers auto headroom install status这条命令在当前机器上安装一个后台服务应用持久化工具接线即把代理端点写进各工具配置并保证8787端口上的代理持续健康。从源码看apply的完整链路是cli/install.py 中的install命令组接收参数 → planner.py 的build_manifest()生成DeploymentManifest→ state.py 的save_manifest()落盘 → supervisors.py 的install_supervisor()注册 supervisor → runtime.py 的wait_ready()等待readyz通过。一个值得注意的平台细节在 Windows 上build_manifest()会把persistent-service静默降级为persistent-task见 planner.py 的注释——因为 Python runner 是普通控制台进程无法实现 Windows SCM 协议协议sc.exe create注册的服务永远无法启动SCM error 1053而任务计划程序既能开机自启又能周期健康恢复因此成为 Windows 上的有效预设对应 issue #2552。持久看门狗任务headroom install apply --preset persistent-task --providers manual --target claude --target codex这条命令安装的是定时恢复路径而非传统常驻服务。从 supervisors.py 看apply会为每个 profile 渲染两个脚本run-headroom.sh前台 runner执行headroom install agent run --profile profileensure-headroom.shwatchdog 脚本执行headroom install agent ensure --profile profile由 cron/计划任务周期性调用发现代理挂了就拉起。Windows 上对应的是run-headroom.ps1/run-headroom.cmd与ensure-headroom.ps1/ensure-headroom.cmd见 paths.py。持久 Dockerheadroom install apply --preset persistent-docker --scope user --providers auto这条命令让 Docker 的 restart policy 取代 OS supervisor。源码中有个针对该预设的实现细节开启--memory时Python 运行时会显式传--memory-db-path 宿主路径但Docker 运行时会被刻意省略该参数见 planner.py 注释——因为容器内 HOME 是/tmp/headroom-home宿主的~/.headroom只是挂载进来直接传宿主绝对路径会导致 SQLite 打不开、/readyz恒 503、部署超时回滚issue #2803省略后代理在容器工作目录下解析 DB恰好落在同一个绑定挂载文件上。另外如果你使用的是Docker 原生宿主 wrapper而非 Python 安装也可以直接从已安装的 wrapper 上对persistent-docker预设执行headroom install apply|status|start|stop|restart|remove。但注意边界service/task 安装以及 provider/user/system 的变更流程仍属于 Python 原生 CLI 的职责。命令面六个生命周期子命令headroom install apply headroom install status headroom install start headroom install stop headroom install restart headroom install remove文档说明apply会创建或更新一个具名部署档案profile把清单存到~/.headroom/deploy/profile/manifest.json应用可逆的配置变更然后启动所选运行时。源码对这条命令的补充细节profile 命名有校验paths.py 中validate_profile_name()要求 profile 只含[A-Za-z0-9._-]且不允许./..防止路径穿越目录布局每个 profile 一个目录除manifest.json外还放runner.log运行日志、runner.pid前台进程 pid、各平台 runner/watchdog 脚本见 paths.py显式--profile不容错cli/install.py 中如果命令行显式传了--profile但该 profile 不存在命令会原样报错而不是悄悄转向其他已安装 profile——stop/restart/remove这类破坏性命令绝不允许误伤别的部署。只有--profile缺省时才走恢复回退读HEADROOM_DEPLOYMENT_PROFILE环境变量或唯一的已安装 profileremove的行为先revert_mutations()回滚对工具配置的修改再remove_supervisor()注销 supervisor最后delete_manifest()删除整个 profile 目录见 state.py 的shutil.rmtree。Presets 与 Runtime kindsPresetspersistent-service- 原生服务监督器persistent-task- 定时看门狗 / 恢复监督器persistent-docker- Docker restart policy无额外 OS 监督器这与 models.py 中的枚举一一对应InstallPreset、SupervisorKindservice/task/none。预设到 supervisor 的映射逻辑在build_manifest()里service 预设产生SupervisorKind.SERVICEtask 预设产生TASKDocker 预设产生NONE由容器引擎负责重启。supervisor 的实际产物从 supervisors.py 可见Linuxpersistent-service渲染 systemd unitscopeuser时放在~/.config/systemd/user/headroom-profile.servicescopesystem时放在/etc/systemd/system/unit 内容为Restarton-failure、RestartSec5ExecStart指向渲染出的run-headroom.shmacOS渲染 launchd plist 并通过launchctl bootstrap加载。源码还处理了一个真实的竞态launchctl bootout之后立刻bootstrap同一 label 可能在数秒内返回 EIO因此_bootstrap_with_retry()会重试最多 30 次每次 0.5 秒约 15 秒以扛过 launchd 的释放窗口见 supervisors.py。Runtime kinds--runtime python直接运行headroom proxy--runtime docker在 Docker 内运行 Headroom但部署本身仍由本机管理对persistent-docker预设runtime 永远是 Docker。DeploymentManifest中 Docker 相关默认值可在 models.py 看到镜像ghcr.io/headroomlabs-ai/headroom:latest、容器名headroom-profile、健康检查 URLhttp://127.0.0.1:8787/readyz。配置作用域Scope改到哪里、改多少ScopeWhat changesproviderTool-specific config surfaces where Headroom can make a precise reversible edituserUser-level shell or environment surfacessystemMachine-wide shell or environment surfaces从 paths.py 可以看到各 scope 实际落笔的文件user~/.bashrc、~/.zshrc、~/.profile可写入持久环境块的文件列表systemLinux 上是/etc/profile.d/headroom.shmacOS 上是/etc/profile、/etc/zprofile、/etc/bashrcprovider直接编辑各工具自己的配置文件。当前 Provider scope 支持的直接适配器文档强调 provider scope 是有意保守的当前的直接适配器为Claude Code -~/.claude/settings.json的envCodex -~/.codex/config.toml中的托管块managed blockOpenClaw - 复用既有的wrap openclaw/unwrap openclaw流程对于 Copilot、Aider、Cursor 以及更宽泛的 env 驱动配置建议用--scope user或--scope system。与文档的一个差异值得注意源码里PROVIDER_SCOPE_TARGETS实际包含claude、codex、openclaw、opencode四个目标见 planner.py且 paths.py 为 OpenCode 提供了配置路径解析优先OPENCODE_CONFIG环境变量其次~/.config/opencode/opencode.jsonc或opencode.json。也就是说 OpenCode 已具备 provider 级直接适配能力只是 Wiki 文档尚未同步更新这一条。apply对 provider scope 下不支持的 target 会明确报错列出例如Provider scope supports only claude, codex, openclaw, and opencode见 planner.py。Provider 选择auto / all / manualOptionMeaning--providers autoDetect supported tools on the host and configure the best available defaults--providers allConfigure all known targets--providers manual --target ...Configure only the named toolsheadroom install apply --providers auto headroom install apply --providers all --scope user headroom install apply --providers manual --target claude --target copilot从 models.py 的ToolTarget枚举看当前支持的全部 target 为claude、copilot、codex、aider、cursor、grok_build、grok、openclaw、opencode。auto模式的探测机制在 planner.py 的detect_targets()对每个 target 用shutil.which()查可执行文件是否在 PATH 上若一个都没探测到resolve_targets()会回退到默认集合claude codexprovider scope 下再额外去掉 copilot见 planner.py。生成 manifest 时每个 target 会得到一份专属环境变量build_install_target_envs()代理自身的基础环境则固定写入HEADROOM_PORT、HEADROOM_HOST127.0.0.1、HEADROOM_MODE、HEADROOM_BACKEND、显式的HEADROOM_TELEMETRYon|off见 planner.py。另有两条自动派生规则若目标只含 Grok / Grok Build 且没有共享该代理的 OpenAI 系工具自动设置OPENAI_TARGET_API_URL指向 xAI 端点从 providers/grok/runtime.py 引入DEFAULT_API_URL--env显式传入的变量最后应用可覆盖上述所有自动派生默认值。健康端点与 wrap 的复用/恢复行为持久化部署发布与临时代理运行完全相同的readyz和health端点。当代理经由 install 子系统启动时/health额外暴露部署元数据{ deployment: { profile: default, preset: persistent-service, runtime: python, supervisor: service, scope: user } }这些字段恰好对应DeploymentManifest的同名属性profile/preset/runtime_kind/supervisor_kind/scope说明/health是把 manifest 中相应字段原样透出方便运维端判断这个 8787 端口是谁在管。Python 原生的headroom wrap ...流程会先检查请求端口上是否存在匹配的持久化部署再决定是否新起临时代理如果已安装的部署存在但处于停止或不健康状态它会先尝试恢复它。探测逻辑基于 health.py 的probe_ready()/probe_json()等待逻辑在 runtime.py 的wait_ready()对/readyz轮询直到 200。需要明确的边界Docker 原生宿主 wrapper 尚不会自动复用或恢复持久化 profile——除非显式--no-proxy否则它总是启动一个全新的代理容器。Docker 原生路径的关系与 compose 管理Docker 原生宿主 wrapper 与 Python install CLI 解决的是运行时故事的不同层Docker-Native Install - 容器化的按需 CLI、宿主工具的 wrap 流程以及 Docker 原生的persistent-docker生命周期命令headroom install ...- 完整的持久 service / task / Docker 生命周期管理包含 provider/user/system 变更。对于不依赖 Python的持久 Docker 工作流使用 docker/docker-compose.native.yml 中 compose 管理的代理路径export HEADROOM_HOST_HOME$HOME export HEADROOM_WORKSPACE$PWD docker compose -f docker/docker-compose.native.yml up -d proxy这样可以保持localhost:8787稳定并在容器退出时自动重启代理。注意HEADROOM_WORKSPACEcompose 文件使用的宿主侧 bind-mount 源目录与HEADROOM_WORKSPACE_DIR容器内 Headroom 状态根的规范变量不是同一个变量。两者都保留compose 文件会自动设置后者。完整的 bucket 模型见 Filesystem Contract。清单持久化的可靠性细节manifest.json是整套安装系统的事实来源state.py 对它做了三层保护原子写入save_manifest()经由_atomic_write_text()先把 payload 写入同目录临时文件mkstempflushfsync后再os.replace()原子改名。即使写入中途被 SIGKILL、OOM 或断电打断磁盘上也只会留下旧文件或完整新文件绝不出现被截断的 manifest只读文件系统则降级为告警而非崩溃。损坏清单的优雅失败load_manifest()对解析失败部分写入、手改、schema 漂移抛出类型化的ManifestError而不是裸 traceback——因为所有 install 生命周期命令以及自动执行的init hook ensure路由都要经过这里CLI 层会把它转成可读的报错见 cli/install.py。旧镜像仓库自动迁移旧 manifest 若仍钉在已停止更新的ghcr.io/chopratejas/headroom镜像上加载时会被自动重写到组织仓库ghcr.io/headroomlabs-ai/headroom并保留 tagissue #2426见 state.py。与文档配套的其他资源CLI Referenceheadroom全部命令参考Docker-Native InstallDocker 原生安装与 wrapper 详解Proxy Server代理服务端点、readyz/health行为macOS LaunchAgentmacOS 上 launchd 部署的细节Filesystem Contract容器内外状态目录bucket的完整模型docker/docker-compose.native.yml无 Python 持久 Docker 的 compose 定义tests/test_install/install 子系统的完整回归测试集【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Headroom 持久化安装实战：用 headroom install 把 8787 端口常驻代理变成可管理的本地运行时
Headroom 持久化安装实战用 headroom install 把 8787 端口常驻代理变成可管理的本地运行时【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom本篇指南基于 Headroom 仓库的 persistent-installs 文档展开讲清楚headroom install子系统的三大持久化预设persistent-service / persistent-task / persistent-docker、--scope与--providers的完整参数语义、部署清单manifest的存储位置与结构以及headroom wrap如何自动复用或恢复常驻部署。读完并对照仓库源码后你将掌握三种常驻运行时的选型依据、每个 CLI 命令的底层行为以及 manifest 原子写入与损坏恢复等工程细节。从临时代理到常驻运行时persistent install 要解决什么问题此前运行 Headroom 只有两种方式临时起一个headroom proxy进程退出即消失或headroom wrap ...包一层工具会话代理生命周期与会话绑定。这两种方式都要求代理在需要时恰好活着。Persistent Installs 让 Headroom 以持久本地运行时的形式安装到机器上受支持的编码工具Claude Code、Codex、Copilot 等持续访问http://127.0.0.1:8787上一直开着的代理而headroom wrap ...会复用或恢复这个部署而不是再启一个第二套临时代理。文档明确建议当你希望工具长期对接一个 always-on 代理时使用 Python 原生的headroom installCLI。整个子系统位于 headroom/install/ 包内从源码结构看各模块职责划分如下模块职责models.py预设、运行时、supervisor、作用域等枚举与DeploymentManifest数据类planner.py目标探测、参数解析、生成规范化 manifeststate.pymanifest 的原子写入、加载与删除paths.py部署状态目录、runner 脚本路径、各工具的配置文件路径supervisors.pysystemd / launchd / 计划任务等 supervisor 的渲染与启停providers.py对工具配置的可逆修改mutation与应用/回滚runtime.py前台/后台运行、端口探测、健康等待、Docker 启动health.pyreadyz/health端点探测对应的回归测试位于 tests/test_install/覆盖 planner、state、supervisors、runtime、health、providers、native installers 等每个模块如 test_planner.py、test_supervisors.py。运行时矩阵先选对模式再执行命令原文档给出的运行时矩阵是选型的核心依据完整继承如下ModeWhat stays runningPrimary entrypointPersistent ServiceNative background serviceheadroom install apply --preset persistent-servicePersistent TaskScheduled watchdog on-demand runnerheadroom install apply --preset persistent-taskPersistent DockerRestartable Docker containerheadroom install apply --preset persistent-dockerOn-Demand CLI (Python)Nothing after command exitsheadroom proxyOn-Demand CLI (Docker)Nothing after container exitsDocker-native wrapper / compose CLIWrapped (Python)Proxy lasts for wrapped sessionheadroom wrap ...Wrapped (Docker)Containerized proxy host tool sessionDocker-native wrapper三种持久化预设的区别本质在于谁来保证代理活着persistent-service交给操作系统原生服务管理器Linux 上是 systemd unitmacOS 上是 launchd LaunchAgentpersistent-task用定时任务cron / 计划任务跑一个 watchdog周期性探测并按需拉起适合不允许注册系统服务的场景persistent-docker则把存活责任完全交给 Docker 的 restart policy不引入额外 OS 层监督。快速上手三种预设的最短命令本机持久服务headroom install apply --preset persistent-service --providers auto headroom install status这条命令在当前机器上安装一个后台服务应用持久化工具接线即把代理端点写进各工具配置并保证8787端口上的代理持续健康。从源码看apply的完整链路是cli/install.py 中的install命令组接收参数 → planner.py 的build_manifest()生成DeploymentManifest→ state.py 的save_manifest()落盘 → supervisors.py 的install_supervisor()注册 supervisor → runtime.py 的wait_ready()等待readyz通过。一个值得注意的平台细节在 Windows 上build_manifest()会把persistent-service静默降级为persistent-task见 planner.py 的注释——因为 Python runner 是普通控制台进程无法实现 Windows SCM 协议协议sc.exe create注册的服务永远无法启动SCM error 1053而任务计划程序既能开机自启又能周期健康恢复因此成为 Windows 上的有效预设对应 issue #2552。持久看门狗任务headroom install apply --preset persistent-task --providers manual --target claude --target codex这条命令安装的是定时恢复路径而非传统常驻服务。从 supervisors.py 看apply会为每个 profile 渲染两个脚本run-headroom.sh前台 runner执行headroom install agent run --profile profileensure-headroom.shwatchdog 脚本执行headroom install agent ensure --profile profile由 cron/计划任务周期性调用发现代理挂了就拉起。Windows 上对应的是run-headroom.ps1/run-headroom.cmd与ensure-headroom.ps1/ensure-headroom.cmd见 paths.py。持久 Dockerheadroom install apply --preset persistent-docker --scope user --providers auto这条命令让 Docker 的 restart policy 取代 OS supervisor。源码中有个针对该预设的实现细节开启--memory时Python 运行时会显式传--memory-db-path 宿主路径但Docker 运行时会被刻意省略该参数见 planner.py 注释——因为容器内 HOME 是/tmp/headroom-home宿主的~/.headroom只是挂载进来直接传宿主绝对路径会导致 SQLite 打不开、/readyz恒 503、部署超时回滚issue #2803省略后代理在容器工作目录下解析 DB恰好落在同一个绑定挂载文件上。另外如果你使用的是Docker 原生宿主 wrapper而非 Python 安装也可以直接从已安装的 wrapper 上对persistent-docker预设执行headroom install apply|status|start|stop|restart|remove。但注意边界service/task 安装以及 provider/user/system 的变更流程仍属于 Python 原生 CLI 的职责。命令面六个生命周期子命令headroom install apply headroom install status headroom install start headroom install stop headroom install restart headroom install remove文档说明apply会创建或更新一个具名部署档案profile把清单存到~/.headroom/deploy/profile/manifest.json应用可逆的配置变更然后启动所选运行时。源码对这条命令的补充细节profile 命名有校验paths.py 中validate_profile_name()要求 profile 只含[A-Za-z0-9._-]且不允许./..防止路径穿越目录布局每个 profile 一个目录除manifest.json外还放runner.log运行日志、runner.pid前台进程 pid、各平台 runner/watchdog 脚本见 paths.py显式--profile不容错cli/install.py 中如果命令行显式传了--profile但该 profile 不存在命令会原样报错而不是悄悄转向其他已安装 profile——stop/restart/remove这类破坏性命令绝不允许误伤别的部署。只有--profile缺省时才走恢复回退读HEADROOM_DEPLOYMENT_PROFILE环境变量或唯一的已安装 profileremove的行为先revert_mutations()回滚对工具配置的修改再remove_supervisor()注销 supervisor最后delete_manifest()删除整个 profile 目录见 state.py 的shutil.rmtree。Presets 与 Runtime kindsPresetspersistent-service- 原生服务监督器persistent-task- 定时看门狗 / 恢复监督器persistent-docker- Docker restart policy无额外 OS 监督器这与 models.py 中的枚举一一对应InstallPreset、SupervisorKindservice/task/none。预设到 supervisor 的映射逻辑在build_manifest()里service 预设产生SupervisorKind.SERVICEtask 预设产生TASKDocker 预设产生NONE由容器引擎负责重启。supervisor 的实际产物从 supervisors.py 可见Linuxpersistent-service渲染 systemd unitscopeuser时放在~/.config/systemd/user/headroom-profile.servicescopesystem时放在/etc/systemd/system/unit 内容为Restarton-failure、RestartSec5ExecStart指向渲染出的run-headroom.shmacOS渲染 launchd plist 并通过launchctl bootstrap加载。源码还处理了一个真实的竞态launchctl bootout之后立刻bootstrap同一 label 可能在数秒内返回 EIO因此_bootstrap_with_retry()会重试最多 30 次每次 0.5 秒约 15 秒以扛过 launchd 的释放窗口见 supervisors.py。Runtime kinds--runtime python直接运行headroom proxy--runtime docker在 Docker 内运行 Headroom但部署本身仍由本机管理对persistent-docker预设runtime 永远是 Docker。DeploymentManifest中 Docker 相关默认值可在 models.py 看到镜像ghcr.io/headroomlabs-ai/headroom:latest、容器名headroom-profile、健康检查 URLhttp://127.0.0.1:8787/readyz。配置作用域Scope改到哪里、改多少ScopeWhat changesproviderTool-specific config surfaces where Headroom can make a precise reversible edituserUser-level shell or environment surfacessystemMachine-wide shell or environment surfaces从 paths.py 可以看到各 scope 实际落笔的文件user~/.bashrc、~/.zshrc、~/.profile可写入持久环境块的文件列表systemLinux 上是/etc/profile.d/headroom.shmacOS 上是/etc/profile、/etc/zprofile、/etc/bashrcprovider直接编辑各工具自己的配置文件。当前 Provider scope 支持的直接适配器文档强调 provider scope 是有意保守的当前的直接适配器为Claude Code -~/.claude/settings.json的envCodex -~/.codex/config.toml中的托管块managed blockOpenClaw - 复用既有的wrap openclaw/unwrap openclaw流程对于 Copilot、Aider、Cursor 以及更宽泛的 env 驱动配置建议用--scope user或--scope system。与文档的一个差异值得注意源码里PROVIDER_SCOPE_TARGETS实际包含claude、codex、openclaw、opencode四个目标见 planner.py且 paths.py 为 OpenCode 提供了配置路径解析优先OPENCODE_CONFIG环境变量其次~/.config/opencode/opencode.jsonc或opencode.json。也就是说 OpenCode 已具备 provider 级直接适配能力只是 Wiki 文档尚未同步更新这一条。apply对 provider scope 下不支持的 target 会明确报错列出例如Provider scope supports only claude, codex, openclaw, and opencode见 planner.py。Provider 选择auto / all / manualOptionMeaning--providers autoDetect supported tools on the host and configure the best available defaults--providers allConfigure all known targets--providers manual --target ...Configure only the named toolsheadroom install apply --providers auto headroom install apply --providers all --scope user headroom install apply --providers manual --target claude --target copilot从 models.py 的ToolTarget枚举看当前支持的全部 target 为claude、copilot、codex、aider、cursor、grok_build、grok、openclaw、opencode。auto模式的探测机制在 planner.py 的detect_targets()对每个 target 用shutil.which()查可执行文件是否在 PATH 上若一个都没探测到resolve_targets()会回退到默认集合claude codexprovider scope 下再额外去掉 copilot见 planner.py。生成 manifest 时每个 target 会得到一份专属环境变量build_install_target_envs()代理自身的基础环境则固定写入HEADROOM_PORT、HEADROOM_HOST127.0.0.1、HEADROOM_MODE、HEADROOM_BACKEND、显式的HEADROOM_TELEMETRYon|off见 planner.py。另有两条自动派生规则若目标只含 Grok / Grok Build 且没有共享该代理的 OpenAI 系工具自动设置OPENAI_TARGET_API_URL指向 xAI 端点从 providers/grok/runtime.py 引入DEFAULT_API_URL--env显式传入的变量最后应用可覆盖上述所有自动派生默认值。健康端点与 wrap 的复用/恢复行为持久化部署发布与临时代理运行完全相同的readyz和health端点。当代理经由 install 子系统启动时/health额外暴露部署元数据{ deployment: { profile: default, preset: persistent-service, runtime: python, supervisor: service, scope: user } }这些字段恰好对应DeploymentManifest的同名属性profile/preset/runtime_kind/supervisor_kind/scope说明/health是把 manifest 中相应字段原样透出方便运维端判断这个 8787 端口是谁在管。Python 原生的headroom wrap ...流程会先检查请求端口上是否存在匹配的持久化部署再决定是否新起临时代理如果已安装的部署存在但处于停止或不健康状态它会先尝试恢复它。探测逻辑基于 health.py 的probe_ready()/probe_json()等待逻辑在 runtime.py 的wait_ready()对/readyz轮询直到 200。需要明确的边界Docker 原生宿主 wrapper 尚不会自动复用或恢复持久化 profile——除非显式--no-proxy否则它总是启动一个全新的代理容器。Docker 原生路径的关系与 compose 管理Docker 原生宿主 wrapper 与 Python install CLI 解决的是运行时故事的不同层Docker-Native Install - 容器化的按需 CLI、宿主工具的 wrap 流程以及 Docker 原生的persistent-docker生命周期命令headroom install ...- 完整的持久 service / task / Docker 生命周期管理包含 provider/user/system 变更。对于不依赖 Python的持久 Docker 工作流使用 docker/docker-compose.native.yml 中 compose 管理的代理路径export HEADROOM_HOST_HOME$HOME export HEADROOM_WORKSPACE$PWD docker compose -f docker/docker-compose.native.yml up -d proxy这样可以保持localhost:8787稳定并在容器退出时自动重启代理。注意HEADROOM_WORKSPACEcompose 文件使用的宿主侧 bind-mount 源目录与HEADROOM_WORKSPACE_DIR容器内 Headroom 状态根的规范变量不是同一个变量。两者都保留compose 文件会自动设置后者。完整的 bucket 模型见 Filesystem Contract。清单持久化的可靠性细节manifest.json是整套安装系统的事实来源state.py 对它做了三层保护原子写入save_manifest()经由_atomic_write_text()先把 payload 写入同目录临时文件mkstempflushfsync后再os.replace()原子改名。即使写入中途被 SIGKILL、OOM 或断电打断磁盘上也只会留下旧文件或完整新文件绝不出现被截断的 manifest只读文件系统则降级为告警而非崩溃。损坏清单的优雅失败load_manifest()对解析失败部分写入、手改、schema 漂移抛出类型化的ManifestError而不是裸 traceback——因为所有 install 生命周期命令以及自动执行的init hook ensure路由都要经过这里CLI 层会把它转成可读的报错见 cli/install.py。旧镜像仓库自动迁移旧 manifest 若仍钉在已停止更新的ghcr.io/chopratejas/headroom镜像上加载时会被自动重写到组织仓库ghcr.io/headroomlabs-ai/headroom并保留 tagissue #2426见 state.py。与文档配套的其他资源CLI Referenceheadroom全部命令参考Docker-Native InstallDocker 原生安装与 wrapper 详解Proxy Server代理服务端点、readyz/health行为macOS LaunchAgentmacOS 上 launchd 部署的细节Filesystem Contract容器内外状态目录bucket的完整模型docker/docker-compose.native.yml无 Python 持久 Docker 的 compose 定义tests/test_install/install 子系统的完整回归测试集【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考