docs/troubleshooting.md

常见问题

安装相关

Playwright 安装失败

uv run playwright install chromium
uv run playwright install-deps chromium

macOS 上 Playwright Sync API 报错

playwright._impl._errors.Error: It looks like you are using Playwright Sync API inside the asyncio loop.

设置环境变量：

export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
uv run autoteam rotate

Windows 启动时出现编码报错

如果历史 .env 文件含有 GBK / ANSI 编码或旧版内联注释格式，建议：

1. 将 .env 保存为 UTF-8
2. 确认配置值格式为：

AUTO_CHECK_INTERVAL=300  # 5 分钟

新版本已兼容 UTF-8 与尾部注释。

登录相关

Codex OAuth 登录失败：未获取到 authorization code

常见原因：

1. IP 被标记 — VPS 的 IP 被 OpenAI/Cloudflare 拦截，建议换住宅代理
2. Cloudflare 验证 — 浏览器环境被检测，需更新 Chromium 或切换网络
3. workspace 选择失败 — 页面结构变化，查看 screenshots/codex_04_*.png
4. 自动回调不可达 — 如果浏览器和 AutoTeam 不在同一台机器，localhost:1455 回调可能不会到达 AutoTeam，此时请改用手动粘贴回调 URL
5. 本地回调被代理拦截 — 如果启用了 PLAYWRIGHT_PROXY_URL，建议同时设置 PLAYWRIGHT_PROXY_BYPASS=localhost,127.0.0.1

登录后 plan 显示 free 而不是 team

通常是 state.json 中的 workspace_name 或 account_id 不正确。

检查：

cat state.json | python -m json.tool

确认：

• account_id 是有效 UUID
• workspace_name 是 Team 名称

验证码一直获取失败

• 检查 CloudMail 是否正常
• 检查邮箱域名 CLOUDMAIL_DOMAIN
• 系统会按 邮件 ID 跳过已经尝试过的验证码邮件，而不是按 6 位数字去重
• 如果浏览器长时间停在 email-verification，通常说明新的验证码邮件没有到达，或拿到的是旧邮件

轮转相关

rotate 没有补号

先看 get_team_member_count 是否失败。若返回 -1，说明 Team API 调用异常：

• 确认管理员已登录（state.json 有 session token）
• 确认 account_id 是有效 UUID

rotate 的目标人数为什么算不准

rotate 3 / fill 3 中的 3 指的是 Team 总人数目标。

也就是说：

• owner
• 外部成员
• 本地管理成员

都会一起计入这 3 个席位。当前自动轮转契约最多保留 1 owner + 2 managed children。

旧号一直被复用但额度不够

旧号复用前会先验证额度。

如果验证返回 auth_error（token 失效），系统会参考：

• last_quota
• quota_resets_at

判断是否值得继续复用。5h 重置时间过后，旧数据会视为过期。

Team 超员但没有清理

rotate 会自动清理超员成员。如果没生效，可手动执行：

uv run autoteam cleanup 3

CPA 同步相关

反向同步后本地 token 似乎“变旧了”

新版本会比较本地与 CPA 两侧文件的：

• last_refresh
• expired

只有 CPA 文件更“新”时，才会覆盖本地文件。

如果你怀疑历史版本已经把旧 token 写回本地，可以先重新登录目标账号，再执行：

uv run autoteam pull-cpa

查看日志里的：

• local_kept_newer
• cpa_duplicates_deleted
• local_duplicates_deleted

同账号在 CPA / 本地出现多个文件名不同的认证文件

新版本会在同步时按同账号去重：

• CPA 侧只保留一份
• 本地也只保留一份
• 并统一重写为本地命名规范

如果你怀疑之前版本遗留了重复文件，执行一次：

uv run autoteam pull-cpa

Docker 相关

容器一直重启

docker compose logs

通常是配置缺失或连通性验证失败。

data 目录没有写权限

入口脚本会自动 chmod -R 777 /app/data。若仍有问题：

sudo chmod -R 777 data/

重建容器后配置丢失

确认 docker-compose.yml 中有：

volumes:
  - ./data:/app/data

容器里访问不到宿主机 SOCKS5 代理

如果代理在宿主机上，比如 host.docker.internal:1080，请先确认容器内可以解析并访问宿主机代理地址；不同 Docker / Podman 环境的宿主机别名配置方式可能不同。

然后在 data/.env 中配置：

PLAYWRIGHT_PROXY_URL=socks5://host.docker.internal:1080
PLAYWRIGHT_PROXY_BYPASS=localhost,127.0.0.1

如果代理需要认证，可以直接写成：

PLAYWRIGHT_PROXY_URL=socks5://username:password@host.docker.internal:1080

Web 面板相关

页面显示 JSON parse error

说明后端返回了非 JSON 响应（通常是 500 错误）。查看后端日志定位具体异常。

操作按钮全部禁用

轮转 / 补满 / 清理等账号池操作需要先在「设置」页完成管理员登录。

Team 成员页的 owner 为什么没有“移出”按钮

account-owner 角色不会显示“移出”按钮，因为这类账号通常无法通过普通成员删除接口移出。

刷新后数据没更新

点击侧边栏底部的「刷新数据」按钮手动刷新。

配置保存后 401 创建邮箱失败

issue#1 错配的典型表现:配置时填的是 maillab 的 *_BASE_URL,但 MAIL_PROVIDER 还是默认的 cf_temp_email → 启动校验在 /admin/address catch-all 路由上误回 200,但创建邮箱阶段被 maillab 拒回 code:401。

修复路径见 配置说明 → ⚠️ 协议错配排查 与 SetupPage 4 步状态机。

邮箱后端

5 个常见错配场景与对应 error_code

场景	触发条件	报错 error_code	修复
issue#1 错配	选 cf_temp_email 但 base_url 是 maillab(或反向)	PROVIDER_MISMATCH	SetupPage 切换 provider 后重试
域名后台为空	maillab /setting/websiteConfig.domainList 为空	EMPTY_DOMAIN_LIST	在 maillab 后台先添加可用域名
凭据错误	管理员密码或 username/password 错	UNAUTHORIZED	重置密码或确认主账号
启用了登录验证码	maillab 后台 captcha = ON	CAPTCHA_REQUIRED(warning)	关闭 captcha 或改用 admin 直登
域名未授权	maillab 设置了 addVerify=1 拒绝创建非白名单域名	DOMAIN_REJECTED	在管理后台添加域名白名单

紧急逃生口

如果嗅探阻断了你已确认无误的配置,可以临时:

export AUTOTEAM_SKIP_PROVIDER_SNIFF=1
uv run autoteam api

仅在确诊误报时使用,生产环境不建议长期开启。

maillab 401 自愈

MaillabClient 业务方法被装饰器包裹,任何一次响应 code:401 会自动触发 re-login 并重试。如果重试仍 401,会抛 MaillabAuthFailed(日志关键字 [maillab] token 已自愈 表示自愈成功)。详细策略见 mail-provider-design.md §8。