JARVIS配置一页通：.env、API Keys与SSL证书快速指南
JARVIS配置一页通：.env、API Keys与SSL证书快速指南
JARVIS 是一个运行在 Mac 上的语音 AI 助手，而 JARVIS 配置其实只有三件事：填写 .env 文件、配好两个 API Keys、生成一份本地 SSL 证书。读完本文，你在一页之内就能搞懂所有配置项，10 分钟让 JARVIS 开口说话。🎙️
配置总览：先建立全局认知
| 配置项 | 作用 | 必须？ | 所在位置 |
|---|---|---|---|
.env 文件 |
存放 API Keys 与个性化设置 | ✅ 必须 | 项目根目录 |
ANTHROPIC_API_KEY |
驱动"AI 大脑"（Claude） | ✅ 必须 | .env 内 |
FISH_API_KEY |
驱动语音合成（TTS） | ✅ 必须 | .env 内 |
cert.pem / key.pem |
启用安全的 WebSocket（wss） | ✅ 建议 | 项目根目录 |
💡 新手最容易卡住的地方是第三步的 SSL 证书——它不是"可选优化"，而是浏览器允许音频功能正常工作的关键。
第一步：创建 .env 配置文件
.env 是所有配置的"总开关"。项目自带了一份模板 .env.example，只需复制一份即可上手：
cp .env.example .env
server.py 启动时会自动读取 .env 并注入环境变量，因此任何修改保存后重启服务即可生效，无需改动代码。
模板中所有可用的配置项如下：
| 变量名 | 说明 | 是否必填 |
|---|---|---|
ANTHROPIC_API_KEY |
Claude 的 API Key，AI 大脑 | 必填 |
FISH_API_KEY |
Fish Audio 的 API Key，语音合成 | 必填 |
FISH_VOICE_ID |
音色模型 ID，默认是 JARVIS（MCU）音色 | 可选 |
USER_NAME |
你的名字，JARVIS 会这样称呼你 | 可选 |
CALENDAR_ACCOUNTS |
限定读取哪些日历账号（逗号分隔邮箱） | 可选 |
JARVIS_SKIP_PERMISSIONS |
跳过 Claude CLI 的交互式授权提示，默认 true |
可选 |
WEATHER_LOCATION_LABEL / WEATHER_LATITUDE / WEATHER_LONGITUDE |
固定天气查询位置 | 可选 |
WEATHER_UNIT |
温度单位，fahrenheit 或 celsius |
可选 |
懒人福音：网页设置面板免改文件
如果你不想手动编辑文件，JARVIS 自带设置面板（源码见 frontend/src/settings.ts）：
- 直接在页面上粘贴 API Key，点击 Save Keys，程序会自动写回
.env文件； - 面板提供 Test Connection 按钮，可实时验证密钥是否有效（对应后端接口 server.py）；
- 状态页会用红/绿小圆点告诉你 Claude Code CLI、Apple Calendar、Mail、Notes 各模块是否就绪（server.py）。
⚠️ 小提醒：状态检测会识别占位值——如果
.env里还是模板默认的your-anthropic-api-key-here，会被视为"未配置"，别忘替换。
第二步：获取并填写两个 API Keys
这两个 Key 是整个 JARVIS 配置的核心，缺一不可：
-
ANTHROPIC_API_KEY
- 作用：驱动 Claude 进行意图识别、对话与任务规划（快速响应用 Haiku，深度研究用 Opus）。
- 获取：在 Anthropic 开发者控制台注册并创建。
- 填写：
ANTHROPIC_API_KEY=sk-ant-你的密钥 - 缺失后果：LLM 功能直接禁用（见 server.py）。
-
FISH_API_KEY
- 作用：把文字回复转换成带英式管家口音的 JARVIS 语音。
- 获取：在 Fish Audio 官网注册并创建。
- 填写：
FISH_API_KEY=你的密钥 - 缺失后果：文字照常工作，但 JARVIS 会"失声"（见 server.py）。
两者都填入后，建议先在设置面板里点一下测试按钮，看到绿色状态点再往下走。✅
第三步：生成 SSL 证书，解锁安全 WebSocket
为什么需要 SSL 证书？
JARVIS 的语音流走的是 WebSocket。浏览器对音频能力有安全上下文要求，而桌面悬浮层组件默认连接 wss://localhost:8340/ws/voice。本地开发时用一张自签名证书就能满足要求。
一条命令生成证书
在项目根目录执行：
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'
生成的两个文件放在项目根目录即可，有效期 365 天，到期重新执行一次命令。
后端如何识别证书
server.py 的启动入口会自动检测：只要 cert.pem 和 key.pem 同时存在，就自动启用 HTTPS + wss；你也可以用 --ssl 参数显式开启。启动成功后，终端会打印实际使用的协议：
WebSocket: wss://0.0.0.0:8340/ws/voice
REST API: https://0.0.0.0:8340/api/
前端开发服务器如何配合
前端由 Vite 在 5173 端口提供服务，frontend/vite.config.ts 已把 /ws 和 /api 请求代理到带 SSL 的后端 https://localhost:8340（secure: false 表示信任自签名证书）。而 frontend/src/ws.ts 会根据页面协议自动选择 ws: 或 wss:，无需手动改连接地址。
可选配置：让 JARVIS 更像"你的" JARVIS
以下设置在 .env.example 中都有注释说明，按需取消注释即可：
USER_NAME=Tony— 设定称呼后，JARVIS 会用你的名字与你对话，而不是千篇一律的 "sir"（server.py）。CALENDAR_ACCOUNTS=you@gmail.com,work@company.com— 留空则自动读取所有日历；设置了则只读指定账号，适合公私账号分离的场景（calendar_access.py）。JARVIS_SKIP_PERMISSIONS— 默认为true。因为 JARVIS 是纯语音交互，无法回应 Claude CLI 弹出的交互式授权窗口；如果你偶尔在终端里手动操作，可以设为false恢复逐次确认（actions.py）。FISH_VOICE_ID— 换一个音色模型 ID，就能给 JARVIS 换个"声线"。
配置自检：启动前的最终清单
按顺序完成以下 5 步，配置即大功告成：
- ✅
cp .env.example .env，填好两个 API Key； - ✅
pip install -r requirements.txt安装 Python 依赖； - ✅
cd frontend && npm install安装前端依赖； - ✅ 用 openssl 命令生成
cert.pem与key.pem； - ✅ 双终端启动：
# 终端 1：后端
python server.py
# 终端 2：前端
cd frontend && npm run dev
然后在 Chrome 中打开 http://localhost:5173，点击页面启用音频，开口说第一句话吧。如果设置面板里所有状态点都是绿色——恭喜，你的 JARVIS 配置已经完成！🎉
📖 延伸阅读：CLAUDE.md 中记录了完整的 10 步启动流程与架构说明，遇到问题可以对照排查。