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

# 配置、环境变量与 API 密钥设置

> 使用环境变量、.env 文件和配置路径来配置 Arka，并了解覆盖默认值和添加 API 密钥的优先级规则。

出于安全、故障切换和本地优先路由的考虑，Arka 默认已开启。仅当你想要覆盖某项或添加 API 密钥时才需要 `.env`。

## 配置路径

| 操作系统 | 配置 | 缓存 |
| - | - | - |
| Linux | `~/.config/arka/` | `~/.cache/arka/` |
| macOS | `~/Library/Application Support/arka/` | `~/Library/Caches/arka/` |
| Windows | `%APPDATA%\arka\` | `%LOCALAPPDATA%\arka\` |

可通过 `ARKA_CONFIG_DIR`（或 `CONFIG_DIR`）、`INSTALL_HOME`（旧版 `ARKA_HOME`）或 `ARKA_CACHE_DIR`（或 `CACHE_DIR`）覆盖。

设置 `ARKA_CONFIG_DIR=/path/to/my-arka-config` 会将**所有**用户配置移到该处：包括 `.env`、`mcp.json`、`hub/`、`agent-memory/`、`skills/` 及相关路径。

```bash theme={null}
# 显示当前根路径 + shell 导出片段
arka config path

# 初始化新的配置目录（不会自动移动）
arka config init --dir ~/my-arka-config

# 备份 / 恢复整个配置树
arka config backup -o ~/backups/arka-2026-07-11.tar.gz
arka config restore ~/backups/arka-2026-07-11.tar.gz

# 列出路径与大小
arka config list
```

用户配置包含 `.env`、`charts.yaml`、`llm-skill-models.json` 和 `skills/`（插件）。

## 优先级

| 层级 | 说明 | 何时生效 |
| - | - | - |
| Shell 环境 | `export GEMINI_API_KEY=…` | 进程中已设置时 |
| 用户 `.env` | `~/.config/arka/.env` | 启动时填充未设置的变量 |
| 开发目录 `.env` | git 克隆中的 `arka/.env` | 填充尚未设置的变量 |
| 旧版 fish `.env` | `~/.config/fish/.env` | 若存在仍会读取 |
| 代码默认值 | 内置于 Python / `config.fish` | 变量缺失时 |

诸如 `your_gemini_api_key_here` 的占位值会被忽略。

## 键名

优先使用短名称。旧版 `ARKA_*` 键仍可用（`ARKA_ROUTE_MODE` → `ROUTE_MODE`）：

```env theme={null}
ROUTE_MODE=symbolic
LLM_AUTO_FALLBACK=1
AGENT_SPEAK=1
SECURITY=1
```

## 内置默认值

| 领域 | 默认值 | 覆盖方式 |
| - | - | - |
| 安全 | 所有层开启（`SECURITY=1`） | 将任一层设为 `0` |
| NL 路由 | 优先离线规则（`ROUTE_MODE=symbolic`） | `ai`、`symbolic_only`、`ai_only` |
| LLM 故障切换 | 遇 429/401/超时自动切换（`LLM_AUTO_FALLBACK=1`） | `LLM_AUTO_FALLBACK=0` |
| 模型策略 | 优先尝试本地再托管（`ARKA_MODEL_POLICY=local-first`） | `hosted-first`、`local-only`、`hosted-only`（参见[查找免费模型](/cn/guides/free-models)） |
| 密钥轮换 | 先轮换备份密钥（`API_KEY_ROTATION=1`） | `API_KEY_ROTATION=0` |
| 语音 TTS | 朗读回复（`AGENT_SPEAK=1`） | `AGENT_SPEAK=0` |
| 唤醒监听 | 关闭直至 `arka listen` | `AGENT_WAKE_AUTO=1` |
| 记忆 | 有密钥时使用云端，否则本地（`MEMORY=auto`） | `local` 或 `supermemory` |
| 目标代理 | 25 步（`GOAL_MAX_STEPS=25`） | `GOAL_MAX_STEPS=30` |
| YouTube 研究 | 2 个视频（`YT_RESEARCH_MAX=2`） | `--limit N` 或环境变量 |
| 提醒 | 默认 1 小时（`REMIND_DEFAULT=1h`） | 传入显式时间 |
| 模型标签 | 在答案下方显示（`SHOW_MODEL=1`） | `SHOW_MODEL=0` |
| 网络搜索超时 | 每次 DuckDuckGo 调用 20 秒（`DDGS_TIMEOUT=20`） | 任意 ≥ 5 的整数 |
| 网络搜索重试 | 放弃前尝试 2 次（`DDGS_RETRIES=2`） | 任意 ≥ 1 的整数 |

网络搜索失败不会阻塞聊天：若 DuckDuckGo 每次重试都超时或报错，聊天会记录错误并改用模型知识回答，而不是让回复卡住。在网络较慢或不稳定时可调高两项：

```env theme={null}
DDGS_TIMEOUT=30
DDGS_RETRIES=3
```

## 关键 API 密钥

```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
```

可从 [Google AI Studio](https://aistudio.google.com) 和 [Groq Console](https://console.groq.com) 获取免费额度密钥。

## 可选附加组件

按需安装功能组：

| 附加组件 | 增加内容 |
| - | - |
| `[chat]` | 网络搜索、Agno、trafilatura、sympy |
| `[voice]` | vosk、sounddevice |
| `[pdf]` | PrivateGPT 客户端 |
| `[charts]` | matplotlib |
| `[drawings]` | Pillow、pymupdf |
| `[video]` | Pillow、edge-tts |
| `[all]` | 以上全部 |

## 应用更改

```bash theme={null}
arka reload              # 重新读取 .env + config.fish
arka reload --listen     # 同时重启唤醒监听
```

首次安装时，`arka setup` 会根据软件包模板初始化 `~/.config/arka/.env`。

## 完整参考

规范的环境变量参考：仓库中的 `src/arka/env.example`（约 500 行）。

<Note>
  故障切换详情参见 [LLM 编排](/cn/concepts/llm)。安全层参见[安全](/cn/concepts/security)。常见修复参见[故障排查](/cn/reference/troubleshooting)。
</Note>


## Related topics

- [多提供商故障切换的 LLM 编排](/cn/concepts/llm.md)
- [配置](/cn/guides/configuration.md)
- [Arka 故障排查：LLM、路由、语音与 RAG 修复](/cn/reference/troubleshooting.md)
- [自动 MCP 配置](/cn/guides/mcp-auto.md)
- [.env 设置](/cn/guides/env-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.