排查 Holon 任务问题

任务卡住通常就那么几种。按你遇到的现象往下走，做检查，再进入下一步。运行时字段和端点见参考。

Daemon 问题

Daemon 启动不了

症状： holon daemon start 卡住或报错退出。

排查清单：

# 1. 检查是否已有实例在运行
holon daemon status

# 2. 查看最近的 daemon 日志
holon daemon logs

# 3. 重启 daemon
holon daemon restart

如果 daemon 绑定端口失败，换一个端口：

holon daemon start --port 8788

启动后 daemon 状态显示“已停止”

查看 daemon 日志里的崩溃信息：

holon daemon logs

常见原因：

端口已被其他进程占用
默认模型缺少凭据或凭据无效
磁盘空间不足，或 ~/.holon/ 权限不足

凭据与模型问题

“No available model” 或凭据错误

最快的修复方式是运行交互式引导向导：

holon onboard

运行诊断工具：

holon config doctor

它会显示哪些模型可用、配置了哪些凭据，以及每个提供商/模型组合的详细可用状态。

API key 未被识别

确认凭据已保存：
```
holon config credentials list
```
环境变量鉴权时，检查变量是否已设置：
```
echo $DEEPSEEK_API_KEY
```
确认提供商已注册，且凭据配置匹配：
```
holon config providers list
```
使用自定义提供商时，检查 --credential-profile 是否与 config credentials set 时用的配置一致：
```
holon config providers get my-provider
```

模型报错或行为异常

确认模型可用：
```
holon config models list
```
检查当前默认模型：
```
holon config get model.default
```

尝试切换到其他模型：

holon config set model.default "anthropic@default/claude-sonnet-4-6"

Agent 问题

Agent 不响应

检查 Agent 是否存在：
```
holon agent model get my-agent
```

用全新的单次运行试试：

holon run "test" --agent my-agent --max-turns 1

Agent 使用了错误的模型

检查 Agent 是否有单独的模型覆盖：

holon agent model get my-agent

清除覆盖，回退到全局默认：

holon agent model clear my-agent

配置问题

配置改动没有生效

确认键值设置正确：
```
holon config get <KEY>
```
检查键名有没有拼写错误：
```
holon config schema
```
如果是直接编辑 ~/.holon/config.json 做的改动，验证 JSON：
```
holon config list
```
配置改动后重启 daemon：
```
holon daemon restart
```

配置被重置为默认值

检查是否设置了 HOLON_HOME，它会改变配置文件位置：

echo $HOLON_HOME

TUI 问题

TUI 显示错乱

尝试禁用备用屏幕：

holon tui --no-alt-screen

或在配置中设置：

holon config set tui.alternate_screen never

TUI 无法连接 daemon

确认 daemon 正在运行：holon daemon status
检查 daemon 的访问模式：本地 TUI 连接要求 holon daemon start --access local

远程连接时，确认 --connect URL 和 --token 正确：

holon tui --connect https://your-server:8787 --token "your-token"

日志与诊断

查看 Agent 任务输出

任务输出存放在 ~/.holon/agents/<agent-id>/task-output/ 下。每个任务有一个以任务 ID 命名的 .log 文件。

完整系统诊断

holon config doctor

它会报告：默认模型、回退模型、各模型可用性及原因、提供商设置、凭据状态和重试策略。

查看运行时配置

# 完整配置转储
holon config list

# 所有可用键，含默认值和说明
holon config schema

运行时性能诊断

Holon 跨轮次生命周期各阶段、提供商交互、工具执行和持久化跟踪细粒度性能指标。这些指标是累积的，覆盖从 daemon 启动以来的整个进程生命周期。

获取指标

curl http://127.0.0.1:7878/api/control/runtime/performance

响应是按类别分组的 JSON 快照：

指标分组

分组	关键指标	关注点
`turn.*`	`turn.total`, `turn.context_build`, `turn.provider_round`, `turn.tool_execution`, `turn.cleanup`	上下文构建变慢（提示词拼装增长），工具时间占比过高
`provider.*`	`provider.request_build`, `provider.round_total`, `provider.retry`	重试次数高或延迟指向提供商问题
`tool.execution`	累积工具耗时	找出 `avg_ms` 异常高的工具
`storage.*`	`storage.append_event`, `storage.persist_state`	持久化变慢说明数据库有压力
`projection.agent_state.*`	`tasks`, `timers`, `work_items`, `waiting_intents`, `external_triggers`	每个 Agent 的状态投影开销
`projection.agents_list`	Agent 列表投影耗时	仪表盘/API 列表延迟
`http.*`	各路由 HTTP 耗时	慢端点、大负载
`scheduler.*`	`scheduler.poll.all`, `.message`, `.idle`, `.stopped`	调度器健康度（空闲比例、轮询延迟）

每个指标条目包含：

字段	说明
`count`	该阶段的总调用次数
`total_ms`	累积墙钟时间
`max_ms`	单次最慢调用
`avg_ms`	平均调用耗时

常见诊断模式

turn.tool_execution 偏高 — 某个工具占用了大部分轮次时间。运行 holon debug latency 找出是哪个工具。

provider.retry 频繁 — 模型提供商在返回错误或超时。检查提供商日志（holon daemon logs）和网络连通性。

turn.context_build 增长 — 提示词拼装变慢，通常说明累积的历史需要压缩。对照配置的压缩阈值检查 Agent 的 total_message_count。

scheduler.poll.idle 比例偏高 — 没有 Agent 处于唤醒状态时属正常。如果有 Agent 有待处理工作，检查唤醒提示和等待条件。

重置指标

指标在 daemon 重启时重置。想观察某个特定场景时，重启 daemon、复现问题，然后抓取快照：

holon daemon restart && sleep 2 && curl http://127.0.0.1:7878/api/control/runtime/performance

另见

配置参考 — 配置键与凭据管理
运行你的第一个 Holon 任务 — 常见任务示例
快速开始 — 首次运行流程