故障排查
按现象排查常见问题：服务器起不来或端口被占用，401/403/400，模型不见了或 503，登录失效，账号都用完了，代理和网络错误，站点拒绝图片或工具。
先看症状对应的小节。每一条都列出你会看到的错误信息、原因和处理办法；错误信息是程序实际输出的原文，可以直接搜索。
先收集信息
| 去哪里看 | 能看到什么 |
|---|---|
运行 hoshimi serve 的终端 | 所有日志（输出到 stderr，不写日志文件）。HOSHIMI_LOG_LEVEL=DEBUG hoshimi serve 或 hoshimi serve --debug 输出更多细节 |
hoshimi check | 配置能否读取、能否通过校验，以及将要启用哪些渠道、多少账号 |
| 渠道 页 | 每个渠道的状态（需要处理）、账号状态（需要登录、已过期、暂停中、出错）、额度和最近的网络错误 |
| 用量 页的调用列表 | 每次调用的渠道、账号、尝试次数、错误代码和说明；勾选 仅失败 只看失败的 |
| 模型 页 | 每个模型的探测结果和是否被记为不可用 |
GET /api/v1/network/diagnostics | 每个渠道每类操作最近一次的网络结果，见网络与代理 |
服务器起不来
网关拒绝请求：401、403、400
这些错误来自 Hoshimi 自己的访问控制，请求还没有到达上游。它们的响应体形如 {"code": "…", "message": "…", "detail": {}}；如果是 OpenAI 格式的 {"error": {…}}，那是上游或路由返回的错误，见后面几节。
| 状态和代码 | 信息 | 原因与处理 |
|---|---|---|
401 model_api_key_required | A model API key is required | 访问 /v1/* 需要模型 API 密钥。用 Authorization: Bearer <模型 API 密钥> 或 x-api-key 发送。注意工具访问密钥不能用在这里 |
401 auth_required | A tool access key is required | 访问 /api/*、/docs 或 /openapi.json 需要工具访问密钥，只接受 Authorization: Bearer；模型 API 密钥和 x-api-key 不能用在这里 |
403 remote_not_allowed | Remote address not allowed | 客户端 IP 不在 security.allow_cidrs 中。把它的网段加进去 |
400 bad_host | Host not allowed | 服务器监听在回环地址，而请求的 Host 不是 localhost、127.0.0.1、::1 或监听地址。常见于反向代理转发了公开域名，或用自定义的本地域名访问。让代理转发 Host: 127.0.0.1:<端口> |
403 bad_origin | Cross-origin request refused | 浏览器从另一个来源发起写请求。把那个来源加入 security.allow_origins（需要工具访问密钥） |
403 bad_origin | Cross-site request refused | 请求没有 Origin，但浏览器标明它来自另一个站点 |
网页界面反复弹出 请输入工具访问密钥，或提示 工具访问密钥不正确。：密钥被改过，用当前的密钥重新登录。忘了密钥时，停止服务器，用 hoshimi config set server.access_token "<新密钥>" 设置一个新的（或设为 null 取消），再启动。详细规则见访问控制。
模型的问题
账号与登录
网络与代理
渠道请求失败时，错误信息形如 <渠道>: <类别>; <建议>，类别与网络诊断中的 kind 相同：
| 信息 | 原因与处理 |
|---|---|
…: proxy_error; check network configuration | 连不上配置的代理。确认代理在运行、地址和端口正确。配置的代理失败时不会退回直连 |
…: timeout; check network configuration | 连接或读取超时。站点可能需要代理才能访问，或代理太慢 |
…: connection_error; check network configuration | DNS、拒绝连接或 TLS 错误 |
…: challenge; complete_browser_authorization | 上游返回了 Cloudflare 质询。Hoshimi 不会自动通过质询；换一条线路，或稍后再试 |
…: edge_rejected; check_endpoint_and_network | 返回的是 HTML 拦截页。检查地址是否正确、线路是否被拦截 |
…: invalid_response; check_endpoint_and_network | 期待 JSON 却收到 HTML，多半是地址指向了网页而不是 API |
…: region_restricted; check_provider_availability | 站点不服务当前出口的地区。换一条其他地区的代理线路 |
…: client_restricted; check_client_compatibility | 站点只允许自己的客户端使用免费额度 |
…: signature_rejected; check_request_integrity | 站点拒绝了请求签名 |
这些都不会让账号作废，也不会触发换账号。
还要注意：
auto模式读取的是服务器进程启动时的环境变量；在另一个终端里设置的HTTPS_PROXY对已经运行的服务器无效。小写的https_proxy优先于大写。- 环境变量里的代理地址写错时，请求会报错而不是被忽略。
network.system_proxy只在 Windows 上有效。- SOCKS 代理对 Bedrock 的 AWS SDK 无效，Bedrock 需要 HTTP(S) 代理。
- 本机地址（如本地的 Ollama）始终直连，不经过代理。
配置方法见网络与代理。
站点拒绝图片或工具
数据与文件
仍然解决不了时，带上 HOSHIMI_LOG_LEVEL=DEBUG 下的日志、hoshimi version 的输出和复现步骤，到 GitHub Issues 反馈。日志可能包含账号 id 和主机名，分享前检查一遍。