安装与快速开始

Deepaa 以 npm CLI 形式发布，支持 macOS 与 Windows。整个安装过程不需要克隆仓库。

让本地 Agent 帮你一键安装

复制下方提示词，粘贴给 Claude Code、Codex、Cursor 等任意本地 Agent，它会自动帮你完成安装与启动。

请帮我在本机安装并启动 Deepaa（本地优先的 AI Agent 网关与可观测性工具）：
1. 检查 Node.js 版本，需要 22 及以上；未安装或版本过低时，先安装 LTS 版本；
2. 执行 npm install -g deepaa 全局安装；网络缓慢时，可先将 npm registry 切换为 https://registry.npmmirror.com；
3. 安装完成后运行 deepaa 启动服务，浏览器会自动打开 http://localhost:3210（代理端口 3211）；
4. 启动后验证 Web UI 可以正常访问，并把访问地址告诉我。

macOS 安装

适用于 Apple Silicon 与 Intel 芯片。

1. 安装 Node.js（已安装可跳过）

brew install node

2. 安装 Deepaa CLI

npm install -g deepaa

3. 启动

deepaa

4. 设为系统服务（可选，开机自启 + 崩溃自动恢复）

deepaa service install

默认端口：Web UI `http://localhost:3210`，代理 `http://localhost:3211`。数据目录 `~/.deepaa`。安装后「应用程序」中自动出现 DeepAA 快捷入口。

Windows 安装

适用于 Windows 10/11，在 PowerShell 或 Windows Terminal 中执行。

1. 安装 Node.js（已安装可跳过）

# 从 https://nodejs.org 下载 LTS 安装包
# 国内镜像：https://npmmirror.com/mirrors/node/

2. 安装 Deepaa CLI

npm install -g deepaa

3. 启动

deepaa

4. 设为系统服务（可选，开机自启 + 崩溃自动恢复）

deepaa service install

若 PowerShell 执行策略限制全局安装，请以管理员身份运行，或改用 cmd。安装后「开始菜单」中自动出现 DeepAA 快捷入口。

⚡

国内网络加速

国内用户通过 npmmirror 镜像可以显著提升下载速度。

1. 配置 npm 镜像（推荐，一次配置长期生效）

npm config set registry https://registry.npmmirror.com

2. 或单次安装时指定镜像

npm install -g deepaa --registry=https://registry.npmmirror.com

3. Node.js 安装包国内镜像

https://npmmirror.com/mirrors/node/

GitHub 访问缓慢时，也可在镜像站点获取 Node 安装包；npm 依赖全部走 npmmirror 即可。

源码构建

适合开发与贡献代码，需要 Node.js 22+ 与 pnpm。

1. 克隆仓库

git clone https://github.com/AIAgentAndy/DeepAA

2. 安装依赖

cd DeepAA
pnpm install

3. 构建

pnpm build

4. 启动

pnpm start

构建一次后，`pnpm start` 直接启动生产模式，不会隐式重新构建。

Agent 客户端对接

配置 Claude Code 或 Codex 将流量路由到本地代理。

Claude Code

export ANTHROPIC_BASE_URL=http://localhost:3211/claude

支持 Anthropic Messages API 兼容格式。

Codex

export OPENAI_BASE_URL=http://localhost:3211/codex/v1

支持 OpenAI Chat Completions 兼容格式。模型 id 需带供应商目标前缀，格式为 `<targetId>_<modelId>`。

代理默认仅绑定 `127.0.0.1`。若需 LAN 访问，显式设置 `HOST=0.0.0.0` 并自行增加访问控制。

环境变量

运行时配置选项。

Variable	Default	Description
PORT	3210	Web UI 与 API 服务端口
PROXY_PORT	3211	本地反向代理端口
HOST	127.0.0.1	Web UI 与代理的默认绑定地址
DEEPAA_DATA_DIR	~/.deepaa	共享的原始捕获、blob、SQLite 与本地配置目录

PORT=4000 PROXY_PORT=4001 node ./bin/deepaa.mjs

CLI 命令一览

安装后即可使用的常用命令：

# 智能启动：缺哪个服务补哪个，就绪后自动打开控制台
deepaa

# 注册为系统服务（可选）：登录自启 + 崩溃自动恢复
deepaa service install

# 查看运行状态与服务注册状态
deepaa status

# 停止 Web 与代理（已注册服务仅停运行、保留注册）
deepaa stop

# 前台运行（开发/调试，Ctrl-C 停止）
deepaa open

# 查看全部命令
deepaa help

远程模型价格目录

Deepaa 的价格目录在官网远程发布，客户端自动拉取最新价格：

https://deepaa.dev/data/defaults/llm_catalog.jsonl

格式为 JSONL：首行为目录元信息（schemaVersion / catalogRevision / publishedAt / 汇率 / 节假日日历），其后每行一个供应商对象（含 models 价格明细）。`#` 与 `//` 注释行、空行会被消费端跳过。

数据存储

捕获的数据（包含 API key、prompt、响应）存储在 `~/.deepaa` 目录，包含：

data/captures/v2/capture-*.jsonl — 原始 JSONL 捕获文件
data/blobs/<sha256>.body.gz — 大型响应体 blob 存储
data/deepaa.sqlite — 索引与聚合视图
data/proxy-config.json — 本地代理配置

⚠️ 原始捕获可能包含敏感信息（API key、prompt、响应），请勿公开分享或推送到 git。