常见问题

headroom: command not found

原因： Ubuntu 24.04 PEP 668 阻止 pip 系统级安装。

解决：

pip3 install headroom-ai fastapi uvicorn 'httpx[http2]' transformers \
   -i https://pypi.tuna.tsinghua.edu.cn/simple \
   --break-system-packages --ignore-installed

原因： headroom-ai 的依赖未完全安装。

解决：

pip3 install fastapi uvicorn 'httpx[http2]' transformers \
   -i https://pypi.tuna.tsinghua.edu.cn/simple \
   --break-system-packages --ignore-installed

Headroom proxy 启动后立即退出

原因： 缺少 h2 包（HTTP/2 支持）。

解决：

pip3 install h2 -i https://pypi.tuna.tsinghua.edu.cn/simple --break-system-packages

查看日志定位原因：

tail -20 /var/log/headroom-proxy.log

Claude Code 发消息但 stats 没变化

原因： ANTHROPIC_BASE_URL 未注入到 Claude Code 进程环境，请求没经过代理。

排查：

echo $ANTHROPIC_BASE_URL    # 如果为空，说明环境变量没生效
 source /root/.bashrc        # 重新加载
 claude                      # 再试

或直接在命令行传入：

ANTHROPIC_BASE_URL=http://localhost:8787 claude

验证部署状态

headroom --version                    # Headroom CLI
 claude --version                      # Claude Code
 curl http://localhost:8787/readyz     # 代理健康
 echo $ANTHROPIC_BASE_URL              # 应为 http://localhost:8787
 echo $ANTHROPIC_TARGET_API_URL        # 应为 https://api.modelarts-maas.com/anthropic
 echo $ANTHROPIC_AUTH_TOKEN             # 应为 MaaS API Key