常见问题（FAQ）

常见问题（FAQ）

这里汇总 ToCodex 使用过程中最常见的问题。建议先根据问题类型快速定位，再按步骤排查；如果问题仍未解决，可以在联系支持时附上版本号、系统环境、复现步骤和相关日志。

如何安装 ToCodex 桌面版？

1. 前往 ToCodex 官网的下载页面，选择适合当前系统的桌面版安装包。
2. 下载完成后运行安装程序，并按照系统提示完成安装。
3. 首次启动时，建议先完成模型配置与基础偏好设置。
4. 打开一个本地项目目录，创建第一个任务，确认文件读取、终端执行和模型响应是否正常。

如果安装后无法启动，请优先检查系统安全软件是否拦截、安装包是否完整、当前系统版本是否满足要求，并尝试重新下载安装包。

IDE 插件无法加载怎么办？

可以按以下顺序排查：

• 确认 IDE 版本：确保编辑器或 IDE 已更新到较新的稳定版本。
• 重新启用插件：在扩展管理中禁用 ToCodex 插件后重新启用，必要时重启 IDE。
• 检查网络与代理：插件初始化可能需要访问模型服务、账户服务或本地服务，代理配置异常会导致加载失败。
• 查看扩展日志：打开 IDE 的输出面板或开发者工具，查找 ToCodex 相关错误信息。
• 排除插件冲突：临时禁用可能拦截终端、网络、文件系统访问的其他插件，再重新加载。

如果插件仍然无法加载，请记录 IDE 版本、ToCodex 插件版本、系统版本和错误日志，方便进一步定位。

如何配置模型？

ToCodex 支持按场景配置不同模型。常见配置流程如下：

1. 打开模型配置或 Provider 配置页面。
2. 选择模型服务商，并填写 API Key、Base URL、模型名称等必要信息。
3. 为配置设置易识别的名称，例如“快速问答”“复杂编码”“长上下文文档”。
4. 保存后执行一次简单对话，确认模型能正常响应。
5. 根据任务类型选择合适配置：轻量任务优先速度，复杂代码任务优先推理能力和上下文长度。

请不要把 API Key、密码、令牌等敏感信息直接发送给模型；建议只保存在本地安全配置中。

浏览器任务模式需要哪些权限？

浏览器任务模式用于操作网页、后台系统、表单和 Web 应用，因此通常需要以下权限：

• 启动或连接浏览器实例。
• 读取当前页面结构、文本、按钮、输入框等可交互元素。
• 根据你的授权执行点击、输入、跳转、下载或截图等操作。
• 在需要登录的网站中使用你已经登录的会话状态。

使用浏览器任务模式时，请注意：

• 涉及支付、删除、发布、权限变更等高风险操作前，应要求 ToCodex 先说明计划并等待确认。
• 不要让任务读取或提交无关的敏感信息。
• 对生产后台操作保持最小权限原则，优先使用测试环境或只读账号。

定时任务不执行怎么办？

定时任务依赖触发规则、运行环境和任务配置。可以依次检查：

• 任务是否启用：确认任务没有被暂停或禁用。
• 触发时间是否正确：检查 Cron 表达式、时区、一次性任务时间或间隔时间设置。
• 运行环境是否在线：如果任务依赖本地桌面端、IDE 或工作区，请确认对应环境在任务触发时可用。
• 并发策略是否跳过：当上一次任务仍在运行时，skip 策略会跳过新的触发。
• 权限是否不足：文件、终端、浏览器、网络或模型权限异常都可能导致任务启动失败。
• 查看运行历史：检查最近一次运行记录、失败原因和错误日志。

如果任务只在特定时间失败，重点检查时区、系统休眠、网络断开和模型服务可用性。

为什么会出现 60s 超时？

60s 超时通常表示某一步操作在限定时间内没有返回结果，常见原因包括：

• 模型响应过慢或模型服务排队。
• 网络代理、DNS 或服务端连接不稳定。
• 命令执行时间过长，例如安装依赖、构建项目或运行大型测试。
• 浏览器页面加载缓慢、目标网站阻塞自动化访问。
• 任务提示词过大，导致模型处理时间显著增加。

建议的处理方式：

• 将复杂任务拆成多个较小步骤执行。
• 对长时间命令单独运行，并设置更合理的超时时间。
• 更换响应更快或更稳定的模型配置。
• 检查代理、网络和服务商状态。
• 减少一次性输入的日志、文件或网页内容。

如何设置自定义规则？

自定义规则用于约束 ToCodex 的行为，例如语言偏好、代码风格、提交规范、安全边界和项目约定。

常见规则示例：

• 始终使用简体中文回答。
• 修改代码后运行相关测试或构建命令。
• 不要修改指定目录或生产配置文件。
• 提交文档时使用固定标题结构。
• 处理敏感操作前必须先给出计划并等待确认。

建议把规则写得具体、可执行、可验证。例如，与其写“代码要好”，不如写“新增 TypeScript 代码必须保留类型标注，并通过项目现有 lint 检查”。

如何排查日志？

日志排查建议从最接近问题发生位置的日志开始：

• 桌面版日志：用于排查启动失败、模型调用、任务执行、权限或本地服务问题。
• IDE 输出面板：用于排查插件加载、扩展激活、文件访问和终端调用问题。
• 任务运行记录：用于排查定时任务、浏览器任务或自动化工作流失败。
• 终端输出：用于排查依赖安装、构建、测试、脚本执行失败。
• 浏览器控制台：用于排查网页加载、登录状态、脚本错误和自动化交互问题。

提交日志时，建议同时提供：问题发生时间、ToCodex 版本、操作系统、相关配置名称、复现步骤、完整错误信息。请在发送前移除 API Key、Token、Cookie、密码和个人隐私数据。

如何联系支持？

如果 FAQ 无法解决问题，可以通过 ToCodex 官网提供的支持入口、社区渠道或反馈表单联系我们。为了更快定位问题，请尽量附上：

• 问题简述和期望结果。
• 实际现象、错误提示或截图。
• ToCodex 桌面版或 IDE 插件版本。
• 操作系统、IDE 名称与版本。
• 模型服务商和模型名称（不要提供 API Key）。
• 可复现步骤和相关日志片段。

涉及账户、支付、授权或企业部署的问题，请优先使用官方支持渠道，并在描述中标明问题类型。