故障排查¶

先查看异常类型和 .hint。lovia 的异常会尽量明确指出问题来自调用配置、Provider、Tool，还是运行边界。

交互式排查时，可以开启框架日志：

from lovia import enable_logging

enable_logging("DEBUG")

提交问题时，请勿附带 API Key、完整提示词、私有 Tool 结果或环境变量转储。

未配置模型¶

现象：第一个 Turn 前抛出 UserError，通常是 Agent 没有模型或模型字符串无效。

给 Agent 传入有效的 model=，并提供当前端点的凭证和 Base URL。注意 Python 库不会自动加载 .env。具体配置见快速开始：配置模型。

现象	检查项
HTTP 401/403	API Key 是否属于当前端点，并已导出到当前进程
HTTP 404	Base URL 是否包含端点要求的前缀，通常是 `/v1`
Anthropic-compatible 端点拒绝请求体	模型名是否带 `anthropic:`，服务是否通过 `ANTHROPIC_BASE_URL` 配置
OpenAI-compatible 端点拒绝请求体	模型名是否不带前缀或带 `openai:`，服务是否通过 `OPENAI_BASE_URL` 配置
端点拒绝原生 JSON Schema	对需要 Prompt Fallback 的 OpenAI-compatible 端点传入 `supports_json_schema=False`

如果异常提供了 ProviderError.status_code、.vendor、.model 和 .retryable，请一并检查。端点方言规则详见 Provider 与模型。

Provider 客户端默认忽略环境中的 HTTP_PROXY / HTTPS_PROXY。如果确实需要这些代理，请设置 LOVIA_PROVIDER_TRUST_ENV=1。

私有 CA 使用 LOVIA_HTTP_CA_BUNDLE=/path/to/ca.pem。安装 Web 可选依赖后，也会使用操作系统信任存储。LOVIA_HTTP_INSECURE=1 会关闭证书校验，只应短暂用于本地诊断，不能用于生产环境。

依次检查：

离线测试中可以通过 ScriptedProvider.calls 检查模型实际收到的 View。如果 Tool 已运行但失败，普通异常会作为 Tool 结果返回给模型；RunCancelled 和 Run 级 BudgetExceeded 仍会结束 Run。

尽量保持 Schema 扁平、明确，检查 OutputValidationError.raw，并确认端点使用原生 JSON Schema 还是 Prompt Fallback。每次修复都会额外消耗一个 Turn。详见结构化输出。

已经完成的 Checkpoint run_id 是幂等键：复用它会重放旧结果，并忽略新输入。新工作应使用新的 run_id，对话连续性则使用稳定的 session_id。详见 Session 与 Checkpoint。

这是既定行为。事件迭代以 RunFailed 结束；只有 await handle.result() 才会抛出异常。消费完事件流后，务必等待最终结果。

默认绑定 127.0.0.1:8000，只能从本机访问。
serve() 绑定非回环地址时会要求或自动生成 Bearer token；create_app() 不会自动生成。内置服务仍不提供限流，多用户部署还需要自行接入认证和授权。
使用单 Worker；实时 Run 托管和审批状态属于进程内状态。
暴露服务前，关闭或严格限制可写 Workspace。

修改绑定地址前，请先阅读生产部署。

安装对应的 extra：

pip install "lovia[mcp]"   # MCP
pip install "lovia[ddg]"   # DuckDuckGo 搜索
pip install "lovia[web]"   # FastAPI 服务端和 UI

Tavily 搜索后端无需安装额外依赖，只需设置 TAVILY_API_KEY。

请包含：