快速上手——从安装完成到第一次让 AI 处理文件
本章不要求你了解 API、模型或命令行。照着操作，约 15 分钟可以完成服务商配置、第一次对话和第一次工作区任务。
开始前准备
你需要：
- 一台 Android 8.0 或更高版本的手机；
- 可以访问模型服务商的网络；
- 一个模型服务商账号和可用的 API Key；
- 账户中有可用额度，或者服务商提供免费额度。
API Key 是调用模型的密码，不是 Lyra Code 账号。Lyra Code 本身不售卖模型额度，也不会替你生成服务商密钥。
保护 API Key
只从服务商官方网站创建 Key。不要截图分享，不要粘贴进公开聊天、代码仓库或问题反馈。怀疑泄露时，立即到服务商后台吊销并重新生成。
第一步：认识侧边栏
打开 Lyra Code 后，点击左上角菜单图标，或者从屏幕左边缘向右滑。侧边栏的“功能”区域包含：
- AI 对话：和模型聊天、让 Agent 使用工具；
- 文件：双栏文件管理器和代码编辑器；
- 终端：连接 SSH 或应用内 PRoot Linux；
- 日志：查看部分运行记录；
- 统计：查看对话和 Token 估算；
- 任务：查看定时任务与下载进度；
- 归档：恢复或删除已归档对话和项目；
- 设置：配置模型、权限、远程服务和个性化选项。
本章先进入 设置。
第二步：添加模型服务商
- 打开 设置 → 模型服务。
- 点击右上角的 ＋。
- 如果列表里有你的服务商，直接点预设项；没有就选择 自定义服务商。
- 预设服务商通常已经填好接口格式和地址，你主要需要填写 API Key。
- 自定义服务商还要按照其 API 文档选择接口格式并填写 Base URL，详见模型与多服务商。
不要根据搜索引擎里的第三方教程猜地址。接口地址、模型名和 API Key 都应以服务商官方控制台或 API 文档为准。
第三步：填写并保存
配置页里常见的字段如下：
| 字段 | 新手应该怎么填 |
|---|---|
| 名称 | 起一个自己看得懂的名字，例如“我的 DeepSeek” |
| API Key | 粘贴服务商后台生成的完整密钥，前后不要带空格 |
| 接口格式 | 使用预设值；自定义服务商按官方文档选择 |
| Base URL | 预设服务商保持默认；第三方网关才按其文档修改 |
| 请求路径 | 通常留空，让应用使用接口格式的默认路径 |
然后按下面顺序操作：
- 点击 刷新模型列表；
- 在返回的模型中勾选至少一个；
- 打开 管理启用模型，确认刚才的模型在启用列表中；
- 如页面提供 可达性检测，选择模型并开始检测；
- 点击 保存。
刷新不到模型不一定是故障
有些兼容服务不实现模型列表接口。这种情况下，按官方文档手动输入准确的模型 ID，再把它加入启用模型列表。
第四步：选择服务商和模型
- 回到 AI 对话。
- 点击输入框旁的 ＋，打开底部动作面板。
- 选择刚保存的服务商。
- 选择一个已启用模型。
- 暂时保持应用原生系统提示词，其他开关先不改。
如果模型列表为空，返回 设置 → 模型服务 → 对应服务商 → 管理启用模型，确认至少启用了一个模型。
第五步：发送第一条消息
在输入框中发送：
你好。请用三句话介绍你能在 Lyra Code 里帮我完成什么，并且暂时不要调用任何工具。
能看到连续输出的回答，说明 API Key、地址、模型名和网络都已配置成功。
第六步：创建第一个工作区
工作区是允许 Agent 读写的项目文件夹。新手可以先创建一个练习目录：
- 打开侧栏 文件。
- 让其中一栏进入
/storage/emulated/0/Download。 - 点击该栏底部的 ＋ → 新建文件夹。
- 命名为
LyraPractice。 - 回到 AI 对话，点击顶部当前工作目录区域或相应的选择入口。
- 选择刚创建的
LyraPractice文件夹，并允许 Android 的目录访问请求。
选好后，当前对话详情里应能看到工作区名称或路径。工作区只对当前对话或所属项目生效，不会自动让 AI 访问整台手机。
第七步：完成第一次 Agent 任务
发送：
在当前工作区新建
hello.md，写入一级标题“我的第一个 Lyra Code 文件”和今天的学习目标。完成后再读取一次，确认内容正确。
处理过程中你可能看到工具调用卡片或审批弹窗：
- 先看工具名称；
- 核对目标路径是否在
LyraPractice； - 核对要写入的内容；
- 确认无误后批准；
- 完成后到 文件 页打开
hello.md检查。
不同工具的审批规则不同。不要把“没有弹窗”理解为没有操作；应始终查看工具记录和最终文件结果。
第八步：学会停止和纠正
- AI 正在输出时，可以点击停止按钮；
- 结果不符合要求时，明确指出哪里错了，不必重新开对话；
- 工具目标路径不对时拒绝审批，并告诉 AI 正确路径；
- 发现任务方向完全错了，先停止，再发一条更具体的新要求；
- 删除、覆盖、远程发送等操作，在确认前一定核对目标和影响。
常见问题
提示 401、Unauthorized 或认证失败
API Key 无效、复制不完整、已过期或不属于当前服务商。回到服务商后台确认并重新生成。
提示余额不足、quota 或 rate limit
余额不足、免费额度用完，或者请求频率过高。到服务商控制台查看账单与限制，稍后重试或换模型。
一直转圈或连接超时
依次检查手机网络、服务商状态、Base URL、请求路径、代理/VPN 和系统时间。不要连续重复发送相同付费请求。
能刷新模型，但聊天报模型不存在
检查对话实际选择的模型是否仍在服务商的启用列表中，模型 ID 的大小写和字符必须完全一致。
AI 不能看图片
模型本身可能不支持视觉输入。先用纯文字测试；图片使用方法见多模态与内容渲染。
AI 说没有工作区
给当前对话重新选择工作区。新建对话不会总是继承上一个普通会话的工作目录；项目中的对话则围绕项目目录管理。