开始前准备

• 准备至少一个可用的模型服务配置。云端模型通常需要 API Key，本地 Ollama 或 vLLM 服务可按服务要求填写。
• 如需联网搜索，再准备博查或智谱搜索 API Key；联网是可选能力。
• 如果要连接 MySQL、Doris 或 Oracle，提前准备只读或读写账号，并确认数据库地址可访问。
• API Key、数据库密码等敏感信息只填写在对应设置中，不要写入项目文件或任务提示词。

点击放大

点击放大

操作步骤

1. 点击工具栏“设置”，切换到“模型”。
2. 在供应商卡片中点击“获取模型”或“配置”，填写 OpenAI 兼容接口地址和接口密钥，并完成“连接测试”。
3. 展开供应商卡片，勾选本次要使用的模型；需要接入其他服务时，使用“自定义 OpenAI 兼容模型”填写接口、模型名称、上下文窗口和最大输出 Token。
4. 点击“设为默认”或调整启用模型顺序。启用列表中的首个模型作为默认模型，发送后可在对话输入区切换已启用模型。
5. 保存配置后再发起任务。只有模型目录声明支持视觉能力的模型才能接收 JPEG、PNG、GIF 或 WebP 图片，自定义模型按文本模型处理。

联网搜索 API Key

联网搜索为可选能力。启用后，Agent 可以检索公开网络信息；搜索结果仍需结合来源、日期和任务口径人工核验。

点击放大

操作步骤

1. 切换到“联网”，打开“启用联网”。
2. 在“供应商”中选择博查或智谱，填写“搜索 API Key”；接口地址由供应商配置提供，不需要自行改写。
3. 完成“连接测试”，再设置“结果上限”（1—20 条），点击“保存联网设置”。
4. 任务中明确检索主题、时间范围和来源要求；不需要联网时关闭开关，避免无关检索。

环境检查

“环境”页面会统一检查 Python、Node.js、PowerShell、CMD、Stata、R 和 LibreOffice。Python、Node.js 与 LibreOffice 可按软件引导自动准备；Stata、R 等按实际研究任务配置。

点击放大

操作步骤

1. 点击工具栏“设置”，切换到“环境”，点击“重新检查”。
2. 先确认 Python、PowerShell 和 CMD 可用；需要运行 JavaScript、文档转换、Stata 或 R 任务时，再检查对应工具。
3. 自动识别不正确时，使用对应行的选择入口指定 Python 解释器、Node.js、Stata 或 R 可执行文件。
4. 按任务需要配置环境，不要为了通过检查安装无关工具；环境状态会影响可调用的工具范围。

远程数据库连接

需要查询外部数据源时，在“数据库连接”中创建 MySQL、Doris 或 Oracle 连接，选择只读或读写权限。远程数据库 Agent 会在当前项目上下文中使用这些连接。

点击放大

1. 打开“设置 → 数据库连接”，点击新建连接，填写地址、端口、数据库、用户名和密码。
2. 优先选择“只读”；只有明确需要写入且具备备份与权限控制时才选择“读写”。
3. 完成连接测试后保存。读写模式下，每条 SQL 会先写入项目 sql/remote_db_history/，保存失败时不会执行。

验收要点

至少一个模型已完成连接测试并启用，联网开关和搜索服务状态符合需要，环境页面完成检查，远程数据库连接（如使用）测试通过。打开项目后，左侧显示项目与专业工作区，中间显示 Agent 执行区，右侧按需打开文件工作区；Skills 在“设置 → 技能”中管理。

数字签名乱码处理

Windows 11 运行安装包时，如果 SmartScreen 或数字签名窗口里的发行者信息显示为问号、方块或乱码，通常是系统没有启用 UTF-8 全球语言支持。安装包是否完整仍以下载页 SHA256 和 MD5 校验码为准。

点击放大

1. 打开 Windows 11“设置”，进入“时间和语言”里的“语言和区域”。
2. 找到“Beta 版：使用 Unicode UTF-8 提供全球语言支持”，将开关改为开启。
3. 按系统提示重启电脑，再重新运行 QiyanAgent 安装包。