Headless

Headless 帮助文档

Headless 模式让 Hawa Code 在不启动终端交互界面的情况下运行，适合无 UI 环境、远程服务和自动化场景。需要说明的是，Headless 并不是通过 --headless 参数开启的，Hawa Code 提供以下两种无终端 UI 的用法：

  1. hcode server：Headless 常驻服务。进程常驻、不渲染终端 UI，内置 WebServer（HTTP + WebSocket），通过浏览器远程控制。这是官方的 Headless 运行模式。
  2. hcode -p "..."：单轮非交互模式。执行一次任务、将结果打印到标准输出后退出，适合管道和脚本调用，但不是常驻服务。

注意：配置项 headlessBrowser（无头浏览器）用于网页抓取渲染，与 Headless 运行模式无关，不要混淆。

1. 两种模式的区别

对比项 hcode server hcode -p "..."
运行方式 进程常驻，不退出 执行单轮后退出
交互能力 浏览器实时交互、审批工具调用 无交互，一次性输出
适用场景 远程常驻服务、无 UI 环境 CI/CD、脚本、管道调用
  • 需要”在远程机器上长期运行、通过浏览器使用完整 Agent 能力”时，使用 hcode server。
  • 需要”在流水线里跑一条命令、按退出码判断结果”时，使用 hcode -p。

2. 使用 hcode server 启动 Headless 服务

2.1 命令格式

hcode server [options]

2.2 参数说明

参数 说明
--port <n> Web 服务端口。默认读取 settings.webServer.port，未配置时为 3210；端口冲突时自动 +1
--host <addr> 绑定地址，默认 127.0.0.1。绑定非 loopback 地址（如 0.0.0.0）时必须同时配置 --token，否则启动失败
--token <token> 访问令牌。WebSocket 握手通过子协议或 ?token= 传递；REST 接口通过 Authorization: Bearer <token> 传递
--resume <id> 恢复历史会话（匹配日志完整路径或文件名后缀 <id>.jsonl），找不到时以退出码 1 退出
--cwd <path> 指定工作目录，默认为进程启动时的当前目录
--verbose 输出详细信息
--dangerously-skip-permissions 跳过所有权限确认，存在安全风险，详见注意事项

命令行参数的优先级高于 settings.json 中的 webServer 配置；Headless 模式下 webServer.enabled 会被强制视为开启。

2.3 示例

hcode server                                    # 本机 127.0.0.1:3210，浏览器打开即用
hcode server --port 4000                        # 指定端口
hcode server --host 0.0.0.0 --token mytok       # 对外暴露（必须带 token）
hcode server --resume 2026-11-06T...            # 恢复历史会话

3. 前置条件

  1. 先完成终端模式初始化：Headless 模式跳过 Onboarding、信任对话框、MCP 审批等依赖终端交互的步骤，因此请先在终端模式中运行一次 hcode，完成模型/API 等初始化配置。
  2. 模型与 API 配置：请确保模型和 API 已通过终端模式配置完成且有效，配置无效时启动或查询会报错。
  3. 权限与 token：绑定 loopback 地址（如 127.0.0.1）无需 token；绑定非 loopback 地址必须配置 --token，否则服务启动失败。
  4. 工作目录：进程会自动授予 --cwd 目录的读取权限，无需终端信任确认。

4. 启动后如何判断成功

启动成功的标志：

  1. 标准输出依次出现 Hawa Code headless server starting...、Tools, commands and MCP clients loaded, starting Web server...。
  2. 随后出现 Hawa Code headless server started 与访问 URL（例如 URL: http://127.0.0.1:3210）；若配置了 token，还会附带访问方式说明。实际端口以启动输出中的 URL: 为准（端口冲突时已自动 +1）。
  3. 进程保持常驻不退出，用浏览器打开该 URL 即可使用。

启动会话后，终端标准输出不再打印会话内容；会话消息以 JSONL 形式落盘，并通过 WebSocket 实时推送到浏览器。

5. 日志与排查

日志位于 UCODE_ROOT_DIR/projects/<项目目录>/ 下：

路径 内容
messages/*.jsonl 会话消息记录
log/*.log 运行日志
log/error-<日期>.log 错误日志
errors/*.txt 错误记录
mcp-logs-<server>/ 各 MCP Server 的日志

常见失败信号与退出码：

现象 说明
Failed to start WebServer: ... 并以退出码 1 退出 WebServer 启动失败，常见于非 loopback 未配 token、端口占用等
Session log not found: <id> 并以退出码 1 退出 --resume 指定的会话日志不存在
启动成功后进程被杀或退出 属于异常，请查看错误日志

排查顺序建议：先看标准输出中的提示 → 查看 log/error-*.log → 检查浏览器端是否因 token 被拒绝连接 → 必要时查看 MCP 日志。

6. CI/CD 与脚本场景

  • 优先使用 hcode -p：执行一次查询、将结果打印到标准输出后以退出码 0 退出，适合作为 CI 步骤按退出码判断结果。

    hcode -p "修复 lint 错误"
    echo "说明" | hcode -p        # 也支持标准输入

    标准输入无内容时进程以退出码 1 退出。

  • 常驻远程服务/无 UI 环境使用 hcode server：在服务器、Docker、systemd 中常驻运行，浏览器作为前端。

  • 批量与自动化任务：可通过 WebServer 的 REST / WebSocket API 程序化提交任务（REST 接口需携带 Bearer token）。

7. 注意事项

  1. 权限确认需要有人在浏览器侧审批：Headless 模式下唯一的审批通道是 Web 客户端；没有任何客户端响应时，工具确认约 5 分钟后超时。
  2. --dangerously-skip-permissions 的安全风险：该参数会跳过所有权限确认，Headless 路径未执行终端模式中的隔离环境校验，请务必仅在受信任的隔离环境中使用。
  3. 后台运行时注意标准输入：通过 systemd、docker run -d 等方式后台运行不受影响；但管道/ heredoc 场景（如 somecmd | hcode server）会因等待标准输入 EOF 而阻塞启动，后台运行请确保标准输入为 /dev/null 或设置 CI=true。
  4. 端口冲突自动处理：端口被占用时自动 +1 重试，实际端口以启动输出 URL: 行为准。
  5. token 安全：token 会出现在进程参数和 URL query param 中，多用户机器上注意进程列表泄露与浏览器历史泄露。
  6. 其他限制：无内建任务超时与失败重试；--resume 跨会话恢复的完整性未经充分验证；Headless 路径不执行 SessionStart hooks，依赖该 hook 注入上下文的用户请注意。