Headroom Python CLI 深度参考：从代理启动、持久化部署到内存管理与编码工具封装

本文以 Headroom 仓库的 CLI 参考文档 为主体，系统讲解 headroom 控制台脚本的全部核心命令：如何启动并调优优化代理（proxy）、管理持久化部署（install）、封装 Claude/Codex/Copilot 等编码工具（wrap），以及内存（memory）、评测（evals）、性能分析（perf）与压缩内容审查（inspect）等运维命令。读完本文，你可以独立完成一次 Headroom 代理的部署与验证，理解每个关键选项的默认值、环境变量与生效路径，并能结合 CLI 源码 核实帮助文档与实际行为的一致性。

时效性说明（继承原文档审计注记，2026-09-02）： 当前分支的 headroom --help 已列出约 30 个顶层命令，而本参考（及 wiki/cli.md）只完整记录了其中 15 个，未覆盖 agent-savings、audit-reads、capture、copilot-auth、dashboard、deploy、diff、doctor、init、loc、output-savings、recover、rollout、savings、sg、tools、update 等。文中 headroom proxy 与 headroom install apply 的选项表也是历史快照——proxy --help 如今已有近 90 个选项。请将其视为"锚定某一时点的参考"，在依赖任何具体选项前，以 headroom <cmd> --help 的实时输出为准。

全局行为：入口点与选项约定

两个等价的入口

Headroom CLI 由 Click 框架构建，提供两种等价调用方式：

• 控制台脚本：headroom
• Python 模块入口：python -m headroom.cli

这一映射在 pyproject.toml 的 [project.scripts] 段中声明为 headroom = "headroom.cli:main"；从 CLI 入口 可以看到，main 是一个 @click.group，同时通过 @click.version_option(get_version(), "--version", "-v") 注册版本选项。

全局选项

选项	作用域	含义
--help, -?	根、命令组、子命令	显示帮助并退出
--version, -v	仅根命令	显示 Headroom 版本并退出

这里有一个容易踩坑的细节：-v 是根级版本别名。在子命令内部（例如 headroom wrap claude -v），-v 保留其子命令含义（即 --verbose），而不是显示版本。-? 之所以在整棵命令树中都可用，是因为 入口文件 中的 _apply_help_aliases() 递归地把 --help/-? 注入了每个命令的 context_settings。

从源码结构看，根命令在解析任何子命令之前还做两件事（见 main.py）：

1. 将文件型配置（settings.json）通过 settings_store.apply_to_environ() 以 os.environ.setdefault 方式注入进程环境——显式导出的 shell 环境变量始终优先，且加载失败被静默吞掉，保证损坏的配置永远不阻塞 CLI；
2. 触发一次限流的后台版本检查（update_check.maybe_check_async()），供代理横幅等界面提示"有新版本"，update 子命令本身除外。

此外，memory 命令组是可选注册的：它依赖 numpy/hnswlib 等可选依赖，导入失败时该命令组不会出现在 --help 中；第三方命令则通过 headroom.cli_extension 入口点在最后注册，确保插件无法遮蔽内置命令。

命令索引

命令	用途	Docker 原生模式对等性
headroom install ...	安装并管理持久化部署	python-native；Docker 原生 wrapper 仅支持 persistent-docker 生命周期子集
headroom proxy	运行 Headroom 代理服务器	容器内原生
headroom learn	从历史工具调用失败中学习	容器内原生
headroom perf	汇总近期代理性能	容器内原生
headroom inspect	查看最近请求的压缩前后内容对比	容器内原生
headroom evals ...	运行内存评测工作流	容器内原生
headroom memory ...	查看与管理已存储的内存	容器内原生
headroom mcp ...	安装、检查、移除或运行 MCP 集成	容器内原生
headroom wrap claude	启动代理并拉起 Claude Code	host-bridged（宿主桥接）
headroom wrap copilot	启动代理并拉起 GitHub Copilot CLI	仅 python-native
headroom wrap codex	启动代理并拉起 Codex CLI	host-bridged
headroom wrap aider	启动代理并拉起 Aider	host-bridged
headroom wrap cursor	启动代理并打印 Cursor 配置指引	host-bridged
headroom wrap openclaw	安装并配置 OpenClaw 插件	host-bridged
headroom unwrap openclaw	禁用 Headroom OpenClaw 插件	host-bridged

下面按"当前分支 headroom --help 捕获快照"展示顶层命令全景（2026-09-02 捕获于本分支）：

Usage: headroom [OPTIONS] COMMAND [ARGS]...

  Headroom - The Context Optimization Layer for LLM Applications.

  Manage memories, run the optimization proxy, and analyze metrics.

  Examples:
      headroom proxy              Start the optimization proxy
      headroom memory list        List stored memories
      headroom memory stats       Show memory statistics
      headroom update             Update Headroom to the latest release

Options:
  -v, --version  Show the version and exit.
  -?, --help     Show this message and exit.

Commands:
  agent-savings   Render or verify Codex/Claude/Cursor token-savings...
  audit-reads     Audit Read-tool traffic for compression opportunities.
  capture         Capture and compare network traffic for Headroom...
  copilot-auth    Manage Headroom's GitHub Copilot OAuth token.
  dashboard       Open the Headroom savings dashboard in your browser.
  deploy          Deploy a turnkey local Headroom proxy and configure...
  diff            Run difftastic (structural diff).
  doctor          Check that the Headroom proxy and client routing are...
  evals           Evaluation commands (memory, compression robustness,...
  init            Install durable Headroom integrations for supported...
  inspect         Show original vs compressed content for recent proxy...
  install         Install and manage persistent Headroom deployments.
  learn           Learn from past tool call failures to prevent future ones.
  loc             Run scc (fast lines-of-code / repo-shape probe).
  mcp             MCP server for Claude Code integration.
  memory          Manage memories stored in Headroom.
  output-savings  Show estimated/measured output-token reduction from the...
  perf            Analyze proxy performance from logs.
  proxy           Start the optimization proxy server.
  recover         Recover agent state left in a temporary Headroom home.
  rollout         Inspect runtime feature-rollout policy (not package...
  savings         Show durable compression savings over time.
  sg              Run ast-grep (AST-aware structural search/replace).
  tools           Manage bundled CLI tool binaries (ast-grep, difft, scc).
  unwrap          Undo durable Headroom wrapping for supported tools.
  update          Update Headroom to the latest release.
  wrap            Wrap CLI tools to run through Headroom.

从 命令注册列表 可以看到，每个顶层命令大致对应 headroom/cli/ 下的一个独立模块（如 agent_savings.py、doctor.py、init.py、savings.py、tools.py、update.py 等），这也是上文 15 个重点命令"命令—模块"一一对应的来源。

headroom proxy：启动优化代理

headroom proxy
headroom proxy --port 8787
headroom proxy --mode cache

选项	默认值	含义
--host	127.0.0.1	绑定的主机接口
--port, -p	8787	绑定端口
--mode	运行时默认	优化模式：token、cache、token_mode、cache_mode、token_savings、cost_savings、token_headroom
--no-optimize	关	禁用优化，以直通（passthrough）模式运行
--no-cache	关	禁用语义缓存
--no-rate-limit	关	禁用限流
--retry-max-attempts	运行时默认 3	上游重试最大次数
--request-timeout-seconds	运行时默认 300	请求超时（秒）
--connect-timeout-seconds	运行时默认 10	上游连接超时
--anthropic-pre-upstream-concurrency	自动 max(2, min(8, cpu_count))	限制 /v1/messages 上同时进行的"上游前"工作（读请求体、深拷贝、第一级压缩、内存上下文查找、上游连接）。0 或负数表示不限制；任何正整数原样生效。目的是防止冷启动回放风暴挤占 /livez、/readyz 与新 Codex WS 建连
--anthropic-pre-upstream-acquire-timeout-seconds	15.0	当 Anthropic 上游前队列饱和时快速失败：等待超时的请求返回带 Retry-After 的 503，而不是一直挂起
--anthropic-pre-upstream-memory-context-timeout-seconds	2.0	请求仍持有上游前槽位期间，Anthropic 内存上下文查找的 fail-open 超时
--log-file	未设置	JSONL 日志输出路径
--budget	未设置	每日美元预算上限
--no-code-aware	关	禁用 AST 感知的代码压缩
--code-aware	关	在代理中启用代码感知压缩（env: HEADROOM_CODE_AWARE_ENABLED）
--no-read-lifecycle	关	禁用过期/被替代 Read 的压缩
--no-ccr	关	完全禁用 CCR——压缩内容中不注入检索标记，也不注入 headroom_retrieve 工具（有损、无恢复路径）
--no-ccr-proactive-expansion	关	禁用 CCR 的主动上下文扩展
--memory	关	启用持久用户内存
--memory-db-path	""	覆盖内存 DB 路径（帮助文本：{cwd}/.headroom/memory.db）
--no-memory-tools	关	禁用内存工具自动注入
--no-memory-context	关	禁用内存上下文自动注入
--memory-top-k	10	注入的内存条数
--learn	关	启用实时流量学习
--no-learn	关	显式禁用流量学习
--backend	anthropic	后端：anthropic、bedrock、openrouter、anyllm 或 litellm-*
--anyllm-provider	openai	anyllm 的后端提供方名
--anthropic-api-url	未设置	自定义 Anthropic 直通 API URL
--openai-api-url	未设置	自定义 OpenAI 直通 API URL
--anthropic-extra-headers	未设置	JSON 对象，合并进（并覆盖）转发的 Anthropic 请求头
--openai-extra-headers	未设置	JSON 对象，合并进（并覆盖）转发的 OpenAI 请求头
--gemini-api-url	未设置	自定义 Gemini 直通 API URL
--region	us-west-2	Bedrock / Vertex / 相关后端的云区域
--bedrock-region	未设置	已弃用的 Bedrock 区域覆盖
--bedrock-profile	未设置	Bedrock 使用的 AWS profile 名
--telemetry	关	加入匿名使用遥测（默认关闭）
--no-telemetry	关	强制关闭匿名遥测（本就是默认）

要点：

• --learn 隐含启用 memory，除非同时给出 --no-learn。
• 代理启动时还会读取一系列环境变量：HEADROOM_HOST、HEADROOM_PORT、HEADROOM_BUDGET、HEADROOM_MODE、HEADROOM_ANYLLM_PROVIDER、HEADROOM_ANTHROPIC_PRE_UPSTREAM_CONCURRENCY、HEADROOM_ANTHROPIC_PRE_UPSTREAM_ACQUIRE_TIMEOUT_SECONDS、HEADROOM_REQUEST_TIMEOUT、HEADROOM_ANTHROPIC_PRE_UPSTREAM_MEMORY_CONTEXT_TIMEOUT_SECONDS、ANTHROPIC_TARGET_API_URL、OPENAI_TARGET_API_URL、GEMINI_TARGET_API_URL、ANTHROPIC_TARGET_API_HEADERS、OPENAI_TARGET_API_HEADERS。CLI 标志优先于环境变量。
• Anthropic 上游前并发上限默认值有意偏保守（考虑 CPU/ONNX 重负载）。大规格容器可以先在 /readyz 或 /debug/warmup 上核对解析出的运行时数值，再考虑调高。

延伸阅读：代理服务器、配置。

源码中的最新选项（快照之外）

由于上表是历史快照，proxy 命令实现 中还能看到一批较新的选项，供你对照实时 --help：

• 进程与连接池：--workers（Uvicorn 工作进程数，默认 1，env HEADROOM_WORKERS）、--limit-concurrency（默认 1000，超过即返回 503）、--max-connections（默认 500）、--max-keepalive（默认 100）、--keepalive-expiry（默认 90 秒）、--http2/--no-http2（默认开；关闭可强制 HTTP/1.1，规避高并发流取消时的共享连接 TLS 损坏）、--http-proxy（仅用于上游请求）。
• 预算细化：--budget-period（hourly/daily/monthly，默认 daily）、--budget-estimated-basis（count/ignore/block，控制 Headroom 自身估算出的花费如何计入预算）。
• 重试与超时：--retry-base-delay-ms（默认 1000）、--retry-max-delay-ms（默认 30000）、--write-timeout-seconds（默认 150）、--anthropic-buffered-request-timeout-seconds（默认 600）。
• 压缩开关族：--lossless（无 CCR 无损模式，不产出任何检索标记）、--ccr-inline-resolve（在非流式响应路径上内联解析 <<ccr:...>> 标记，适用于无工具调用回路的调用方，如作为 LiteLLM 护栏）、--compressor（把激活的内置压缩器限定到指定集合：smart_crusher、kompress、code_aware、search、log、tabular、config、html、image）、--disable-kompress 及其按管线（Anthropic/OpenAI）覆盖的变体、--target-ratio（覆盖 Kompress 的文本保留比例，越小越激进）、--protect-tool-results（永不进行有损压缩的工具名列表，并与内置默认合并）、--code-graph（索引当前目录并通过 codebase-memory-mcp 监听重索引）。
• 限流：--rpm（默认 60）、--tpm（默认 100000）。
• Read 生命周期实验项：--read-maturation 系列（实验性，需 HEADROOM_ROLLOUT_CHANNEL=beta），含 --read-maturation-quiesce-turns（默认 5）、--read-maturation-max-hold-turns（默认 25）、--read-maturation-min-size-bytes（默认 2048）。
• 记忆分区：--memory-storage（project/user/global，默认 project——每个工作区独立 SQLite，避免跨项目串味）、--memory-project-root。
• 日志与调试：--log-messages（完整消息日志，内容进入日志文件并通过实时 feed 端点提供；注意可能记录敏感数据）、--codex-wire-debug（本地 Codex 线级快照）。

一个值得注意的实现细节：在 proxy 启动前的内存调优逻辑 中，macOS 上 CLI 会一次性 re-exec 自身以应用 MallocAggressiveMadvise=1/MallocLargeCache=0，解决长生命周期代理 RSS 只增不减的问题；HEADROOM_MALLOC_TUNING=0 可禁用该 re-exec。该逻辑会先校验当前进程确为 headroom 或 python -m headroom.cli 入口，避免误杀嵌入式调用方的进程。

headroom learn：从工具调用失败中学习

headroom learn
headroom learn --apply
headroom learn --agent codex --all

选项	默认值	含义
--project	当前项目解析	目标项目路径
--all	关	分析所有发现的项目
--apply	关	写出建议（默认仅 dry-run 输出）
--agent	auto	智能体来源：auto、内置（claude、codex、gemini）或插件提供的名称
--model	自动检测	分析使用的 LLM 模型

要点：

• --agent auto 会扫描所有检测到的智能体数据源。
• 省略 --project 时，Headroom 从当前目录向上解析项目根。
• 外部智能体集成通过 headroom.learn_plugin 入口点注册。

延伸阅读：失败学习。

headroom perf：性能汇总

headroom perf
headroom perf --hours 24
headroom perf --raw

选项	默认值	含义
--hours	168.0	时间窗口（小时）
--raw	关	打印原始 PERF 记录而非汇总报告

该命令读取 ${HEADROOM_WORKSPACE_DIR}/logs/proxy.log（默认 ~/.headroom/logs/proxy.log——见文件系统约定）。从 perf 命令实现 看，报告涵盖 Token 节省与压缩效果、缓存命中率与前缀稳定性、变换与路由分布、TOIN 学习状态，以及可执行的改进建议；此外还有原文档未列出的 --format 选项（text/json/csv，默认 text），例如 headroom perf --format csv --hours 24 > last-24h.csv 可直接导出按模型聚合的表格数据。

headroom inspect：看到压缩到底改了什么

headroom inspect                 # 检查最近一条请求
headroom inspect --last 5       # 检查最近 5 条请求
headroom inspect --full          # 包含未改动消息
headroom inspect --format json   # 原始 feed，便于管道到其它工具

选项	默认值	含义
--port / -p	8787	要查询的代理端口（env: HEADROOM_PORT）
--last	1	显示最近几条请求
--format	text	text 渲染高亮 diff；json 输出原始 feed
--full	关	包含压缩器未改动的消息

inspect 的意义在于：Headroom 的遥测给出的是量化数据（token 数、比例），而它让你看见压缩器具体改了什么，从而建立对压缩的信任、定位质量回归。它通过查询运行中代理的 loopback /transformations/feed 端点工作，因此代理必须以 --log-messages（或 --log-file）启动，才能捕获压缩前后的消息快照。从 inspect 实现 看，text 模式对每条被改动的消息使用标准库 difflib.unified_diff 渲染统一 diff（删除行红色、新增行绿色），不引入任何新依赖；若某条请求没有任何逐消息内容变化，会明确提示"节省来自结构级/变换级编辑"。

headroom evals：内存评测命令组

headroom evals memory

运行 LoCoMo 内存评测基准。

headroom evals memory -n 3
headroom evals memory --answer-model gpt-4o --llm-judge

选项	默认值	含义
--n-conversations, -n	全部可用	评测的对话数
--categories	基准默认	逗号分隔的类别
--include-adversarial	关	包含第 5 类/不可回答的问题
--top-k	10	每个问题检索的内存数
--f1-threshold	0.5	正确性阈值
--answer-model	未设置	答案生成模型
--llm-judge	关	使用 LLM-as-judge 打分
--judge-provider	litellm	裁判提供方：openai、anthropic、litellm、simple
--judge-model	gpt-4o	裁判模型
--output, -o	未设置	保存 JSON 结果到路径
--no-extract	关	禁用 LLM 内存抽取
--extraction-model	gpt-4o-mini	内存抽取模型
--pass-all	关	要求所有检查都通过
--parallel	10	并行工作数
--debug	关	启用调试输出

headroom evals memory-v2

运行带 LLM 控制工具的 V2 内存评测流程。

headroom evals memory-v2
headroom evals memory-v2 --save-model gpt-4o-mini --llm-judge

选项	默认值	含义
--n-conversations, -n	全部可用	评测的对话数
--categories	基准默认	逗号分隔的类别
--include-adversarial	关	包含对抗性问题
--f1-threshold	0.5	正确性阈值
--save-model	gpt-4o-mini	持久化内存时使用的模型
--answer-model	gpt-4o	答案模型
--max-results	10	最大工具结果数
--no-graph	关	禁用图使用
--llm-judge	关	使用 LLM-as-judge 打分
--judge-model	gpt-4o	裁判模型
--output, -o	未设置	保存 JSON 结果
--parallel	5	并行工作数
--debug	关	启用调试输出

存在两个隐藏的兼容 shim 对应旧命令路径：headroom memory-eval 与 headroom memory-eval-v2。它们有意不出现在常规使用文档中。

headroom memory：内存管理命令组

该命令组只在可选内存依赖（numpy/hnswlib）导入成功时注册——见 入口文件的条件导入。

headroom memory list

headroom memory list
headroom memory list --scope USER --since 7d
headroom memory list -q "budget"

选项	默认值	含义
--db-path	若存在则 ./.headroom/memory.db，否则 ~/.headroom/memory.db	内存数据库路径
--limit, -n	50	最多显示条数
--session, -s	未设置	按会话 ID 过滤
--scope	未设置	USER、SESSION、AGENT 或 TURN
--since	未设置	年龄过滤，支持 7d、2w、1m 等时长语法
--search, -q	未设置	内容搜索查询

headroom memory show <memory_id>

headroom memory show 1234abcd
headroom memory show 1234abcd --json

参数/选项	默认值	含义
memory_id	必填	完整或部分内存 ID
--db-path	同上解析规则	内存数据库路径
--json	关	输出原始 JSON

headroom memory stats

headroom memory stats

选项	默认值	含义
--db-path	同上解析规则	内存数据库路径

headroom memory edit <memory_id>

headroom memory edit 1234abcd --content "Updated note"
headroom memory edit 1234abcd --importance 0.9

参数/选项	默认值	含义
memory_id	必填	完整或部分内存 ID
--db-path	同上解析规则	内存数据库路径
--content, -c	未设置	新的内存内容
--importance, -i	未设置	新的重要性分数（0.0 到 1.0）

--content 与 --importance 至少提供一个。

headroom memory delete <memory_ids...>

headroom memory delete 1234abcd 5678efgh
headroom memory delete 1234abcd --force

参数/选项	默认值	含义
memory_ids...	必填	一个或多个内存 ID
--db-path	同上解析规则	内存数据库路径
--force, -f	关	跳过确认

headroom memory prune

headroom memory prune --older-than 30d --dry-run
headroom memory prune --scope SESSION --force

选项	默认值	含义
--db-path	同上解析规则	内存数据库路径
--older-than	未设置	年龄阈值
--scope	未设置	范围过滤：USER、SESSION、AGENT、TURN
--low-importance	未设置	重要性截断值
--session, -s	未设置	会话 ID 过滤
--dry-run	关	只展示将被移除的内容
--force, -f	关	跳过确认

必须至少提供一个过滤条件，多个过滤条件以 AND 语义组合。

headroom memory purge

headroom memory purge --confirm

选项	默认值	含义
--db-path	同上解析规则	内存数据库路径
--confirm	关	必需的确认标志

headroom memory export / import

headroom memory export
headroom memory export --output export.json
headroom memory import export.json
headroom memory import export.json --force

参数/选项	默认值	含义
file（import）	必填	包含导出内存的 JSON 文件
--db-path	同上解析规则	内存数据库路径
--output, -o（export）	stdout	输出路径
--force, -f（import）	关	跳过确认

import 期望 JSON 数组；格式错误的条目会被跳过。

headroom mcp：MCP 服务管理

headroom mcp install

headroom mcp install
headroom mcp install --proxy-url http://127.0.0.1:9000

选项	默认值	含义
--proxy-url	http://127.0.0.1:8787	写入 MCP 配置的代理 URL
--force	关	覆盖已有的 Headroom MCP 配置

headroom mcp uninstall / status

headroom mcp uninstall
headroom mcp status

uninstall 从 Claude 配置中移除 Headroom MCP 服务条目；status 检查 MCP SDK 可用性、Claude 配置状态与代理可达性。

headroom mcp serve

headroom mcp serve
headroom mcp serve --proxy-url http://127.0.0.1:9000 --debug

选项	默认值	含义
--proxy-url	http://127.0.0.1:8787	代理 URL（同时读取 HEADROOM_PROXY_URL）
--direct	关	禁用 stdio 传输包装
--debug	关	启用调试日志

serve 属于公开 CLI 的一部分，但通常由 MCP 宿主工具调用，而非由人直接运行。延伸阅读：MCP 工具。

headroom install：持久化部署管理

headroom install apply

headroom install apply --preset persistent-service --providers auto
headroom install apply --preset persistent-task --providers manual --target claude --target codex
headroom install apply --preset persistent-docker --scope user

选项	默认值	含义
--preset	persistent-service	生命周期预设：persistent-service、persistent-task 或 persistent-docker
--runtime	python	service/task 安装使用的运行时：python 或 docker
--scope	user	配置作用域：provider、user 或 system
--providers	auto	目标选择模式：auto、all 或 manual
--target	可重复	与 --providers manual 搭配使用的工具目标（claude/copilot/codex/aider/cursor/openclaw）
--profile	default	部署 profile 名
--port, -p	8787	持久化代理端口
--backend	anthropic	托管运行时的代理后端
--anyllm-provider	未设置	与 --backend anyllm 搭配的提供方名
--region	未设置	云区域覆盖
--mode	token	代理优化模式
--memory	关	在托管运行时中启用持久内存
--telemetry	关	加入匿名遥测（默认关闭）
--no-telemetry	关	强制关闭遥测（本就是默认）
--image	ghcr.io/headroomlabs-ai/headroom:latest	Docker 运行时使用的镜像

apply 的完整流程：把 manifest 存到 ${HEADROOM_WORKSPACE_DIR}/deploy/<profile>/manifest.json（默认 ~/.headroom/deploy/<profile>/manifest.json），应用受管的工具配置，启动所选运行时，并等待 readyz 就绪。

Docker 原生的宿主 wrapper 只暴露 persistent-docker 场景下的较窄 headroom install 子集：apply、status、start、stop、restart、remove。这些流程保持相同的端口与 manifest 行为，但会有意拒绝 persistent-service、persistent-task 以及 --scope、--providers、--target 等 provider 变更标志。

生命周期子命令

headroom install status --profile default   # 显示 profile、预设、运行时、supervisor 类型、作用域、端口、运行状态、就绪性与 /health 中的后端
headroom install start                      # 启动已安装的部署 profile（不重新应用变更）
headroom install stop                       # 停止托管运行时
headroom install restart                    # 停止并启动所选 profile
headroom install remove                     # 停止运行时、移除 supervisor 产物、回滚受管配置、删除 manifest

延伸阅读：持久化安装。

headroom wrap / headroom unwrap：封装编码工具

共享语义

• --port（如可用）默认 8787
• --no-proxy 跳过代理启动，假定已存在代理
• --learn 启用实时流量学习
• -v、--verbose 表示详细输出（注意与根级版本别名的区别）
• 隐藏的 --prepare-only 供内部 Docker 原生桥接流程使用，不写入常规文档

headroom wrap claude

headroom wrap claude
headroom wrap claude --resume <session-id>
headroom wrap claude --port 9999

选项/参数	默认值	含义
--port, -p	8787	代理端口
--no-proxy	关	复用已有代理
--learn	关	启用实时流量学习
--verbose, -v	关	详细输出
claude_args...	透传	附加的 Claude Code 参数

要求宿主上存在 claude 二进制。

headroom wrap codex

headroom wrap codex
headroom wrap codex -- "fix the bug"
headroom wrap codex --backend anyllm --anyllm-provider groq

选项/参数	默认值	含义
--port, -p	8787	代理端口
--no-proxy	关	复用已有代理
--learn	关	启用实时流量学习
--backend	未设置	代理后端覆盖
--anyllm-provider	未设置	anyllm 提供方覆盖
--region	未设置	云区域覆盖
--verbose, -v	关	详细输出
codex_args...	透传	附加的 Codex CLI 参数

要求宿主上存在 codex 二进制。

headroom wrap copilot

headroom wrap copilot -- --model claude-sonnet-4-20250514
headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4o

选项/参数	默认值	含义
--port, -p	8787	代理端口
--no-proxy	关	复用已有代理
--learn	关	启用实时流量学习
--backend	未设置	代理后端覆盖
--anyllm-provider	未设置	anyllm 提供方覆盖
--region	未设置	云区域覆盖
--provider-type	auto	强制 Copilot BYOK 提供方类型（anthropic 或 openai）
--wire-api	未设置	OpenAI 风格后端的 OpenAI 线级 API 覆盖
--verbose, -v	关	详细输出
copilot_args...	透传	附加的 Copilot CLI 参数

要求宿主上存在 copilot 二进制。当在请求端口上已存在匹配的持久化部署时，wrap copilot 会先复用或恢复它，再回退到临时代理。

headroom wrap aider

headroom wrap aider
headroom wrap aider -- --model gpt-4o
headroom wrap aider --backend litellm-vertex --region us-central1

选项/参数	默认值	含义
--port, -p	8787	代理端口
--no-proxy	关	复用已有代理
--learn	关	启用实时流量学习
--backend	未设置	代理后端覆盖
--anyllm-provider	未设置	anyllm 提供方覆盖
--region	未设置	云区域覆盖
--verbose, -v	关	详细输出
aider_args...	透传	附加的 Aider 参数

要求宿主上存在 aider 二进制。

headroom wrap cursor

headroom wrap cursor
headroom wrap cursor --port 9999

选项	默认值	含义
--port, -p	8787	代理端口
--no-proxy	关	复用已有代理
--learn	关	启用实时流量学习
--verbose, -v	关	详细输出

该命令打印 Cursor 配置说明，并在代理保持存活期间等待。它不会直接启动 Cursor。

headroom wrap openclaw

headroom wrap openclaw
headroom wrap openclaw --plugin-path ./plugins/openclaw

选项	默认值	含义
--plugin-path	未设置	本地插件源目录
--plugin-spec	headroom-ai/openclaw	NPM 插件规格
--skip-build	关	跳过本地 npm install/构建步骤
--copy	关	复制插件而非链接安装
--proxy-port	8787	Headroom 代理端口
--startup-timeout-ms	20000	代理启动超时
--gateway-provider-id	可重复	经 Headroom 路由的 OpenClaw 提供方 ID
--python-path	未设置	Python 启动器覆盖
--no-auto-start	关	禁用插件自动启动行为
--no-restart	关	不重启 OpenClaw 网关
--verbose, -v	关	详细输出

要求宿主上存在 openclaw 二进制；本地源码模式可能还需要 npm。在 Docker 原生模式下，已安装的宿主 wrapper 驱动宿主 openclaw CLI，而插件从 PATH 中自动启动宿主 headroom wrapper。

headroom unwrap openclaw

headroom unwrap openclaw
headroom unwrap openclaw --no-restart

选项	默认值	含义
--no-restart	关	不重启 OpenClaw 网关
--verbose, -v	关	详细输出

该命令禁用 Headroom OpenClaw 插件并恢复旧的上下文引擎槽位。

Docker 原生对等矩阵

该矩阵对比 Python CLI 契约与本分支新增的 Docker 原生宿主 wrapper：

• native in container（容器内原生） —— 命令完全在 Headroom 容器内运行
• host-bridged（宿主桥接） —— Headroom 跑在 Docker 里，但被封装的外部工具仍在宿主上运行

命令路径	Python CLI	Docker 原生 wrapper	对等性
headroom proxy	native	容器内原生	full
headroom learn	native	容器内原生	full
headroom perf	native	容器内原生	full
headroom evals memory	native	容器内原生	full
headroom evals memory-v2	native	容器内原生	full
headroom memory ...	native（内存依赖可用时）	容器内原生	full
headroom mcp install	native	容器内原生	full
headroom mcp uninstall	native	容器内原生	full
headroom mcp status	native	容器内原生	full
headroom mcp serve	native	容器内原生	full
headroom install apply|status|start|stop|restart|remove	native	仅 persistent-docker 的 Docker 原生 wrapper；compose 仍是替代方案	partial
headroom wrap claude	native	宿主桥接	partial
headroom wrap copilot	native	Docker 原生 wrapper 未实现	none
headroom wrap codex	native	宿主桥接	partial
headroom wrap aider	native	宿主桥接	partial
headroom wrap cursor	native	宿主桥接	partial
headroom wrap openclaw	native	宿主桥接	partial
headroom unwrap openclaw	native	宿主桥接	partial

关于 Docker 原生执行模型本身，参见 Docker 原生安装；持久化 service/task/docker 生命周期管理参见 持久化安装。

隐藏与仅兼容的命令路径

以下内容存在于代码中，但有意从常规用户文档中排除：

• headroom memory-eval
• headroom memory-eval-v2
• wrap 子命令上隐藏的内部 --prepare-only 标志

如果你需要描述运维行为或调试内部 wrapper 流程，请直接参考 wrap 实现 的源码。

小结：如何可靠地使用这份参考

1. 以实时 --help 为最终依据：本文（连同 wiki/cli.md）中的选项表是锚定 2026-09-02 分支的快照，而 proxy 命令实现 中可见的选项数量已经远超文档表格；
2. 理解环境变量回退链：几乎所有代理选项都有对应的 HEADROOM_* 环境变量，CLI 标志优先级更高，这让 Docker 部署与交互式调试可以共享同一套调优参数；
3. 按职责定位源码模块：headroom/cli/ 下每个顶层命令对应一个模块文件（proxy.py、learn.py、perf.py、inspect.py、memory.py、mcp.py、install.py、wrap.py、evals.py），需要确认某选项的确切行为时，直接读对应模块比读任何快照文档都更可靠；
4. 验证压缩质量用 inspect、验证系统行为用 perf：前者展示逐消息的 diff 级证据，后者给出聚合的节省率与缓存命中率，两者共同构成对代理行为的端到端信任链。