# 快速开始

> 安装 Astravia、完成首次引导、配置模型，并为第一个可验证任务准备工作区。

Canonical page: /getting-started



<Takeaways>
  <li>
    与当前系统匹配的桌面端
  </li>

  <li>
    至少一个可用的默认模型
  </li>

  <li>
    能打开项目并创建会话
  </li>
</Takeaways>

完成本页后，你会得到一个有可用模型、能够创建项目的 Astravia 桌面工作区。带账户的构建还会完成登录；开源版没有账户，直接配置自己的模型即可。整个过程通常只需一次，之后可以从项目或「对话」开始任务。

如果你是升级现有安装、需要更换设备或从源码运行，请先阅读[安装、升级与数据迁移](/getting-started/installation-and-updates/)，再回到本页完成首次配置。

<MediaFrame>
  <img src="/images/product/workspace.webp" alt="完成首次设置后的 Astravia 主工作区" width="2354" height="1613" />

  <figcaption>
    准备完成后，侧栏管理项目和能力，中间区域创建会话并提交任务。
  </figcaption>
</MediaFrame>

## 准备工作 [#准备工作]

<Kit>
  <KitItem index="01" title="计算机">
    支持 Windows / macOS / Linux，以[官网下载区](https://astravia.dev/#download)实际发布包为准。
  </KitItem>

  <KitItem index="02" title="账号">
    只有带 Astravia 账户的构建才需要浏览器 **授权登录**。开源版没有这一步。
  </KitItem>

  <KitItem index="03" title="模型服务">
    组织提供的远程模型，或在「设置 → 模型配置」自行添加的服务商与密钥。
  </KitItem>
</Kit>

## 安装与首次启动 [#安装与首次启动]

<Steps>
  <Step>
    ### 下载并安装 [#下载并安装]

    从 [Astravia 官网下载区](https://astravia.dev/#download)获取适合当前操作系统和处理器架构的安装包，完成安装后启动 Astravia。官网下载区没有列出的平台或架构表示当前没有可用制品，不要使用其他平台安装包替代。
  </Step>

  <Step>
    ### 完成首次引导 [#完成首次引导]

    首次启动会进入引导流程，主要包括：

    1. **语言与外观**：选择界面语言（跟随系统 / 中文 / English）和外观偏好。
    2. **系统权限**（仅 macOS）：按提示完成应用所需权限。
    3. **登录**（仅带账户的构建，且尚未登录时）：点击 **授权登录**，在浏览器完成 OAuth 后返回应用。开源版没有账户，引导里不会出现这一步。
    4. **欢迎页**：引导结束进入主界面。

    之后可在「设置 → 通用设置」中通过 **启动 App 引导** 重新打开该流程。
  </Step>

  <Step>
    ### 确认登录状态 [#确认登录状态]

    带账户的构建里，侧栏账户区域应显示已登录。企业用户使用组织提供的登录方式；授权链接失效时，在登录弹层中重新授权。开源版没有账户区域，这一步可以跳过。
  </Step>
</Steps>

## 配置模型 [#配置模型]

打开 **设置 → 模型配置**（侧栏也可进入模型相关入口）：

<Beats>
  <li>
    在 

    **预设服务商**

     中选择已支持的服务商（如 Claude、OpenAI、DeepSeek、Z.ai (GLM)、Kimi、Grok、Qwen、Gemini 等），填写 API Key。
  </li>

  <li>
    使用 

    **从接口拉取**

     获取模型列表并勾选添加，或手动 

    **添加模型**

    。
  </li>

  <li>
    将常用模型 

    **设为默认模型**

    。
  </li>

  <li>
    可选：调整全局 

    **思考**

     档位（关闭 / 极低 / 低 / 中 / 高 / 极高）；模型不支持时会自动降级。
  </li>
</Beats>

没有预设时，使用 **添加服务商** 配置自定义名称、API 类型、Base URL 与 API Key。

<Callout title="密钥安全" type="warn">
  访问密钥只应填写在凭据配置界面。支持 `sk-...`、`env:MY_API_KEY` 等形式。不要把密钥写入提示词、项目文件或问题报告。配置落在本机 `~/.astravia/agent/models.json`。
</Callout>

## 主界面入口 [#主界面入口]

<Panel>
  <PanelGroup title="侧栏主区">
    <PanelItem title="新会话 / 项目区">
      在工作目录中创建会话并执行任务
    </PanelItem>

    <PanelItem title="自动化">
      按计划单次或周期执行任务
    </PanelItem>

    <PanelItem title="知识库">
      导入并整理可长期检索的资料（界面可能带 BETA 标识）
    </PanelItem>

    <PanelItem title="能力">
      技能、场景、MCP、插件、套装
    </PanelItem>
  </PanelGroup>

  <PanelGroup title="更多菜单">
    <PanelItem title="批量任务">
      同一提示处理多个文件夹
    </PanelItem>

    <PanelItem title="模型设置">
      跳转到设置中的模型配置
    </PanelItem>

    <PanelItem title="Agent 设置">
      跳转到 Agent 配置
    </PanelItem>

    <PanelItem title="外观">
      跳转到外观设置
    </PanelItem>
  </PanelGroup>
</Panel>

完整设置（Claw、知识库后台、应用环境、消息推送、Astravia Vivi 等）从侧栏 **设置** 进入。场景类型可在能力页管理；另有路由 `/scenes` 的场景专页，但不一定作为侧栏一级入口展示。

## 确认准备完成 [#确认准备完成]

<Checklist title="开始第一个任务前">
  <li>
    账户区域显示已登录，或当前部署允许未登录使用。
  </li>

  <li>
    「设置 → 模型配置」至少有一个模型，并已设为默认模型。
  </li>

  <li>
    新建会话页能够选择该模型，没有显示凭证或连接错误。
  </li>

  <li>
    需要处理本地文件时，已经创建或打开正确的项目目录。
  </li>

  <li>
    已理解新会话的执行模式是「沙盒受限」还是「完全访问」。
  </li>
</Checklist>

如果模型测试失败，先处理配置问题，不要在任务中反复重试。参见[配置模型](/product/models/)和[故障排查](/troubleshooting/)。

<Continue>
  <ContinueLink href="/getting-started/first-task/" title="运行第一个任务" description="选择工作目录、编写目标并核对执行结果。" />

  <ContinueLink href="/examples/" title="选择一个实战示例" description="从代码、资料、批量或自动化的完整任务开始。" />

  <ContinueLink href="/product/models/" title="配置模型" description="预设服务商、自定义服务商与验证方式。" />

  <ContinueLink href="/product/overview/" title="使用指南概览" description="按任务浏览连接、执行与扩展能力。" />
</Continue>