研发部›EVA AI›安装与上手

GET STARTED

安装与首次配置

从安装到可正常使用，需完成三件事：处理系统拦截、配置 API Key、按需下载语音模型。

尚未下载？请前往 下载页（当前 v1.2.0）。

安装应用

打开已下载的 EVA AI 1.2.0 内测版-arm64.dmg，将其中 EVA AI.app 拖入「应用程序」文件夹。

首次启动：右键打开

本版本未使用 Apple 开发者签名，直接双击会被系统拦截。请在图标上右键选择「打开」，再次确认「打开」；此后可正常双击启动。

也可通过终端一次性移除隔离标记：

xattr -dr com.apple.quarantine "/Applications/EVA AI.app"

授予系统权限

按需授予：麦克风（实时对话）、屏幕录制（截图）、辅助功能（控制其他应用）。未授权不影响其余功能，仅对应能力不可用。屏幕录制权限需重启应用后生效。

怎么更新到新版本

应用内不会自动替换自己，只会在「设置 → 关于」里提示有新版本，并给一个去下载页的入口。更新是手动的，但只要一步。

不用先卸载旧版本。Windows 安装器会自己把旧版卸掉再装新版，中间不会问你。macOS 与 Linux 同理，把新的换上就行。

Windows（安装版）

先完全退出 EVA（托盘图标右键 → 退出；光点窗口的 × 只是最小化），然后运行新版 -Setup-x64.exe 或 -Setup-x86.exe。

安装向导会检测到已装的版本并自动替换。装完直接打开，一切都还在。

Windows（免安装版）

下载新的 -免安装-x64.exe（或 -x86），旧的删掉、新的一放就行。免安装版不写注册表，没有卸载流程。

macOS

打开新的 DMG，把 EVA AI 拖进「应用程序」。系统会问「已存在同名项目，是否替换」，选替换。不需要先删旧的。

Linux

AppImage：下载新的，删掉旧文件，对新文件重新 chmod +x。
tar.gz：解压到新目录，把旧目录删掉即可。

你的数据在哪

配置、API Key、对话记录、长期记忆、语音模型，全部存在用户主目录的 ~/.eva，不在安装目录里。

WindowsC:\Users\你的用户名\.eva
macOS/Users/你的用户名/.eva
Linux/home/你的用户名/.eva

因为这个目录独立于安装位置，所以升级不会动它，卸载重装也不会动它 —— 就算把 EVA 完全卸载，配置和聊天记录仍然躺在那里。

反过来说：想彻底清干净，光卸载是不够的，得手动删掉 ~/.eva。API Key 就存在那里（config.json，权限 600）。

跨版本升级

可以直接跳。1.1.3 升到 1.1.7 不需要逐版走一遍，直接用最新安装包就行 —— 安装器只认「装没装过」，不关心中间隔了几个版本。

版本很旧的话（比如 1.0.x），升级后建议打开「设置」扫一眼 API Key 还在不在 —— 数据不会丢，但个别配置项的名字在新版本里变过。

首次启动的三项配置

配置 API

首次启动会引导填写「服务商 + API Key + 模型」。模型必须支持 function calling：DeepSeek、通义千问、Kimi、智谱 GLM、GPT-4o 或本机 Ollama 均可。填写完成后点击「测试连接」，显示「连接正常」即可使用。

密钥仅写入本机 ~/.eva/config.json（权限 600），且仅发往用户配置的接口地址。

授予权限

同上：麦克风、屏幕录制、辅助功能。权限按应用授予，重装或更换路径后需重新授权。

语音模型（可选）

首次进入「实时对话」页时会自动下载识别模型至 ~/.eva/voice/，状态胶囊会显示进度。下载完成后识别全程在本机进行，不再联网。

如需语音播报，需在本机运行 Qwen TTS WebUI；未运行不影响其他功能，仅无语音输出。

校验下载文件

下载页上每个安装包均提供 SHA-256。建议在安装前核对，以确认文件未被篡改；应用更新时核对的也是同一份值。

# macOS
shasum -a 256 ~/Downloads/"EVA AI 1.2.0 内测版-arm64.dmg"

# Windows PowerShell
Get-FileHash "$env:USERPROFILE\Downloads\EVA AI 1.2.0 内测版-Setup-x64.exe" -Algorithm SHA256

# Linux
sha256sum ~/Downloads/"EVA AI 1.2.0 内测版-Linux-x86_64.AppImage"

完整清单（含体积与发布日期）见 下载页，亦可直接读取 version.json。

数据放在哪

配置与密钥
~/.eva/config.json（权限 600，只在本机）
会话与记忆
~/.eva/sessions/ · ~/.eva/memory.md
截图
~/.eva/captures/
语音模型
~/.eva/voice/（SenseVoice / Whisper，按需下载）
卸载
删掉应用即可，数据不会跟着走。想彻底清干净，再删 ~/.eva/。Windows 是 %USERPROFILE%\.eva\。
换端口 / 换数据目录
内核默认监听 127.0.0.1:8787；用 EVA_PORT=9000、EVA_HOME=/别的/路径 可以改。

常见问题

与网页版 AI 的区别是什么？+
网页版仅提供文字回复。EVA 使用同一类模型，但可调用 16 件本地工具在本机执行操作：读写文件、运行命令、截取屏幕、查询系统状态。目标不是对话体验，而是完成任务。
本地文件会被上传吗？+
工具全部在本机执行，文件内容不会被主动上传。离开本机的只有发送给模型的对话内容，且仅发往用户配置的接口地址。密钥仅存于 ~/.eva/config.json（权限 600），界面只回显掩码。
误操作的风险如何控制？+
审批模式下，每条有风险的操作都需用户确认；确认层展示的是将要执行的原始命令，而非转述。系统并不保证不犯错，但不会在未获批准的情况下执行。
截图为空白如何处理？+
macOS 的「屏幕录制」权限按应用授予。请在 系统设置 → 隐私与安全性 → 屏幕录制 中勾选 EVA，然后重启应用——权限仅在启动时读取一次。
语音无输出如何处理？+
请先确认 Qwen TTS WebUI 正在运行（默认 127.0.0.1:7860），且音色库中存在对应音色包。实时对话页的状态胶囊会标明是「未连接」还是「正在载入 1.7B 模型」。
唤醒后无响应如何处理？+
请查看实时对话页底部的状态胶囊：识别模型需先载入内存，1.1 GB 的 SenseVoice 首次进入页面需等待十余秒。载入完成后胶囊显示「SenseVoice Small · 就绪」。胶囊同时区分「未检测到语音」（音量条无变化）与「未命中唤醒词」（日志显示「听见…但没叫我」）两种情况。
语音识别是否需要下载模型？+
是。模型按需下载，存放于 ~/.eva/voice/。默认 SenseVoice 约 1.1 GB（中文准确率最高），也可在设置中改用 Whisper Base（约 430 MB）或 Tiny。下载完成后识别全程在本机进行，不再联网。
是否支持部署到服务器？+
deploy/ 目录包含 systemd 与 nginx 安装脚本，部署后即为常驻座席。需要注意，该方式不再具备「本机」这一层隔离，硬红线与审批机制仍然生效。
数据存放位置与卸载方式？+
应用与数据相互独立：卸载应用不会删除数据。配置、会话、截图、语音模型与日志均存于 ~/.eva/（Windows 为 %USERPROFILE%\.eva\）。如需彻底清除，删除该目录即可。

遇到未记录的报错

请提供三项信息：版本号（设置 → 关于）、截图、当时的输入内容，发送至作者 @成分复杂。

查看本版本变更