> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# 快速开始：安装 Arka 并运行第一条命令

> 在 macOS、Linux 或 Windows 上安装 Arka，配置 API 密钥，并在五分钟内运行你的第一条自然语言终端命令。

让 Arka 在 macOS、Linux 或 Windows 上运行起来 —— **无需克隆仓库或本地编译**。安装 Python 包、运行 `arka setup`、配置 API 密钥，即可在任意终端使用 `arka`。

## 安装（无需从源码构建）

大多数用户应直接安装 **`arka-agent`** 包，无需 `git clone`、`./scripts/refetch.sh` 或编译步骤。

<Tabs>
  <Tab title="pipx（推荐）">
    独立安装，适合日常终端使用。需要 [pipx](https://pipx.pypa.io)。

    ```bash theme={null}
    pipx install "arka-agent[chat]"
    arka setup
    arka doctor
    ```

    若 PyPI 返回 404，可直接从 GitHub 安装（仍无需本地构建）：

    ```bash theme={null}
    pipx install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
    arka setup
    arka doctor
    ```
  </Tab>

  <Tab title="pip / venv">
    安装到现有虚拟环境或用户 site-packages。

    ```bash theme={null}
    python3 -m pip install "arka-agent[chat]"
    arka setup
    arka doctor
    ```
  </Tab>

  <Tab title="Git clone（贡献者）">
    仅在你**开发 Arka 本身**或需要修改仓库时使用。

    ```bash theme={null}
    git clone https://github.com/Sumit884-byte/arka.git
    cd arka
    ./scripts/refetch.sh --install
    arka setup
    ```
  </Tab>

  <Tab title="可编辑开发模式">
    适用于在仓库内进行开发的贡献者。

    ```bash theme={null}
    git clone https://github.com/Sumit884-byte/arka.git && cd arka
    python3 scripts/sync_bundled.py
    pip install -e ".[chat]"
    arka setup
    ```
  </Tab>
</Tabs>

### 在任意终端使用

安装完成后，打开**新**终端标签页（让 PATH 生效），然后运行：

```bash theme={null}
arka ask "what is Rust?"
arka "convert 100 USD to INR"
arka help
```

## 开始使用

<Steps>
  <Step title="配置 API 密钥">
    复制示例环境文件并至少添加一个提供商的密钥。

    ```bash theme={null}
    cp .env.example ~/.config/arka/.env
    ```

    快速上手的最小 `.env`：

    ```env theme={null}
    GEMINI_API_KEY=your_key_here
    GROQ_API_KEY=your_key_here
    AI_PREFERRED_PROVIDER=gemini
    AI_PREFERRED_MODEL=gemini-2.0-flash
    AGENT_SPEAK=1
    ```

    <Note>
      配置路径因操作系统而异。Linux 使用 `~/.config/arka/`，macOS 使用 `~/Library/Application Support/arka/`，Windows 使用 `%APPDATA%\arka\`。
    </Note>
  </Step>

  <Step title="验证安装">
    运行诊断以确认依赖和 API 密钥。

    ```bash theme={null}
    arka doctor
    ```
  </Step>

  <Step title="运行你的第一条命令">
    提出一个问题，看 Arka 将其路由到网络答案技能。

    ```bash theme={null}
    arka ask "what is Rust?"
    ```

    再试几个：

    ```bash theme={null}
    arka "convert 100 USD to INR"
    arka route "play bohemian rhapsody on spotify"
    arka help
    ```
  </Step>

  <Step title="个性化（可选）">
    选择兴趣，获取为你量身定制的技能推荐。

    ```bash theme={null}
    arka personalize wizard
    arka personalize recommend
    ```

    详见[个性化你的 Arka 体验](/cn/guides/personalize)，了解兴趣标签和非交互式选项。
  </Step>

  <Step title="安装 fish shell（可选）">
    Fish 可解锁完整的 70+ 技能路由。pip 包中自带 `config.fish`。

    ```bash theme={null}
    # macOS
    brew install fish

    # Linux
    apt install fish

    # Windows
    scoop install fish
    ```
  </Step>
</Steps>

## 可选附加组件

| 附加组件       | 增加内容                                |
| ---------- | ----------------------------------- |
| `[chat]`   | Agno、web 搜索、trafilatura、sympy、geopy |
| `[voice]`  | vosk、sounddevice                    |
| `[pdf]`    | PrivateGPT 客户端                      |
| `[charts]` | matplotlib                          |
| `[all]`    | 以上全部                                |

```bash theme={null}
pip install "arka-agent[all]"
```

## 下一步

按侧边栏顺序阅读，或直接跳到你需要的部分：

<CardGroup cols={2}>
  <Card title="CLI 参考" icon="terminal" href="/cn/guides/cli">
    所有命令、别名和子命令。
  </Card>

  <Card title="技能目录" icon="puzzle-piece" href="/cn/guides/skills">
    你可以让 Arka 做的事。
  </Card>

  <Card title="路由工作原理" icon="route" href="/cn/concepts/routing">
    离线规则、LLM 回退与纠错层。
  </Card>

  <Card title="LLM 配置" icon="brain" href="/cn/concepts/llm">
    提供商、故障切换和按技能模型。
  </Card>

  <Card title="配置" icon="settings" href="/cn/reference/configuration">
    环境变量、优先级和内置默认值。
  </Card>

  <Card title="语音" icon="microphone" href="/cn/guides/voice">
    唤醒词、STT 与 TTS 设置。
  </Card>
</CardGroup>


## Related topics

- [个性化你的 Arka 体验](/cn/guides/personalize.md)
- [Arka 简介](/cn/index.md)
- [MCP 集成](/cn/guides/mcp.md)
- [使用唤醒词、STT 和 TTS 的语音控制](/cn/guides/voice.md)
- [如何用 Arka 写代码](/cn/guides/code-with-arka.md)