戰(zhàn)：用 headroom install 把 8787 端口常駐代理變成可管理的本地運(yùn)行時(shí))
Headroom 持久化安裝實(shí)戰(zhàn)用 headroom install 把 8787 端口常駐代理變成可管理的本地運(yùn)行時(shí)【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/head/headroom本篇指南基于 Headroom 倉(cāng)庫(kù)的 persistent-installs 文檔展開(kāi)講清楚headroom install子系統(tǒng)的三大持久化預(yù)設(shè)persistent-service / persistent-task / persistent-docker、--scope與--providers的完整參數(shù)語(yǔ)義、部署清單manifest的存儲(chǔ)位置與結(jié)構(gòu)以及headroom wrap如何自動(dòng)復(fù)用或恢復(fù)常駐部署。讀完并對(duì)照倉(cāng)庫(kù)源碼后你將掌握三種常駐運(yùn)行時(shí)的選型依據(jù)、每個(gè) CLI 命令的底層行為以及 manifest 原子寫(xiě)入與損壞恢復(fù)等工程細(xì)節(jié)。從臨時(shí)代理到常駐運(yùn)行時(shí)persistent install 要解決什么問(wèn)題此前運(yùn)行 Headroom 只有兩種方式臨時(shí)起一個(gè)headroom proxy進(jìn)程退出即消失或headroom wrap ...包一層工具會(huì)話代理生命周期與會(huì)話綁定。這兩種方式都要求代理在需要時(shí)恰好活著。Persistent Installs 讓 Headroom 以持久本地運(yùn)行時(shí)的形式安裝到機(jī)器上受支持的編碼工具Claude Code、Codex、Copilot 等持續(xù)訪問(wèn)http://127.0.0.1:8787上一直開(kāi)著的代理而headroom wrap ...會(huì)復(fù)用或恢復(fù)這個(gè)部署而不是再啟一個(gè)第二套臨時(shí)代理。文檔明確建議當(dāng)你希望工具長(zhǎng)期對(duì)接一個(gè) always-on 代理時(shí)使用 Python 原生的headroom installCLI。整個(gè)子系統(tǒng)位于 headroom/install/ 包內(nèi)從源碼結(jié)構(gòu)看各模塊職責(zé)劃分如下模塊職責(zé)models.py預(yù)設(shè)、運(yùn)行時(shí)、supervisor、作用域等枚舉與DeploymentManifest數(shù)據(jù)類planner.py目標(biāo)探測(cè)、參數(shù)解析、生成規(guī)范化 manifeststate.pymanifest 的原子寫(xiě)入、加載與刪除paths.py部署狀態(tài)目錄、runner 腳本路徑、各工具的配置文件路徑supervisors.pysystemd / launchd / 計(jì)劃任務(wù)等 supervisor 的渲染與啟停providers.py對(duì)工具配置的可逆修改mutation與應(yīng)用/回滾runtime.py前臺(tái)/后臺(tái)運(yùn)行、端口探測(cè)、健康等待、Docker 啟動(dòng)health.pyreadyz/health端點(diǎn)探測(cè)對(duì)應(yīng)的回歸測(cè)試位于 tests/test_install/覆蓋 planner、state、supervisors、runtime、health、providers、native installers 等每個(gè)模塊如 test_planner.py、test_supervisors.py。運(yùn)行時(shí)矩陣先選對(duì)模式再執(zhí)行命令原文檔給出的運(yùn)行時(shí)矩陣是選型的核心依據(jù)完整繼承如下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三種持久化預(yù)設(shè)的區(qū)別本質(zhì)在于誰(shuí)來(lái)保證代理活著persistent-service交給操作系統(tǒng)原生服務(wù)管理器Linux 上是 systemd unitmacOS 上是 launchd LaunchAgentpersistent-task用定時(shí)任務(wù)cron / 計(jì)劃任務(wù)跑一個(gè) watchdog周期性探測(cè)并按需拉起適合不允許注冊(cè)系統(tǒng)服務(wù)的場(chǎng)景persistent-docker則把存活責(zé)任完全交給 Docker 的 restart policy不引入額外 OS 層監(jiān)督?？焖偕鲜秩N預(yù)設(shè)的最短命令本機(jī)持久服務(wù)headroom install apply --preset persistent-service --providers auto headroom install status這條命令在當(dāng)前機(jī)器上安裝一個(gè)后臺(tái)服務(wù)應(yīng)用持久化工具接線即把代理端點(diǎn)寫(xiě)進(jìn)各工具配置并保證8787端口上的代理持續(xù)健康。從源碼看apply的完整鏈路是cli/install.py 中的install命令組接收參數(shù) → planner.py 的build_manifest()生成DeploymentManifest→ state.py 的save_manifest()落盤(pán) → supervisors.py 的install_supervisor()注冊(cè) supervisor → runtime.py 的wait_ready()等待readyz通過(guò)。一個(gè)值得注意的平臺(tái)細(xì)節(jié)在 Windows 上build_manifest()會(huì)把persistent-service靜默降級(jí)為persistent-task見(jiàn) planner.py 的注釋——因?yàn)?Python runner 是普通控制臺(tái)進(jìn)程無(wú)法實(shí)現(xiàn) Windows SCM 協(xié)議協(xié)議sc.exe create注冊(cè)的服務(wù)永遠(yuǎn)無(wú)法啟動(dòng)SCM error 1053而任務(wù)計(jì)劃程序既能開(kāi)機(jī)自啟又能周期健康恢復(fù)因此成為 Windows 上的有效預(yù)設(shè)對(duì)應(yīng) issue #2552。持久看門(mén)狗任務(wù)headroom install apply --preset persistent-task --providers manual --target claude --target codex這條命令安裝的是定時(shí)恢復(fù)路徑而非傳統(tǒng)常駐服務(wù)。從 supervisors.py 看apply會(huì)為每個(gè) profile 渲染兩個(gè)腳本run-headroom.sh前臺(tái) runner執(zhí)行headroom install agent run --profile profileensure-headroom.shwatchdog 腳本執(zhí)行headroom install agent ensure --profile profile由 cron/計(jì)劃任務(wù)周期性調(diào)用發(fā)現(xiàn)代理掛了就拉起。Windows 上對(duì)應(yīng)的是run-headroom.ps1/run-headroom.cmd與ensure-headroom.ps1/ensure-headroom.cmd見(jiàn) paths.py。持久 Dockerheadroom install apply --preset persistent-docker --scope user --providers auto這條命令讓 Docker 的 restart policy 取代 OS supervisor。源碼中有個(gè)針對(duì)該預(yù)設(shè)的實(shí)現(xiàn)細(xì)節(jié)開(kāi)啟--memory時(shí)Python 運(yùn)行時(shí)會(huì)顯式傳--memory-db-path 宿主路徑但Docker 運(yùn)行時(shí)會(huì)被刻意省略該參數(shù)見(jiàn) planner.py 注釋——因?yàn)槿萜鲀?nèi) HOME 是/tmp/headroom-home宿主的~/.headroom只是掛載進(jìn)來(lái)直接傳宿主絕對(duì)路徑會(huì)導(dǎo)致 SQLite 打不開(kāi)、/readyz恒 503、部署超時(shí)回滾issue #2803省略后代理在容器工作目錄下解析 DB恰好落在同一個(gè)綁定掛載文件上。另外如果你使用的是Docker 原生宿主 wrapper而非 Python 安裝也可以直接從已安裝的 wrapper 上對(duì)persistent-docker預(yù)設(shè)執(zhí)行headroom install apply|status|start|stop|restart|remove。但注意邊界service/task 安裝以及 provider/user/system 的變更流程仍屬于 Python 原生 CLI 的職責(zé)。命令面六個(gè)生命周期子命令headroom install apply headroom install status headroom install start headroom install stop headroom install restart headroom install remove文檔說(shuō)明apply會(huì)創(chuàng)建或更新一個(gè)具名部署檔案profile把清單存到~/.headroom/deploy/profile/manifest.json應(yīng)用可逆的配置變更然后啟動(dòng)所選運(yùn)行時(shí)。源碼對(duì)這條命令的補(bǔ)充細(xì)節(jié)profile 命名有校驗(yàn)paths.py 中validate_profile_name()要求 profile 只含[A-Za-z0-9._-]且不允許./..防止路徑穿越目錄布局每個(gè) profile 一個(gè)目錄除manifest.json外還放runner.log運(yùn)行日志、runner.pid前臺(tái)進(jìn)程 pid、各平臺(tái) runner/watchdog 腳本見(jiàn) paths.py顯式--profile不容錯(cuò)cli/install.py 中如果命令行顯式傳了--profile但該 profile 不存在命令會(huì)原樣報(bào)錯(cuò)而不是悄悄轉(zhuǎn)向其他已安裝 profile——stop/restart/remove這類破壞性命令絕不允許誤傷別的部署。只有--profile缺省時(shí)才走恢復(fù)回退讀HEADROOM_DEPLOYMENT_PROFILE環(huán)境變量或唯一的已安裝 profileremove的行為先revert_mutations()回滾對(duì)工具配置的修改再remove_supervisor()注銷 supervisor最后delete_manifest()刪除整個(gè) profile 目錄見(jiàn) state.py 的shutil.rmtree。Presets 與 Runtime kindsPresetspersistent-service- 原生服務(wù)監(jiān)督器persistent-task- 定時(shí)看門(mén)狗 / 恢復(fù)監(jiān)督器persistent-docker- Docker restart policy無(wú)額外 OS 監(jiān)督器這與 models.py 中的枚舉一一對(duì)應(yīng)InstallPreset、SupervisorKindservice/task/none。預(yù)設(shè)到 supervisor 的映射邏輯在build_manifest()里service 預(yù)設(shè)產(chǎn)生SupervisorKind.SERVICEtask 預(yù)設(shè)產(chǎn)生TASKDocker 預(yù)設(shè)產(chǎn)生NONE由容器引擎負(fù)責(zé)重啟。supervisor 的實(shí)際產(chǎn)物從 supervisors.py 可見(jiàn)Linuxpersistent-service渲染 systemd unitscopeuser時(shí)放在~/.config/systemd/user/headroom-profile.servicescopesystem時(shí)放在/etc/systemd/system/unit 內(nèi)容為Restarton-failure、RestartSec5ExecStart指向渲染出的run-headroom.shmacOS渲染 launchd plist 并通過(guò)launchctl bootstrap加載。源碼還處理了一個(gè)真實(shí)的競(jìng)態(tài)launchctl bootout之后立刻bootstrap同一 label 可能在數(shù)秒內(nèi)返回 EIO因此_bootstrap_with_retry()會(huì)重試最多 30 次每次 0.5 秒約 15 秒以扛過(guò) launchd 的釋放窗口見(jiàn) supervisors.py。Runtime kinds--runtime python直接運(yùn)行headroom proxy--runtime docker在 Docker 內(nèi)運(yùn)行 Headroom但部署本身仍由本機(jī)管理對(duì)persistent-docker預(yù)設(shè)runtime 永遠(yuǎn)是 Docker。DeploymentManifest中 Docker 相關(guān)默認(rèn)值可在 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 實(shí)際落筆的文件user~/.bashrc、~/.zshrc、~/.profile可寫(xiě)入持久環(huán)境塊的文件列表systemLinux 上是/etc/profile.d/headroom.shmacOS 上是/etc/profile、/etc/zprofile、/etc/bashrcprovider直接編輯各工具自己的配置文件。當(dāng)前 Provider scope 支持的直接適配器文檔強(qiáng)調(diào) provider scope 是有意保守的當(dāng)前的直接適配器為Claude Code -~/.claude/settings.json的envCodex -~/.codex/config.toml中的托管塊managed blockOpenClaw - 復(fù)用既有的wrap openclaw/unwrap openclaw流程對(duì)于 Copilot、Aider、Cursor 以及更寬泛的 env 驅(qū)動(dòng)配置建議用--scope user或--scope system。與文檔的一個(gè)差異值得注意源碼里PROVIDER_SCOPE_TARGETS實(shí)際包含claude、codex、openclaw、opencode四個(gè)目標(biāo)見(jiàn) planner.py且 paths.py 為 OpenCode 提供了配置路徑解析優(yōu)先OPENCODE_CONFIG環(huán)境變量其次~/.config/opencode/opencode.jsonc或opencode.json。也就是說(shuō) OpenCode 已具備 provider 級(jí)直接適配能力只是 Wiki 文檔尚未同步更新這一條。apply對(duì) provider scope 下不支持的 target 會(huì)明確報(bào)錯(cuò)列出例如Provider scope supports only claude, codex, openclaw, and opencode見(jiàn) 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枚舉看當(dāng)前支持的全部 target 為claude、copilot、codex、aider、cursor、grok_build、grok、openclaw、opencode。auto模式的探測(cè)機(jī)制在 planner.py 的detect_targets()對(duì)每個(gè) target 用shutil.which()查可執(zhí)行文件是否在 PATH 上若一個(gè)都沒(méi)探測(cè)到resolve_targets()會(huì)回退到默認(rèn)集合claude codexprovider scope 下再額外去掉 copilot見(jiàn) planner.py。生成 manifest 時(shí)每個(gè) target 會(huì)得到一份專屬環(huán)境變量build_install_target_envs()代理自身的基礎(chǔ)環(huán)境則固定寫(xiě)入HEADROOM_PORT、HEADROOM_HOST127.0.0.1、HEADROOM_MODE、HEADROOM_BACKEND、顯式的HEADROOM_TELEMETRYon|off見(jiàn) planner.py。另有兩條自動(dòng)派生規(guī)則若目標(biāo)只含 Grok / Grok Build 且沒(méi)有共享該代理的 OpenAI 系工具自動(dòng)設(shè)置OPENAI_TARGET_API_URL指向 xAI 端點(diǎn)從 providers/grok/runtime.py 引入DEFAULT_API_URL--env顯式傳入的變量最后應(yīng)用可覆蓋上述所有自動(dòng)派生默認(rèn)值。健康端點(diǎn)與 wrap 的復(fù)用/恢復(fù)行為持久化部署發(fā)布與臨時(shí)代理運(yùn)行完全相同的readyz和health端點(diǎn)。當(dāng)代理經(jīng)由 install 子系統(tǒng)啟動(dòng)時(shí)/health額外暴露部署元數(shù)據(jù){ deployment: { profile: default, preset: persistent-service, runtime: python, supervisor: service, scope: user } }這些字段恰好對(duì)應(yīng)DeploymentManifest的同名屬性profile/preset/runtime_kind/supervisor_kind/scope說(shuō)明/health是把 manifest 中相應(yīng)字段原樣透出方便運(yùn)維端判斷這個(gè) 8787 端口是誰(shuí)在管。Python 原生的headroom wrap ...流程會(huì)先檢查請(qǐng)求端口上是否存在匹配的持久化部署再?zèng)Q定是否新起臨時(shí)代理如果已安裝的部署存在但處于停止或不健康狀態(tài)它會(huì)先嘗試恢復(fù)它。探測(cè)邏輯基于 health.py 的probe_ready()/probe_json()等待邏輯在 runtime.py 的wait_ready()對(duì)/readyz輪詢直到 200。需要明確的邊界Docker 原生宿主 wrapper 尚不會(huì)自動(dòng)復(fù)用或恢復(fù)持久化 profile——除非顯式--no-proxy否則它總是啟動(dòng)一個(gè)全新的代理容器。Docker 原生路徑的關(guān)系與 compose 管理Docker 原生宿主 wrapper 與 Python install CLI 解決的是運(yùn)行時(shí)故事的不同層Docker-Native Install - 容器化的按需 CLI、宿主工具的 wrap 流程以及 Docker 原生的persistent-docker生命周期命令headroom install ...- 完整的持久 service / task / Docker 生命周期管理包含 provider/user/system 變更。對(duì)于不依賴 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穩(wěn)定并在容器退出時(shí)自動(dòng)重啟代理。注意HEADROOM_WORKSPACEcompose 文件使用的宿主側(cè) bind-mount 源目錄與HEADROOM_WORKSPACE_DIR容器內(nèi) Headroom 狀態(tài)根的規(guī)范變量不是同一個(gè)變量。兩者都保留compose 文件會(huì)自動(dòng)設(shè)置后者。完整的 bucket 模型見(jiàn) Filesystem Contract。清單持久化的可靠性細(xì)節(jié)manifest.json是整套安裝系統(tǒng)的事實(shí)來(lái)源state.py 對(duì)它做了三層保護(hù)原子寫(xiě)入save_manifest()經(jīng)由_atomic_write_text()先把 payload 寫(xiě)入同目錄臨時(shí)文件mkstempflushfsync后再os.replace()原子改名。即使寫(xiě)入中途被 SIGKILL、OOM 或斷電打斷磁盤(pán)上也只會(huì)留下舊文件或完整新文件絕不出現(xiàn)被截?cái)嗟?manifest只讀文件系統(tǒng)則降級(jí)為告警而非崩潰。損壞清單的優(yōu)雅失敗load_manifest()對(duì)解析失敗部分寫(xiě)入、手改、schema 漂移拋出類型化的ManifestError而不是裸 traceback——因?yàn)樗?install 生命周期命令以及自動(dòng)執(zhí)行的init hook ensure路由都要經(jīng)過(guò)這里CLI 層會(huì)把它轉(zhuǎn)成可讀的報(bào)錯(cuò)見(jiàn) cli/install.py。舊鏡像倉(cāng)庫(kù)自動(dòng)遷移舊 manifest 若仍釘在已停止更新的ghcr.io/chopratejas/headroom鏡像上加載時(shí)會(huì)被自動(dòng)重寫(xiě)到組織倉(cāng)庫(kù)ghcr.io/headroomlabs-ai/headroom并保留 tagissue #2426見(jiàn) state.py。與文檔配套的其他資源CLI Referenceheadroom全部命令參考Docker-Native InstallDocker 原生安裝與 wrapper 詳解Proxy Server代理服務(wù)端點(diǎn)、readyz/health行為macOS LaunchAgentmacOS 上 launchd 部署的細(xì)節(jié)Filesystem Contract容器內(nèi)外狀態(tài)目錄bucket的完整模型docker/docker-compose.native.yml無(wú) Python 持久 Docker 的 compose 定義tests/test_install/install 子系統(tǒng)的完整回歸測(cè)試集【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/head/headroom創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Headroom 持久化安裝實(shí)戰(zhàn)：用 headroom install 把 8787 端口常駐代理變成可管理的本地運(yùn)行時(shí)
Headroom 持久化安裝實(shí)戰(zhàn)用 headroom install 把 8787 端口常駐代理變成可管理的本地運(yùn)行時(shí)【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/head/headroom本篇指南基于 Headroom 倉(cāng)庫(kù)的 persistent-installs 文檔展開(kāi)講清楚headroom install子系統(tǒng)的三大持久化預(yù)設(shè)persistent-service / persistent-task / persistent-docker、--scope與--providers的完整參數(shù)語(yǔ)義、部署清單manifest的存儲(chǔ)位置與結(jié)構(gòu)以及headroom wrap如何自動(dòng)復(fù)用或恢復(fù)常駐部署。讀完并對(duì)照倉(cāng)庫(kù)源碼后你將掌握三種常駐運(yùn)行時(shí)的選型依據(jù)、每個(gè) CLI 命令的底層行為以及 manifest 原子寫(xiě)入與損壞恢復(fù)等工程細(xì)節(jié)。從臨時(shí)代理到常駐運(yùn)行時(shí)persistent install 要解決什么問(wèn)題此前運(yùn)行 Headroom 只有兩種方式臨時(shí)起一個(gè)headroom proxy進(jìn)程退出即消失或headroom wrap ...包一層工具會(huì)話代理生命周期與會(huì)話綁定。這兩種方式都要求代理在需要時(shí)恰好活著。Persistent Installs 讓 Headroom 以持久本地運(yùn)行時(shí)的形式安裝到機(jī)器上受支持的編碼工具Claude Code、Codex、Copilot 等持續(xù)訪問(wèn)http://127.0.0.1:8787上一直開(kāi)著的代理而headroom wrap ...會(huì)復(fù)用或恢復(fù)這個(gè)部署而不是再啟一個(gè)第二套臨時(shí)代理。文檔明確建議當(dāng)你希望工具長(zhǎng)期對(duì)接一個(gè) always-on 代理時(shí)使用 Python 原生的headroom installCLI。整個(gè)子系統(tǒng)位于 headroom/install/ 包內(nèi)從源碼結(jié)構(gòu)看各模塊職責(zé)劃分如下模塊職責(zé)models.py預(yù)設(shè)、運(yùn)行時(shí)、supervisor、作用域等枚舉與DeploymentManifest數(shù)據(jù)類planner.py目標(biāo)探測(cè)、參數(shù)解析、生成規(guī)范化 manifeststate.pymanifest 的原子寫(xiě)入、加載與刪除paths.py部署狀態(tài)目錄、runner 腳本路徑、各工具的配置文件路徑supervisors.pysystemd / launchd / 計(jì)劃任務(wù)等 supervisor 的渲染與啟停providers.py對(duì)工具配置的可逆修改mutation與應(yīng)用/回滾runtime.py前臺(tái)/后臺(tái)運(yùn)行、端口探測(cè)、健康等待、Docker 啟動(dòng)health.pyreadyz/health端點(diǎn)探測(cè)對(duì)應(yīng)的回歸測(cè)試位于 tests/test_install/覆蓋 planner、state、supervisors、runtime、health、providers、native installers 等每個(gè)模塊如 test_planner.py、test_supervisors.py。運(yùn)行時(shí)矩陣先選對(duì)模式再執(zhí)行命令原文檔給出的運(yùn)行時(shí)矩陣是選型的核心依據(jù)完整繼承如下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三種持久化預(yù)設(shè)的區(qū)別本質(zhì)在于誰(shuí)來(lái)保證代理活著persistent-service交給操作系統(tǒng)原生服務(wù)管理器Linux 上是 systemd unitmacOS 上是 launchd LaunchAgentpersistent-task用定時(shí)任務(wù)cron / 計(jì)劃任務(wù)跑一個(gè) watchdog周期性探測(cè)并按需拉起適合不允許注冊(cè)系統(tǒng)服務(wù)的場(chǎng)景persistent-docker則把存活責(zé)任完全交給 Docker 的 restart policy不引入額外 OS 層監(jiān)督?？焖偕鲜秩N預(yù)設(shè)的最短命令本機(jī)持久服務(wù)headroom install apply --preset persistent-service --providers auto headroom install status這條命令在當(dāng)前機(jī)器上安裝一個(gè)后臺(tái)服務(wù)應(yīng)用持久化工具接線即把代理端點(diǎn)寫(xiě)進(jìn)各工具配置并保證8787端口上的代理持續(xù)健康。從源碼看apply的完整鏈路是cli/install.py 中的install命令組接收參數(shù) → planner.py 的build_manifest()生成DeploymentManifest→ state.py 的save_manifest()落盤(pán) → supervisors.py 的install_supervisor()注冊(cè) supervisor → runtime.py 的wait_ready()等待readyz通過(guò)。一個(gè)值得注意的平臺(tái)細(xì)節(jié)在 Windows 上build_manifest()會(huì)把persistent-service靜默降級(jí)為persistent-task見(jiàn) planner.py 的注釋——因?yàn)?Python runner 是普通控制臺(tái)進(jìn)程無(wú)法實(shí)現(xiàn) Windows SCM 協(xié)議協(xié)議sc.exe create注冊(cè)的服務(wù)永遠(yuǎn)無(wú)法啟動(dòng)SCM error 1053而任務(wù)計(jì)劃程序既能開(kāi)機(jī)自啟又能周期健康恢復(fù)因此成為 Windows 上的有效預(yù)設(shè)對(duì)應(yīng) issue #2552。持久看門(mén)狗任務(wù)headroom install apply --preset persistent-task --providers manual --target claude --target codex這條命令安裝的是定時(shí)恢復(fù)路徑而非傳統(tǒng)常駐服務(wù)。從 supervisors.py 看apply會(huì)為每個(gè) profile 渲染兩個(gè)腳本run-headroom.sh前臺(tái) runner執(zhí)行headroom install agent run --profile profileensure-headroom.shwatchdog 腳本執(zhí)行headroom install agent ensure --profile profile由 cron/計(jì)劃任務(wù)周期性調(diào)用發(fā)現(xiàn)代理掛了就拉起。Windows 上對(duì)應(yīng)的是run-headroom.ps1/run-headroom.cmd與ensure-headroom.ps1/ensure-headroom.cmd見(jiàn) paths.py。持久 Dockerheadroom install apply --preset persistent-docker --scope user --providers auto這條命令讓 Docker 的 restart policy 取代 OS supervisor。源碼中有個(gè)針對(duì)該預(yù)設(shè)的實(shí)現(xiàn)細(xì)節(jié)開(kāi)啟--memory時(shí)Python 運(yùn)行時(shí)會(huì)顯式傳--memory-db-path 宿主路徑但Docker 運(yùn)行時(shí)會(huì)被刻意省略該參數(shù)見(jiàn) planner.py 注釋——因?yàn)槿萜鲀?nèi) HOME 是/tmp/headroom-home宿主的~/.headroom只是掛載進(jìn)來(lái)直接傳宿主絕對(duì)路徑會(huì)導(dǎo)致 SQLite 打不開(kāi)、/readyz恒 503、部署超時(shí)回滾issue #2803省略后代理在容器工作目錄下解析 DB恰好落在同一個(gè)綁定掛載文件上。另外如果你使用的是Docker 原生宿主 wrapper而非 Python 安裝也可以直接從已安裝的 wrapper 上對(duì)persistent-docker預(yù)設(shè)執(zhí)行headroom install apply|status|start|stop|restart|remove。但注意邊界service/task 安裝以及 provider/user/system 的變更流程仍屬于 Python 原生 CLI 的職責(zé)。命令面六個(gè)生命周期子命令headroom install apply headroom install status headroom install start headroom install stop headroom install restart headroom install remove文檔說(shuō)明apply會(huì)創(chuàng)建或更新一個(gè)具名部署檔案profile把清單存到~/.headroom/deploy/profile/manifest.json應(yīng)用可逆的配置變更然后啟動(dòng)所選運(yùn)行時(shí)。源碼對(duì)這條命令的補(bǔ)充細(xì)節(jié)profile 命名有校驗(yàn)paths.py 中validate_profile_name()要求 profile 只含[A-Za-z0-9._-]且不允許./..防止路徑穿越目錄布局每個(gè) profile 一個(gè)目錄除manifest.json外還放runner.log運(yùn)行日志、runner.pid前臺(tái)進(jìn)程 pid、各平臺(tái) runner/watchdog 腳本見(jiàn) paths.py顯式--profile不容錯(cuò)cli/install.py 中如果命令行顯式傳了--profile但該 profile 不存在命令會(huì)原樣報(bào)錯(cuò)而不是悄悄轉(zhuǎn)向其他已安裝 profile——stop/restart/remove這類破壞性命令絕不允許誤傷別的部署。只有--profile缺省時(shí)才走恢復(fù)回退讀HEADROOM_DEPLOYMENT_PROFILE環(huán)境變量或唯一的已安裝 profileremove的行為先revert_mutations()回滾對(duì)工具配置的修改再remove_supervisor()注銷 supervisor最后delete_manifest()刪除整個(gè) profile 目錄見(jiàn) state.py 的shutil.rmtree。Presets 與 Runtime kindsPresetspersistent-service- 原生服務(wù)監(jiān)督器persistent-task- 定時(shí)看門(mén)狗 / 恢復(fù)監(jiān)督器persistent-docker- Docker restart policy無(wú)額外 OS 監(jiān)督器這與 models.py 中的枚舉一一對(duì)應(yīng)InstallPreset、SupervisorKindservice/task/none。預(yù)設(shè)到 supervisor 的映射邏輯在build_manifest()里service 預(yù)設(shè)產(chǎn)生SupervisorKind.SERVICEtask 預(yù)設(shè)產(chǎn)生TASKDocker 預(yù)設(shè)產(chǎn)生NONE由容器引擎負(fù)責(zé)重啟。supervisor 的實(shí)際產(chǎn)物從 supervisors.py 可見(jiàn)Linuxpersistent-service渲染 systemd unitscopeuser時(shí)放在~/.config/systemd/user/headroom-profile.servicescopesystem時(shí)放在/etc/systemd/system/unit 內(nèi)容為Restarton-failure、RestartSec5ExecStart指向渲染出的run-headroom.shmacOS渲染 launchd plist 并通過(guò)launchctl bootstrap加載。源碼還處理了一個(gè)真實(shí)的競(jìng)態(tài)launchctl bootout之后立刻bootstrap同一 label 可能在數(shù)秒內(nèi)返回 EIO因此_bootstrap_with_retry()會(huì)重試最多 30 次每次 0.5 秒約 15 秒以扛過(guò) launchd 的釋放窗口見(jiàn) supervisors.py。Runtime kinds--runtime python直接運(yùn)行headroom proxy--runtime docker在 Docker 內(nèi)運(yùn)行 Headroom但部署本身仍由本機(jī)管理對(duì)persistent-docker預(yù)設(shè)runtime 永遠(yuǎn)是 Docker。DeploymentManifest中 Docker 相關(guān)默認(rèn)值可在 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 實(shí)際落筆的文件user~/.bashrc、~/.zshrc、~/.profile可寫(xiě)入持久環(huán)境塊的文件列表systemLinux 上是/etc/profile.d/headroom.shmacOS 上是/etc/profile、/etc/zprofile、/etc/bashrcprovider直接編輯各工具自己的配置文件。當(dāng)前 Provider scope 支持的直接適配器文檔強(qiáng)調(diào) provider scope 是有意保守的當(dāng)前的直接適配器為Claude Code -~/.claude/settings.json的envCodex -~/.codex/config.toml中的托管塊managed blockOpenClaw - 復(fù)用既有的wrap openclaw/unwrap openclaw流程對(duì)于 Copilot、Aider、Cursor 以及更寬泛的 env 驅(qū)動(dòng)配置建議用--scope user或--scope system。與文檔的一個(gè)差異值得注意源碼里PROVIDER_SCOPE_TARGETS實(shí)際包含claude、codex、openclaw、opencode四個(gè)目標(biāo)見(jiàn) planner.py且 paths.py 為 OpenCode 提供了配置路徑解析優(yōu)先OPENCODE_CONFIG環(huán)境變量其次~/.config/opencode/opencode.jsonc或opencode.json。也就是說(shuō) OpenCode 已具備 provider 級(jí)直接適配能力只是 Wiki 文檔尚未同步更新這一條。apply對(duì) provider scope 下不支持的 target 會(huì)明確報(bào)錯(cuò)列出例如Provider scope supports only claude, codex, openclaw, and opencode見(jiàn) 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枚舉看當(dāng)前支持的全部 target 為claude、copilot、codex、aider、cursor、grok_build、grok、openclaw、opencode。auto模式的探測(cè)機(jī)制在 planner.py 的detect_targets()對(duì)每個(gè) target 用shutil.which()查可執(zhí)行文件是否在 PATH 上若一個(gè)都沒(méi)探測(cè)到resolve_targets()會(huì)回退到默認(rèn)集合claude codexprovider scope 下再額外去掉 copilot見(jiàn) planner.py。生成 manifest 時(shí)每個(gè) target 會(huì)得到一份專屬環(huán)境變量build_install_target_envs()代理自身的基礎(chǔ)環(huán)境則固定寫(xiě)入HEADROOM_PORT、HEADROOM_HOST127.0.0.1、HEADROOM_MODE、HEADROOM_BACKEND、顯式的HEADROOM_TELEMETRYon|off見(jiàn) planner.py。另有兩條自動(dòng)派生規(guī)則若目標(biāo)只含 Grok / Grok Build 且沒(méi)有共享該代理的 OpenAI 系工具自動(dòng)設(shè)置OPENAI_TARGET_API_URL指向 xAI 端點(diǎn)從 providers/grok/runtime.py 引入DEFAULT_API_URL--env顯式傳入的變量最后應(yīng)用可覆蓋上述所有自動(dòng)派生默認(rèn)值。健康端點(diǎn)與 wrap 的復(fù)用/恢復(fù)行為持久化部署發(fā)布與臨時(shí)代理運(yùn)行完全相同的readyz和health端點(diǎn)。當(dāng)代理經(jīng)由 install 子系統(tǒng)啟動(dòng)時(shí)/health額外暴露部署元數(shù)據(jù){ deployment: { profile: default, preset: persistent-service, runtime: python, supervisor: service, scope: user } }這些字段恰好對(duì)應(yīng)DeploymentManifest的同名屬性profile/preset/runtime_kind/supervisor_kind/scope說(shuō)明/health是把 manifest 中相應(yīng)字段原樣透出方便運(yùn)維端判斷這個(gè) 8787 端口是誰(shuí)在管。Python 原生的headroom wrap ...流程會(huì)先檢查請(qǐng)求端口上是否存在匹配的持久化部署再?zèng)Q定是否新起臨時(shí)代理如果已安裝的部署存在但處于停止或不健康狀態(tài)它會(huì)先嘗試恢復(fù)它。探測(cè)邏輯基于 health.py 的probe_ready()/probe_json()等待邏輯在 runtime.py 的wait_ready()對(duì)/readyz輪詢直到 200。需要明確的邊界Docker 原生宿主 wrapper 尚不會(huì)自動(dòng)復(fù)用或恢復(fù)持久化 profile——除非顯式--no-proxy否則它總是啟動(dòng)一個(gè)全新的代理容器。Docker 原生路徑的關(guān)系與 compose 管理Docker 原生宿主 wrapper 與 Python install CLI 解決的是運(yùn)行時(shí)故事的不同層Docker-Native Install - 容器化的按需 CLI、宿主工具的 wrap 流程以及 Docker 原生的persistent-docker生命周期命令headroom install ...- 完整的持久 service / task / Docker 生命周期管理包含 provider/user/system 變更。對(duì)于不依賴 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穩(wěn)定并在容器退出時(shí)自動(dòng)重啟代理。注意HEADROOM_WORKSPACEcompose 文件使用的宿主側(cè) bind-mount 源目錄與HEADROOM_WORKSPACE_DIR容器內(nèi) Headroom 狀態(tài)根的規(guī)范變量不是同一個(gè)變量。兩者都保留compose 文件會(huì)自動(dòng)設(shè)置后者。完整的 bucket 模型見(jiàn) Filesystem Contract。清單持久化的可靠性細(xì)節(jié)manifest.json是整套安裝系統(tǒng)的事實(shí)來(lái)源state.py 對(duì)它做了三層保護(hù)原子寫(xiě)入save_manifest()經(jīng)由_atomic_write_text()先把 payload 寫(xiě)入同目錄臨時(shí)文件mkstempflushfsync后再os.replace()原子改名。即使寫(xiě)入中途被 SIGKILL、OOM 或斷電打斷磁盤(pán)上也只會(huì)留下舊文件或完整新文件絕不出現(xiàn)被截?cái)嗟?manifest只讀文件系統(tǒng)則降級(jí)為告警而非崩潰。損壞清單的優(yōu)雅失敗load_manifest()對(duì)解析失敗部分寫(xiě)入、手改、schema 漂移拋出類型化的ManifestError而不是裸 traceback——因?yàn)樗?install 生命周期命令以及自動(dòng)執(zhí)行的init hook ensure路由都要經(jīng)過(guò)這里CLI 層會(huì)把它轉(zhuǎn)成可讀的報(bào)錯(cuò)見(jiàn) cli/install.py。舊鏡像倉(cāng)庫(kù)自動(dòng)遷移舊 manifest 若仍釘在已停止更新的ghcr.io/chopratejas/headroom鏡像上加載時(shí)會(huì)被自動(dòng)重寫(xiě)到組織倉(cāng)庫(kù)ghcr.io/headroomlabs-ai/headroom并保留 tagissue #2426見(jiàn) state.py。與文檔配套的其他資源CLI Referenceheadroom全部命令參考Docker-Native InstallDocker 原生安裝與 wrapper 詳解Proxy Server代理服務(wù)端點(diǎn)、readyz/health行為macOS LaunchAgentmacOS 上 launchd 部署的細(xì)節(jié)Filesystem Contract容器內(nèi)外狀態(tài)目錄bucket的完整模型docker/docker-compose.native.yml無(wú) Python 持久 Docker 的 compose 定義tests/test_install/install 子系統(tǒng)的完整回歸測(cè)試集【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/head/headroom創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考