Headroom Proxy on macOS基于 LaunchAgent 的常驻代理服务部署实战指南【免费下载链接】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 仓库中 macOS 部署指南 展开讲解如何将 headroom 代理服务器部署为 macOS 原生 LaunchAgent 后台服务实现登录自动启动、崩溃自动拉起与标准日志落盘。读完本文你可以独立完成从 CLI 安装、plist 生成、shell 集成到故障排查、卸载的完整生命周期管理并理解安装脚本与 proxy 内存嵌入器MPS GPU offload在源码层面的实际行为。1. 为什么选择 LaunchAgent 后台化部署headroom 是一个在内容到达 LLM 之前压缩工具输出、日志、文件与 RAG 分块的代理层库、proxy、MCP server。在日常开发中代理需要作为 Claude 等客户端的上游中转长期存活。手动运行headroom proxy需要一直占用一个终端窗口且进程崩溃后无人重启。macOS 的 LaunchAgent 提供了原生的解决方案部署后获得四项能力自动启动用户登录login时自动拉起服务崩溃恢复KeepAlive机制在进程退出后自动重启标准日志stdout/stderr 分别写入~/Library/Logs/下的日志文件原生生命周期管理通过launchctl完成启动、停止、状态查询。这非常适合部署一次、忘记它set and forget的本地开发环境。需要说明的是LaunchAgent 是**按用户per-user**的运行在用户上下文中、随用户登录启动这与系统级的 LaunchDaemonroot/开机启动不同后者的取舍见 第 11 节安全考量。2. 前置条件与 CLI 安装2.1 环境要求条件说明macOS 版本macOS 10.13High Sierra 或更新headroom已安装并带proxy支持API Key已配置 Anthropic API key代理上游默认指向 Anthropic2.2 安装带 proxy 支持的 headroom# 安装宿主 CLI含 proxy 支持 uv tool install --python 3.13 headroom-ai[proxy] # 如果安装后 shell 找不到 headroom uv tool update-shell # 验证安装 headroom proxy --help在 macOS Homebrew 环境下python3可能指向比当前 headroom wheel 支持的更新的解释器显式传--python 3.13可以把 CLI 固定在 wheel 支持的 Python 上。若系统缺少 Python 3.13先安装brew install python3.132.3 API Key 的三种配置方式方式一Shell 环境推荐# 添加到 ~/.bashrc 或 ~/.zshrc export ANTHROPIC_API_KEYsk-ant-...方式二写入 LaunchAgent plistkeyEnvironmentVariables/key dict keyANTHROPIC_API_KEY/key stringsk-ant-.../string /dict方式三系统级环境# 添加到 /etc/launchd.conf需要管理员权限 setenv ANTHROPIC_API_KEY sk-ant-...plist 模板默认把 API key 相关配置保持注释状态见 模板文件 中!-- ANTHROPIC_API_KEY should be set in your shell environment --注释即官方倾向让密钥留在 shell 环境中而不是固化进 plist。3. 部署资产与自动化安装3.1 部署目录结构所有 macOS 部署资产位于 examples/deployment/macos-launchagent/文件作用com.headroom.proxy.plist.templateLaunchAgent plist 模板含__HEADROOM_PATH__、__PORT__、__HOME__占位符install.sh自动化安装脚本uninstall.sh自动化卸载脚本shell-integration.shShell 集成脚本自动设置ANTHROPIC_BASE_URLREADME.md该目录的快速上手说明3.2 一键安装cd examples/deployment/macos-launchagent ./install.sh安装器完成六步操作检测headroom可执行文件command -v headroom并校验headroom proxy --help可用提示端口配置默认 8787创建日志目录~/Library/Logs/headroom从模板生成 LaunchAgent plist 并写入~/Library/LaunchAgents/com.headroom.proxy.plist加载并启动服务launchctl bootstrap验证服务状态与端口监听。安装选项# 自定义端口 ./install.sh --port 9000 # 无人值守安装跳过所有交互提示 ./install.sh --port 8787 --unattended # 已存在服务时重装交互式确认 Reinstall? [y/N] ./install.sh3.3 从源码看 install.sh 的实际行为阅读 install.sh 可以确认以下实现细节排障时很有用平台守护uname -s不为Darwin时直接退出并提示 Use systemd on LinuxL76-L79端口校验端口必须是 1024–65535 的整数否则fatalL126-L128端口占用检测用lsof -iTCP:$PORT -sTCP:LISTEN -t预检被占用时交互确认L131-L140模板渲染用sed一次性替换三个占位符生成最终 plist随后chmod 644L157-L165幂等加载launchctl bootstrap失败时会先launchctl bootout再重试一次L169-L179加载后验证sleep 2后检查launchctl print与端口监听未监听时提示tail -f ${LOG_DIR}/proxy-error.logL181-L198。安装成功后脚本会打印服务详情端口、日志路径、label以及推荐的 shell 集成与常用命令例如重启命令launchctl kickstart -k gui/$USER_UID/com.headroom.proxy。4. 手动安装完全掌控每一步如果不想走安装脚本可以按以下四步手动完成。Step 1创建日志目录mkdir -p ~/Library/Logs/headroomStep 2生成 LaunchAgent Plistcd examples/deployment/macos-launchagent cp com.headroom.proxy.plist.template ~/Library/LaunchAgents/com.headroom.proxy.plist然后编辑~/Library/LaunchAgents/com.headroom.proxy.plist替换三个占位符__HEADROOM_PATH__→command -v headroom的输出如/usr/local/bin/headroom__PORT__→ 目标端口如8787__HOME__→echo $HOME的输出如/Users/yourusername。Step 3加载 LaunchAgentlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plistStep 4验证服务# 服务是否运行 launchctl print gui/$(id -u)/com.headroom.proxy # 端口是否监听 lsof -iTCP:8787 -sTCP:LISTEN # 健康检查 curl http://localhost:8787/healthPlist 模板逐项解读com.headroom.proxy.plist.template 中每个键的作用!-- 服务标签必须与 plist 文件名一致 -- keyLabel/key stringcom.headroom.proxy/string !-- 启动命令headroom proxy --host 127.0.0.1 --port PORT -- keyProgramArguments/key array string__HEADROOM_PATH__/string stringproxy/string string--host/string string127.0.0.1/string string--port/string string__PORT__/string /array keyEnvironmentVariables/key dict !-- 端口环境模板实际使用的键名是 HEADROOM_PROXY_PORT -- keyHEADROOM_PROXY_PORT/key string__PORT__/string !-- ANTHROPIC_API_KEY 建议留在 shell 环境模板中保持注释 -- /dict keyWorkingDirectory/key string__HOME__/string !-- stdout / stderr 分别落盘 -- keyStandardOutPath/key string__HOME__/Library/Logs/headroom/proxy.log/string keyStandardErrorPath/key string__HOME__/Library/Logs/headroom/proxy-error.log/string !-- 崩溃自动重启 -- keyKeepAlive/key true/ !-- 登录时自动启动 -- keyRunAtLoad/key true/ !-- 后台自适应进程类型 -- keyProcessType/key stringAdaptive/string !-- 重启间隔 10 秒 -- keyThrottleInterval/key integer10/integer两个值得注意的点默认绑定127.0.0.1ProgramArguments中写死--host 127.0.0.1即代理只监听本机回环地址不暴露到外部网络ProcessType Adaptive允许 launchd 将其作为后台进程管理降低前台调度优先级。5. 配置详解5.1 端口默认端口8787。自定义方式安装时指定./install.sh --port 9000安装后更换卸载./uninstall.sh用新端口重装./install.sh --port 9000同步更新 shell 侧的端口变量见 5.4 说明关于端口环境变量的一个勘误说明wiki 原文部分位置写作HEADROOM_PORT但从仓库源码看实际生效的键名是HEADROOM_PROXY_PORT——shell-integration.sh 中HEADROOM_PROXY_PORT${HEADROOM_PROXY_PORT:-8787}install.sh 的成功提示也打印export HEADROOM_PROXY_PORT${PORT}plist 模板写入的也是HEADROOM_PROXY_PORT。请以HEADROOM_PROXY_PORT为准。5.2 日志位置日志写入 macOS 标准位置标准输出~/Library/Logs/headroom/proxy.log错误输出~/Library/Logs/headroom/proxy-error.log如需改到自定义路径编辑 plist 中的对应键keyStandardOutPath/key string/custom/path/proxy.log/string同理可改StandardErrorPath。5.3 环境变量与压缩后端说明在 plist 的EnvironmentVariables节中追加其他配置keyEnvironmentVariables/key dict !-- 代理端口 -- keyHEADROOM_PROXY_PORT/key string8787/string !-- 可选API key或设置在 shell 中 -- keyANTHROPIC_API_KEY/key stringsk-ant-.../string /dict重要变更提示早先 LLMLingua-2 launch-agent 变量HEADROOM_COMPRESSION_PROVIDERllmlingua、HEADROOM_LLMLINGUA_DEVICE以及headroom-ai[llmlingua]extra已随--llmlingua标志一起退役。模板中残留的HEADROOM_COMPRESSION_PROVIDER注释行即为历史痕迹。如今要启用 ML 压缩应安装[ml]extra 并参考 wiki/transforms.md。5.4 崩溃恢复LaunchAgent 的恢复语义由两个键控制见模板 L49-L63KeepAlive true进程退出包括崩溃后自动重启ThrottleInterval 10两次重启尝试之间至少间隔 10 秒防止崩溃风暴打满 CPU。如需禁用自动重启keyKeepAlive/key false/注意修改 plist 后需要重新加载服务才能生效重载命令见 第 7 节。6. Shell 集成安装完服务后可以让 shell 在登录时自动把 Anthropic 客户端指向代理。6.1 配置方法在~/.bashrcbash或~/.zshrczsh中追加# 端口可选默认 8787——注意实际键名是 HEADROOM_PROXY_PORT export HEADROOM_PROXY_PORT8787 # 引入 shell 集成 source /path/to/headroom/examples/deployment/macos-launchagent/shell-integration.sh6.2 脚本机制源码级解读shell-integration.sh 的执行逻辑防重复加载通过HEADROOM_SHELL_INTEGRATION_LOADED环境变量去重L27-L30该变量同时是排障探针——正常 source 后echo $HEADROOM_SHELL_INTEGRATION_LOADED应为1快速路径检测lsof -iTCP:${HEADROOM_PROXY_PORT} -sTCP:LISTEN -t判断端口是否已有进程监听L33-L35运行中则直接接管设置export ANTHROPIC_BASE_URLhttp://localhost:${HEADROOM_PROXY_PORT}L57-L59未运行则尝试拉起若 plist 文件存在执行launchctl bootstrap gui/$(id -u) plist幂等已加载不会失败等待 1 秒后复检启动成功才设置ANTHROPIC_BASE_URL并打印提示L61-L70清理命名空间结束时unset -f两个内部函数不污染 shellL74。这套机制让 Claude 系客户端无需手动配置即可走代理。6.3 手动配置不用集成脚本# 添加到 ~/.bashrc 或 ~/.zshrc export ANTHROPIC_BASE_URLhttp://localhost:87877. 服务管理7.1 查看状态# 服务状态 launchctl print gui/$(id -u)/com.headroom.proxy # 端口监听 lsof -iTCP:8787 -sTCP:LISTEN # 健康端点 curl http://localhost:8787/health7.2 查看日志tail -f ~/Library/Logs/headroom/proxy.log # stdout tail -f ~/Library/Logs/headroom/proxy-error.log # stderr tail -n 50 ~/Library/Logs/headroom/proxy-error.log # 最近 50 行7.3 重启服务# 优雅重启stop 依赖 KeepAlive 拉起 launchctl kickstart -k gui/$(id -u)/com.headroom.proxy # 手动 stop/start launchctl bootout gui/$(id -u)/com.headroom.proxy launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist7.4 临时停用不卸载# 禁用进程不会被 KeepAlive 拉起 launchctl disable gui/$(id -u)/com.headroom.proxy # 重新启用 launchctl enable gui/$(id -u)/com.headroom.proxydisable与bootout的区别bootout会把整个 job 从 launchd 中卸载disable只是把该 label 标记为禁用状态适合暂时不想跑但保留注册的场景。8. 安装后验证清单按顺序执行以下五步全部通过即部署成功1. 服务状态——launchctl print gui/$(id -u)/com.headroom.proxy输出应包含state running2. 端口监听——lsof -iTCP:8787 -sTCP:LISTEN应显示 headroom 进程。3. 健康端点——curl http://localhost:8787/health期望返回{status: healthy}4. 真实代理请求—— 走一遍完整链路export ANTHROPIC_BASE_URLhttp://localhost:8787 python -c import anthropic client anthropic.Anthropic() response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens50, messages[{role: user, content: Hi}] ) print(response.content[0].text) 5. 错误日志无异常tail -n 20 ~/Library/Logs/headroom/proxy-error.log应无错误输出常见启动错误对照 第 9 节。9. 故障排查9.1 服务无法启动症状launchctl print显示未加载或 failed 状态。先看日志tail -n 50 ~/Library/Logs/headroom/proxy-error.log常见原因对照表错误解决方案ANTHROPIC_API_KEY not set在环境或 plist 中设置 API keyModuleNotFoundError: No module named headroom安装uv tool install --python 3.13 headroom-ai[proxy]command not found: headroom用command -v headroom的输出修正 plist 路径Address already in use换端口或停掉占用端口的服务9.2 端口被占用症状服务起来了但端口不监听日志出现 Address already in use。lsof -iTCP:8787 -sTCP:LISTEN # 找出占用者处理停掉冲突服务或换端口./uninstall.sh ./install.sh --port 9000。9.3 服务启动后立即崩溃tail -f ~/Library/Logs/headroom/proxy-error.log常见原因依赖缺失重装headroom-ai[proxy]、API key 无效校验ANTHROPIC_API_KEY、Python 版本不兼容要求 3.10。9.4 ANTHROPIC_BASE_URL 未生效先确认代理在运行curl http://localhost:8787/health然后source ~/.bashrc # 或 ~/.zshrc # 集成脚本是否被 source正常应为 1 echo $HEADROOM_SHELL_INTEGRATION_LOADED若为 0说明shell-integration.sh未被当前 shell 加载。9.5 登录/重启后未自动启动launchctl list | grep headroom # 确认已注册未注册则重新加载launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist并确认 plist 中RunAtLoad为truegrep -A1 RunAtLoad ~/Library/LaunchAgents/com.headroom.proxy.plist9.6 权限问题Operation not permittedchmod 644 ~/Library/LaunchAgents/com.headroom.proxy.plist ls -l ~/Library/LaunchAgents/com.headroom.proxy.plistplist 应属主为当前用户而非 root安装脚本本身会chmod 644见 install.sh。10. 卸载10.1 快速卸载cd examples/deployment/macos-launchagent ./uninstall.shuninstall.sh 依次执行launchctl bootout停止服务 → 删除 plist → 询问或按--remove-logs直接执行是否删除日志目录。10.2 彻底清理./uninstall.sh --remove-logs # 从 ~/.bashrc / ~/.zshrc 中删除或注释 # export HEADROOM_PROXY_PORT8787 # source .../shell-integration.sh # 以及如有export ANTHROPIC_BASE_URL...10.3 手动卸载launchctl bootout gui/$(id -u)/com.headroom.proxy rm ~/Library/LaunchAgents/com.headroom.proxy.plist rm -rf ~/Library/Logs/headroom # 可选11. 安全考量LaunchAgent vs LaunchDaemonLaunchAgent本文方案运行在用户上下文无需 root随用户登录启动天然的用户级隔离。LaunchDaemon未覆盖以 root 或指定用户运行系统级服务开机启动需要管理员权限。单用户开发场景下LaunchAgent 在安全性上是更合适的选择。API Key 安全实践✅ 放在 shell 配置的环境变量中✅ 使用 macOS Keychain进阶方案✅ 收紧含密钥的 plist 权限chmod 600❌ 不要把 API key 提交到版本控制❌ 不要存放在世界可读的文件中。网络安全模板中--host 127.0.0.1使代理只绑定本机回环地址无外部网络暴露面。不要改为绑定0.0.0.0除非有防火墙规则配合。12. 进阶配置12.1 多实例第一个实例走安装脚本第二个实例手工创建不同 label 的 plist./install.sh --port 8787 cp com.headroom.proxy.plist.template ~/Library/LaunchAgents/com.headroom.proxy-2.plist # 编辑Label 改为 com.headroom.proxy-2端口改为 8788 launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy-2.plist注意 label 必须与 plist 文件名一致这是 launchd 的硬性要求。12.2 定时启动仅在工作时间运行向 plist 追加keyStartCalendarInterval/key dict keyHour/key integer9/integer keyMinute/key integer0/integer /dict12.3 资源限制keyHardResourceLimits/key dict keyNumberOfProcesses/key integer1/integer keyMemoryMax/key integer536870912/integer !-- 512 MB -- /dict13. Apple SiliconMPS GPU 嵌入 offloadApple Silicon 上proxy 的 memory 模块本地记忆向量检索可以把嵌入计算从默认 ONNX CPU 后端卸载到 Apple GPUMPS降低高负载下的 CPU 占用对无风扇机型如 M5 Air上 CPU 饱和导致的超时尤为有用。启用方式pip install headroom-ai[pytorch-mps] # [pytorch_mps] 写法亦可 export HEADROOM_EMBEDDER_RUNTIMEpytorch_mps在 LaunchAgent 下则写进 plist 的EnvironmentVariableskeyHEADROOM_EMBEDDER_RUNTIME/key stringpytorch_mps/string从源码看这条路径的精确行为memory_handler.py 中local 后端默认走onnx嵌入模型all-MiniLM-L6-v2384 维向量仅当HEADROOM_EMBEDDER_RUNTIME归一化后等于pytorch_mps时才会尝试导入sentence_transformers与torch并在torch.backends.mps.is_available()为真时切换到 torch 句向量后端跑在 GPU 上。任何一环缺失MPS 不可用、依赖未装都只是打印 warning 并回落到默认选择路径严格 opt-in默认行为不变。pyproject.toml中也标注该 extra 为 macOS-only、刻意排除在[all]之外。详细背景见 wiki/memory.md。14. 常见问题FAQQ为什么不用手动headroom proxyALaunchAgent 提供自动启动、崩溃恢复与完整的生命周期管理无需记住手动启动或保持终端窗口。Q能用于生产吗ALaunchAgent 面向开发环境。生产请使用 Docker、systemd 或云原生部署见下节。Q改配置后需要重启 proxy 吗A需要。修改 plist 后执行launchctl kickstart -k gui/$(id -u)/com.headroom.proxyQ能接多个 API provider 吗A本文的 LaunchAgent 配置面向 Anthropic。其他 provider 见 wiki/proxy.md 的配置选项。QApple SiliconM1/M2/M3兼容吗A完全兼容。ML 压缩Kompress通过headroom-ai[ml]opt-in在 Apple Silicon 上会自动检测 MPS。15. 生产部署与跨平台替代LaunchAgent 为单用户开发设计。生产环境建议评估LaunchDaemon系统级替代按用户 Agentplist 中增加资源限制CPU、内存与日志轮转通过外部工具做监控不同端口多实例做冗余。跨平台方案平台方案LinuxsystemdWindows任务计划程序或 NSSM容器化见 wiki/proxy.md 与 wiki/docker-install.md16. 相关文档wiki/proxy.md — 代理核心配置与功能wiki/configuration.md — 详细配置项wiki/ARCHITECTURE.md — Headroom 内部架构wiki/troubleshooting.md — 通用故障排查wiki/transforms.md — 压缩转换含[ml]extra 用法wiki/memory.md — Memory 模块与嵌入运行时/GPU offloadexamples/deployment/macos-launchagent/README.md — 部署目录快速上手【免费下载链接】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），仅供参考
