OSW 使用手册

常见问题

先分清「哪一层不对」，再对症处理：客户端到本地服务、本地服务到上游、还是本地服务自己。

客户端连不上

症状可能原因处理
PROXY_NOT_RUNNING / 无法连接到本地服务代理没启动托盘里点「启动服务」，或看主界面状态行。
Anthropic 客户端 404Base URL 多加了 /v1改成 http://127.0.0.1:9300（见协议）。
连接被拒端口不对或被占用确认监听端口（设置 → 网络 → 监听服务），必要时换端口。
REQUEST_REWRITE_RULE_FAILED重写规则拒绝了请求逐条关掉重写规则定位。

先跑一次 curl http://127.0.0.1:9300/v1/models：能返回模型列表，说明本地服务在跑，问题在客户端配置。

请求到了本地但没跑通

错误码含义处理
NO_MODEL_CONFIGURED没有可用的上游供应商去模型管理加供应商与模型。
NO_AVAILABLE_PROVIDER该逻辑模型没有已启用且可用的供应商模型在逻辑模型里添加可用模型，或等冷却结束。
INVALID_MODEL请求没有携带可用的模型名客户端里填一个非空模型名（不知道就用 default）。
MANUAL_MODEL_UNAVAILABLE手动指定的模型当前不适用于该协议换一个适用该协议的模型，或改用故障转移模式。
ALL_PROVIDERS_FAILED所有上游供应商都失败了展开请求记录的逐次尝试，看每次具体错什么。
UPSTREAM_MODELS_UNAVAILABLE拉取不到模型列表检查接口地址与协议是否匹配（供应商与模型）。

上游相关

错误码含义处理
UPSTREAM_AUTH_FAILED上游拒绝认证检查 API Key 是否正确、是否过期。
UPSTREAM_TIMEOUT上游请求超时看是否该调大超时，或该供应商在抖。
UPSTREAM_STREAM_ERROR流式响应意外中断流式开始后中断即中止，不会拼接；重试看看。
UPSTREAM_UNAVAILABLE上游不可用去统计分析看是否集中发生。

代理相关

错误码含义
SYSTEM_PROXY_RESOLUTION_FAILED无法解析系统代理设置。
OUTBOUND_PROXY_UNREACHABLE无法通过出站代理连接到目标地址。
OUTBOUND_PROXY_AUTH_REQUIRED出站代理要求认证。
OUTBOUND_PROXY_TUNNEL_REJECTED出站代理拒绝建立隧道。

先切直连排除代理

上游请求普遍失败时，把上游代理切回「不使用任何代理」快速确认是不是代理的问题。

客户端配置

错误码含义处理
CLIENT_CONFIG_CLIENT_NOT_SUPPORTED该客户端暂不支持自动填充在配置页下方手动编辑内容。
CLIENT_CONFIG_PARSE_FAILED内容无法按格式解析先修正原文件语法，再自动填充；或手动编辑。
CLIENT_CONFIG_WRITE_FAILED无法写入配置文件检查文件路径与权限。
CLIENT_CONFIG_PATH_NOT_ALLOWED配置文件不在可写入清单里只能填清单内的路径。

云同步

错误码含义处理
CLOUD_SYNC_NOT_CONFIGURED还没配好先保存凭据。
CLOUD_SYNC_AUTH_FAILED凭据被拒确认令牌有效且权限够用（只需 gist）。
CLOUD_SYNC_UNREACHABLE连不上云端检查网络与上游代理。
CLOUD_SYNC_REMOTE_FILE_MISSING远端还没这份文件先在已有配置的机器上备份一次。
CLOUD_SYNC_REMOTE_FILE_INVALID远端文件不是合法 JSON可能被手改坏了，重新备份覆盖。

服务自身

现象处理
DATABASE_UNAVAILABLE检查数据目录是否可写、磁盘是否满。
SECRET_STORE_UNAVAILABLE系统密钥库不可用，见本地优先与密钥。
启动失败、配置异常看运行日志。
版本行为不一致osw status 看是否有版本漂移（命令行）。

有些事 OSW 明确不做，先看不支持的边界再排查。

最后更新

构建来自Clarify