企业官网建设流程全解析

ai-virtual-phone（AI虚拟手机）是一款基于 Next.js 的开源项目：在浏览器里模拟一部完整的手机，让你用自己的 API Key驱动** AI 角色聊天**、朋友圈互动和剧情创作。本文是一份面向新手的首次使用指南，带你完成本地运行、配置 API Key、创建第一个 AI 角色这三件事，全程不到 10 分钟就能开聊。

它是什么：一部装在浏览器里的 AI 虚拟手机

打开它，你会看到一部仿真手机桌面：聊天、朋友圈、音乐、日历、日记等应用一应俱全。与传统聊天软件不同的是，屏幕对面的"人"是你自己创建的 AI 角色——她有性格设定、作息、记忆，还能发语音、转红包、刷朋友圈。

核心特点一句话总结：所有大模型调用都走你自己的 API Key，项目不内置任何模型服务，数据也存在你自己的浏览器里，完全私有。

快速本地运行：环境要求与启动命令

运行前只需准备 package.json 里声明的两个条件：

• Node.js 20+（Next.js 15 要求 ≥ 18.18）
• 任意 OpenAI 兼容的 LLM API（OpenAI / DeepSeek / 中转站等），或 Anthropic / Google Gemini 官方 API

执行下面的命令即可启动（仓库地址仅供 clone 使用）：

git clone -b main https://gitcode.com/gh_mirrors/ai/ai-virtual-phone cd ai-virtual-phone npm install cp .env.example .env.local npm run dev

然后浏览器打开http://localhost:3001（默认端口 3001，可用PORT环境变量修改）。

.env.example已默认开启单机模式（NEXT_PUBLIC_SELF_HOSTED_MODE=true），会跳过账号/激活码门禁，直接进入，适合个人自用。

第一步：打开「设置 → API 设置」配置你的 API Key

进入应用后，桌面底部 Dock 栏点设置图标，进入API 设置（对应源码 components/settings/api-settings.tsx）。

首次打开时页面已自带一条"OpenAI 官方"配置，按以下方式填写即可：

💡 小提示：

• 支持OpenAI 兼容接口、Anthropic、Google Gemini三类协议，可随时点右上角"新增API方案"添加多个，聊天时自由切换；
• 填完后先点测试连接，看到成功提示再保存，能少走弯路。

第二步：创建第一个 AI 角色卡

配置好 API 后，打开 Dock 栏的角色入口（桌面画布里点"新建"）。这里对应 components/phone-character-app.tsx，角色数据读写逻辑在 lib/character-storage.ts。

新建角色卡只需填三样东西：

1. 名字：给 TA 起个称呼，比如"小橘"；
2. 人设（Persona）：这是灵魂所在，写清性格、口癖、与你的关系，例如"温柔话多的大学生，喜欢用 emoji，会主动关心你的作息"；
3. 头像：可选，支持上传照片，支持 1:1、3:4、16:9 等多种拍立得相框样式。

不会写人设？没关系——项目内置了桌面 AI 助手「小卷」，可以帮你润色人设、写世界书和预设，相当于随身创作教练。

另外也支持直接导入别人做好的角色卡（PNG 或 JSON 格式），导入后自动落到当前"卷宗"里，和手动新建的效果一样。

上面这张就是项目自带的 AI 生成壁纸——配好 API Key 后，你也可以在设置里开启AI 生图，让手机壁纸、角色头像都变成"现画"的。

第三步：打开聊天，开始和 AI 角色说话

角色创建完成后，回到桌面点开聊天应用（源码 components/chat/phone-chat-app.tsx），从联系人里选中你的新角色，发送第一句话。

之后你会体验到远超"一问一答"的仿真感：

• 💬私聊 / 群聊：可以拉多个 AI 角色组建群聊；
• 📱朋友圈：角色会自己发帖、给你点赞评论；
• 🎙️语音消息：配好 Minimax 语音合成 API 后，角色会"开口说话"；
• 🧠长期记忆：有作息、有记忆、关系会随对话推进而变化。

可选进阶：3 分钟解锁更多玩法

开聊之后，按需开启这些增强功能（全部在设置里配置，不配也能正常使用基础聊天）：

• AI 生图：填写生图 API，解锁头像、壁纸、朋友圈配图现画；
• Minimax 语音：语音合成/识别，让角色带声音；
• 网易云音乐：自填 API 地址后，音乐 App 里可以在线听歌；
• 游戏大厅与小游戏：手机里内置了斗地主、真心话大冒险等，可以叫上 AI 角色一起玩：

更重的云端功能（云备份、微信接入、离线推送）属于可选项：每位用户可以在设置 → 云服务部署里一键创建自己的 Supabase 个人云，说明见 README.md 与 docs/supabase-all-in-one.sql。

常见问题（FAQ）

问：本地跑起来后打不开页面？答：确认访问的是http://localhost:3001（不是 3000），端口可用PORT环境变量修改。

问：我的角色和聊天记录存在哪里？答：全部存在你自己的浏览器本地（localStorage / IndexedDB），项目不含任何模型服务，也不收集数据。

问：API Key 用哪个最划算？答：任意 OpenAI 兼容接口均可，DeepSeek、各类中转站都是常见选择；官方 OpenAI、Anthropic、Gemini 也原生支持。

写在最后

到这里，你的第一部 AI 虚拟手机已经跑起来了：配置 API Key → 创建 AI 角色 → 开聊，三步走完。接下来可以慢慢探索世界书、剧情模式、视觉小说、应用市场等玩法。项目以 AGPL-3.0 协议开源（见 LICENSE），祝你和 TA 聊得愉快 🍀

延伸阅读：README.md 中的环境变量总表、components/settings/api-settings.tsx、lib/settings-types.ts