# 快速开始：5 分钟用 NearWork 完成第一个任务

> 从下载安装到跑通第一个任务：登录、切换模型、上传文件、确认工具权限，附权限模式说明与常见问题。

NearWork 是一个装在你自己电脑上的 AI 智能体：它能读文件、跑命令、查网页、写文档，把「说一句话」直接变成「交付一个结果」。这篇教程带你从零跑到第一个真实任务，全程大约 5 分钟。

## 一、安装桌面端

- **Windows**：下载安装包（`.exe`）后双击安装，安装位置可自定义。
- **Linux**：下载 `.deb`（Debian / Ubuntu）或 `.rpm`（Fedora / CentOS 系）。
- **macOS**：以[下载页](/#download)显示的版本为准。

不想装桌面端，也可以用命令行版本（**需要 Node.js 22+**，低版本启动会直接报错并提示升级）：

```bash
npm install -g @lingxi-agent/core
lingxi
```

安装完成后首次启动，应用会在你的用户目录下创建数据目录 `LINGXI_HOME`（默认 `~/.LingXi`，Windows 下是 `C:\Users\<你的用户名>\.LingXi`）。配置、会话、记忆、知识库、日志全部保存在这里，换机器时复制这个目录即可迁移。

## 二、登录（必需步骤）

**NearWork 必须登录后才能使用**：首次启动会引导登录，未登录时无法新建会话、发送消息。登录入口在桌面端左下角；CLI 里输入 `/login` 会拉起浏览器授权。登录态保存在数据目录的 `auth.json` 中，桌面端与 CLI 共享同一份，换端无需重复登录。

登录之后，模型从哪来有两种选择，随时可以在设置里切换：

| 模型来源 | 适合谁 | 说明 |
|---|---|---|
| NearWork 官方额度 | 想开箱即用 | 使用官方中转的模型，按订阅套餐计费；免费版自带周期性额度 |
| 自带 API Key | 已有供应商账号 | 在「设置 → 模型与供应商」里填自己的 Key，费用直接结算给供应商 |

要注意的是：自带 API Key 只改变「模型和账单走谁」，并不替代登录——账号仍是使用产品的前提。

## 三、选模型：七个槽位，各管一件事

NearWork 不让你每次都在长长的模型列表里翻，而是把模型按用途拆成七个槽位。在「设置 → 模型与供应商」里编辑任意一个供应商，就能看到这七个模型 ID 字段：

| 槽位 | 设置里的名字 | 什么时候用 |
|---|---|---|
| 极速 | 极速模式 | 日常问答、改写、简单脚本，追求响应速度 |
| 思考 | 思考模式 | 复杂推理、方案设计、疑难 bug，允许它想久一点 |
| 视觉 | 视觉模式 | 看图、读截图、图像理解 |
| 图像编辑 | 图像编辑模式 | 文字生成图片、改图 |
| 语音生成 | 语音生成 | 文字转语音：朗读回复、配音 |
| 语音识别 | 语音识别（ASR） | 语音转文字：语音输入、录音转写 |
| 向量嵌入 | 向量嵌入 | 记忆与知识库的语义检索 |

聊天时只需要关心前两个：输入框上方切换「极速 / 思考」，也能调整推理深度（低 / 中 / 高）。其余槽位由对应功能自动取用——看图走视觉、生图改图走图像编辑、语音输入与朗读走两个语音槽位、记忆和知识库检索走向量嵌入，不用手动切换。

用 NearWork 官方账号时，七个槽位会按你订阅可用的模型自动填好；自带 API Key 时自己填模型 ID 即可。某个槽位留空的直接后果是那项能力暂不可用（比如没配视觉模型，贴图时会提示未配置），不会悄悄换成别的模型。同一个会话里换模型不会丢上下文。

## 四、跑第一个任务

点击「新建会话」，选一个工作目录，然后直接说你要什么。几个可以直接复制的例子：

```text
把这份会议录音整理成纪要：结论、分歧、待办（含负责人和时间）
```

```text
扫描当前目录，找出所有超过 5MB 的图片，压缩到 1MB 以内，原文件备份到 backup/ 目录
```

```text
读一下这个项目的 README 和 package.json，告诉我怎么本地跑起来，缺什么依赖
```

发送之后，你会看到 NearWork 的完整执行过程：先想、再调工具（读文件 / 执行命令 / 搜网页）、看结果、继续，直到交付。中间涉及写文件、执行命令这类操作时，会弹出确认询问——这是权限机制在起作用。

## 五、四种权限模式

安全边界由你定，四种模式覆盖从「每步都问」到「完全放手」：

| 模式 | 行为 |
|---|---|
| `normal`（默认） | 只读操作自动执行，写入和命令需要确认 |
| `strict` | 每一步都确认 |
| `auto` | 全自动执行，危险命令仍会被拦截 |
| `full_access` | 全部放行，不弹确认 |

首次使用建议保持默认的 `normal`：既能感受到自动执行的效率，又不会在你没看清时改动文件。熟起来之后再调高。

## 六、常见问题

### 安装后打开是白屏怎么办？

先确认安装包下载完整（重新下载一次），再检查是否有杀毒软件拦截了渲染进程。Windows 上如仍白屏，可以尝试以管理员身份运行一次，让应用完成首次依赖写入。若问题持续，把日志目录（`<LINGXI_HOME>/log`）里的最近一份日志发给客服。

### 必须登录才能用吗？

必须。NearWork 的所有客户端（桌面端、CLI）都要先登录 NearWork 账号才能新建会话、发送消息；自带 API Key 只是把模型调用和费用转到你自己的供应商账号上，不是免登录的替代方案。

### 不想用官方额度，但登录后能只走自己的 Key 吗？

能。登录后到「设置 → 模型与供应商」新增一条供应商条目，填上自己的 API Key 并把七个槽位的模型 ID 补全，然后把这条设为默认即可；官方额度只在你主动选择官方模型时才会消耗。

### 免费额度怎么算？

免费版按周期发放灵力额度（总额度 / 7 天额度 / 5 小时额度三重限制），灵力与实际用量挂钩：文本和向量按 token、图片按张、语音按字符或时长。具体数值与当前套餐见[定价页](/pricing)。

### 想私有化部署，或者把企业知识库放在自己的服务器上？

可以。NearWork 的引擎、模型网关与企业知识库都支持部署到贵方自己的服务器，满足内网离线、数据不出域等合规要求；方案与报价按规模和合规要求定制。这类需求没有自助入口，请点**页面右下角的「联系我们」**按钮，扫码加微信并说明是私有化部署需求。

## 下一步

- 想接外部工具？看[MCP 配置指南](/docs/features/mcp)。
- 关心数据去了哪里？看[数据与隐私说明](/docs/faq/data-privacy)。
- 想了解订阅与计费细节？看[定价页](/pricing)。
