跳转至

安装

本页将引导你在 5 分钟内完成 OLAV 的安装和初始化。

功能声明

ID 声明 状态
C-L2-01 olav version 正确报告版本号 ✅ v0.10.0
C-L2-13 olav init 创建项目目录结构 ✅ v0.10.0

环境要求

依赖 说明
Python 3.11+ OLAV 的运行环境
LLM API Key 支持 OpenAI、Anthropic、Ollama（本地）等多种提供商

第一步：安装

pip install olav

git clone https://github.com/olav-ai/olav.git
cd olav
uv sync

开发模式

源码安装后，所有 olav 命令需加 uv run 前缀，如 uv run olav version。 以下文档示例均使用 pip install 后的裸 olav 命令。

验证安装是否成功：

olav version

看到类似输出即表示安装成功： 

Version:   v0.10.0

第二步：初始化项目

进入你的工作目录，运行：

olav init

olav init 会自动创建 .olav/ 目录和配置骨架，包括 api.json（LLM 配置）、数据库和核心 Agent。

第三步：配置 API Key

编辑 olav init 生成的 .olav/config/api.json，填入你的 API Key。

api.json 使用 shared.api_key 统一管理密钥——LLM 和 Embedding 共用同一个 Key，无需分别配置：

{
  "shared": { "api_key": "sk-..." },
  "llm": { "provider": "openai", "model": "gpt-4o" },
  "embedding": { "mode": "api", "api": { "model": "openai/text-embedding-3-small" } }
}


{
  "shared": { "api_key": "sk-ant-..." },
  "llm": { "provider": "anthropic", "model": "claude-3-5-sonnet-20241022" },
  "embedding": { "mode": "local" }
}
Anthropic 不提供 embedding API，使用本地模型（mode: local，自动下载 BAAI/bge）。

{
  "shared": { "api_key": "sk-or-..." },
  "llm": { "provider": "custom", "model": "openai/gpt-4o", "base_url": "https://openrouter.ai/api/v1" },
  "embedding": { "mode": "api", "api": { "model": "openai/text-embedding-3-small", "base_url": "https://openrouter.ai/api/v1" } }
}


{
  "llm": { "provider": "ollama", "model": "llama3.1", "base_url": "http://localhost:11434" },
  "embedding": { "mode": "local" }
}
完全离线，无需 API Key。

保护你的密钥

api.json 包含 API 密钥，务必加入 .gitignore（olav init 已自动处理）。

环境变量方式

不想在文件中存储密钥时，可通过环境变量覆盖（优先级高于 api.json）： 

export OLAV_LLM_API_KEY="sk-..."       # 覆盖 shared.api_key
export OLAV_LLM_MODEL="gpt-4o"         # 覆盖 llm.model
export OPENAI_API_KEY="sk-..."          # OpenAI 快捷方式
export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic 快捷方式

创建的目录结构如下：

.olav/
├── config/
│   ├── api.json        ← LLM 和认证配置（包含密钥，不要提交到 git）
│   ├── services.yaml   ← 已注册的外部服务
│   └── settings.json   ← 平台设置（当前活跃 Agent 等）
├── databases/
│   ├── audit.duckdb    ← 审计日志（自动记录所有操作）
│   └── domain.duckdb   ← 业务数据（Agent 执行结果等）
└── workspace/
    └── core/           ← 预装的核心 Agent
        ├── AGENT.md    ← Agent 的能力定义
        └── MANIFEST.yaml ← 路由关键词和版本信息

第四步：设置 .gitignore

工作空间（workspace）可以安全提交到 git，与团队共享 Agent 定义。但配置和数据库不应提交：

# .gitignore
.olav/config/      # 包含 API 密钥
.olav/databases/   # 包含审计日志和业务数据
.olav/run/         # 运行时 PID 文件

git add .olav/workspace/
git commit -m "feat: init olav workspace"

下一步： 运行你的第一个查询 →