故障排查

客户端找不到工具

• 确认 uvx 已安装且客户端能执行它
• 固定版本可避免升级后行为变化：uvx --from "usmartsg-mcp==1.1.0" usmartsg-mcp
• 该命令会保持运行等待 MCP stdio 消息，属正常行为，应由客户端拉起

工具列表里没有 place_order / modify_order

本地版默认注册全部 11 个工具。如果这两个缺失，依次检查：

1. 客户端配置的 env 里是否设置了 USMART_READONLY（值为 1、true、yes、on 时写工具不注册）
2. 是否设置了 USMART_PROFILE=directory（该值只注册 5 个查询工具）
3. 改完后是否重启了客户端，这些变量在进程启动时读取
4. 确认装的是 usmartsg-mcp

凭证检查失败

• 检查 USMART_HOME 指向的目录、config.json 是否存在且可读，以及文件权限
• 不要把真实凭证粘贴到聊天中
• 授权失败时，确认没有改动 config.json 里的 clientId 与 redirectUri；删掉 ~/.usmart/config.json 重启即可重新生成默认配置

OAuth 授权后仍提示未授权

• 确认 oauth_login_status 返回授权成功
• 确认 redirectUri 没有被改动（含端口、路径、大小写）
• 会话文件是 ~/.usmart/oauth_session.json，删除它等于本地登出

授权后浏览器打不开 localhost:5100

这通常是本机回调被代理、浏览器「仅 HTTPS」模式或安全软件拦截，不影响授权本身：地址栏里以 http://localhost:5100/callback 开头的完整链接仍然有效。

• 把该链接交给助手，让它用 oauth_login_status 的 callback_url 参数提交；链接一次性、10 分钟内有效，不要转发到别处
• 端口被占用时：Windows 用 netstat -ano | findstr :5100，macOS 用 lsof -i :5100 查占用进程
• 长期被拦截时，在客户端 env 里设置 USMART_OAUTH_SKIP_LISTENER=1，直接走手动回填

下单返回 100034

写接口要求 X-Request-Id 非空，代码会自动生成。若仍报错，确认没有用 extraHeaders 把它覆盖成空值。

下单返回 100073

这是平台风控的「价格偏离市价较大」提示，不是鉴权失败。人工核对价格后可传 force_entrust_flag=true 继续，该参数只应在核对后使用。