问题排查

1. 点击页面顶部的安装 WSL/Ubuntu 操作，并允许管理员权限。
2. Windows 要求重启时先保存其他工作，再重启电脑。
3. 重启后打开 Ubuntu，按提示创建一次 Linux 用户名和密码。
4. 回到 Woodox 的 “Agent 设置”点击 “重新检查”。

自动安装失败、出现十六进制错误代码或需要手工安装时，按WSL/Ubuntu 说明书的错误代码表逐层处理。

1. 点击 “打开 Ubuntu 完成初始化”。
2. 创建 Linux 用户名和密码；输入密码时屏幕不显示字符是正常现象。
3. 看到 Linux 命令提示符后关闭窗口，再回客户端重新检查。

• bubblewrap 只在选择 Codex 时是必需项；Kimi/Qwen 不会因为缺少它而被阻止。
• 先点击 “自动安装基础组件”，并在 Ubuntu 提示时输入 Linux 密码。
• 如果网络下载失败，检查 Ubuntu 是否能访问软件源，稍后重试。
• 如果显示 apt/dpkg 被占用，关闭其他正在更新 Ubuntu 的窗口，等待更新结束后重试。

需要手动处理时，在当前 Ubuntu 中运行：

sudo apt update
sudo apt install -y ca-certificates curl tmux bubblewrap xz-utils

命令成功后回到客户端点击 “重新检查”。

1. 确认 Agent 设置当前选中的 Ubuntu 名称。
2. 在同一套 Ubuntu 中运行：

node --version
npm --version
which node
which npm

• 两个版本命令都必须成功；只有 npm 文件存在并不等于 Node 运行环境完整。
• 当前最低要求为 Node.js 18。低于 18 时点击 “自动安装运行环境”。
• 自动安装会从 nodejs.org 下载并校验 Node.js 22，安装到当前 Ubuntu 用户目录，不会替换 Windows 的 Node。
• 如果 CLI 实际在另一套 Ubuntu，切换到那套环境，不要重复安装。

1. 确认你在客户端当前选中的 Ubuntu 中测试，而不是 Windows PowerShell 或另一套 WSL。
2. 分别运行 codex --version、kimi --version或qwen --version。
3. 如果只有打开特定 shell 配置后才能找到 CLI，检查 PATH 是否包含 ~/.local/bin和~/.kimi-code/bin。
4. 关闭并重新打开 Woodox 后重新检查。检测到后页面会明确显示“跳过安装”。

1. 回到客户端点击 “重新检查”。
2. 在当前 Ubuntu 运行 codex login status确认 CLI 本身能读取登录状态。
3. 浏览器无法回到终端时，展开登录兜底并使用设备码登录。
4. 如果终端登录的是另一 Linux 用户或另一套 Ubuntu，需要在客户端选中的环境重新登录。

这不是 Woodox 的安装故障。Kimi Code OAuth 当前账号没有可用会员权益，或 Kimi 暂时无法验证权益。

1. 确认登录的是有相应 Kimi Code 权益的账号。
2. 没有会员时，可以开通相应权益，或重新运行 kimi login改用 Kimi Platform API Key。
3. API Key 在 platform.kimi.com创建就选该入口；在 platform.kimi.ai创建就选另一个入口。

1. 在 Qwen Code 终端输入 /auth。
2. 选择 Coding Plan 或 API Key，并按 Qwen 官方提示完成。
3. Qoder 是另一款产品，不是 Qwen Code；当前客户端不支持用 Qoder 替代 qwen命令。

1. 电脑端概览确认后台服务已在线。
2. 重新打开 “手机连接”，扫描刚生成的第二个二维码。
3. 确认手机和电脑不是一个连接访客 Wi-Fi、一个连接主网络；部分路由器会隔离无线设备。
4. 不要使用 WSL 的 172.x.x.x地址，使用电脑 WLAN 的 192.168.x.x/10.x.x.x地址。
5. 检查 Windows 防火墙是否允许 Woodox 当前网络访问。
6. 电脑不要休眠。仍失败时进入 “诊断”查看端口和服务心跳。

1. Windows 客户端进入 “设备管理”。
2. 在 “等待确认”中找到自己的手机，核对名称和标识。
3. 点击 “允许”；不认识的设备点击拒绝。
4. 返回手机重试连接。被撤销过的设备需要恢复或重新扫码生成身份。

这类问题必须按“DNS → 443/TLS → 反向代理 → Unix Socket → SSH 隧道 → 本机 8787”顺序检查，不能靠重扫二维码解决。

1. 账户中心 502：先在云服务器检查 curl http://127.0.0.1:8790/api/health。
2. 设备域名 502：检查 ss -xl是否存在该设备的 codex-mobile.sock。
3. SSH 失败：核对云安全组/UFW 的 22、设备公钥、服务器主机指纹和受限账号状态。
4. 证书错误：检查实际域名是否被通配符证书覆盖，以及证书是否过期。

完整命令和预期结果见自建服务器逐层验收。

• 电脑端重置连接后，所有旧二维码和旧链接都会失效。
• 从当前电脑端 “手机连接”重新扫码，不要继续使用聊天记录里保存的旧链接。
• 连续失败触发限流时，等待几分钟后再使用新链接。

1. 切换回 “对话”视图，不要把原始终端屏幕当作完整历史。
2. 在对话时间线向上滚到顶部，等待更早记录加载。
3. 刷新后稍等实时连接恢复；客户端会用当前状态校正断线期间遗漏。
4. Codex 结构化历史暂不可用时可能进入终端增量回退，功能仍可用，但卡片结构会减少。

• 每条消息最多 4 个附件，每个最多 12 MB。
• 不要把附件和 Slash 命令放在同一条消息。
• 重新从系统相册或文件管理器选择原始文件，避免扩展名与内容不一致。
• 切换会话会清除未发送的附件；服务重启后需要重新选择。
• 电脑暂存空间已满时稍后重试，旧附件会自动清理。