🐾 PocketPaw

一款在您本地运行的 AI 助手，而非依赖他人的服务器。

自托管的 AI 助手，配备原生桌面应用和 Web 控制面板。可通过 Discord、Slack、WhatsApp、Telegram 或浏览器与您交流。
无需订阅，无云端锁定，您的数据始终保留在本地设备上。

⚠️ 测试版： 本项目仍在积极开发中，版本间可能存在不兼容的变更。

快速入门

桌面应用（推荐）

下载原生桌面应用，它集成了后端安装程序，并提供功能齐全的用户界面，包括系统托盘、全局快捷键、侧边栏以及多窗口支持。

通过终端安装

pip install pocketpaw && pocketpaw

# 1. 验证 Python 版本（必须是 3.11+）
python3 --version

# 2. 将 pip 升级到最新版本
python3 -m pip install --upgrade pip

# 3. 创建并激活虚拟环境（可选但建议）
python3 -m venv pocketpaw-env
source pocketpaw-env/bin/activate

# 4. 安装 PocketPaw
pip install pocketpaw

# 5. 运行 PocketPaw
pocketpaw

curl -fsSL https://pocketpaw.xyz/install.sh | sh

powershell -NoExit -Command "iwr -useb https://pocketpaw.xyz/install.ps1 | iex"

'pocketpaw' 不是内部或外部命令

C:\Users\<your-username>\AppData\Local\Python\Python3.XX\Scripts

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

python -m pocketpaw

pipx install pocketpaw && pocketpaw    # 隔离式安装
uvx pocketpaw                           # 无需安装即可运行

# 从源代码安装
git clone https://github.com/pocketpaw/pocketpaw.git
cd pocketpaw && uv run pocketpaw

git clone https://github.com/pocketpaw/pocketpaw.git && cd pocketpaw
cp .env.example .env
docker compose up -d

docker exec pocketpaw cat /home/pocketpaw/.pocketpaw/access_token

Web 仪表板将在 http://localhost:8888 打开。您可以通过它连接 Discord、Slack、WhatsApp 或 Telegram。

🔑 设置您的第一个 API 密钥

如果首次运行时仪表板显示 UNHEALTHY，通常说明 PocketPaw 已正确安装，您只需配置至少一个模型提供商（API 密钥或本地模型）即可。

1. 在仪表板中打开 Settings > API Keys。
2. 为至少一个提供商添加密钥：
   • Anthropic：console.anthropic.com/settings/keys
   • OpenAI：platform.openai.com/api-keys
   • Google Gemini：aistudio.google.com/apikey
3. 保存设置并重新尝试聊天。

[!TIP] 高级用户 / Docker / 无界面模式： 您也可以通过环境变量而非仪表板来设置 API 密钥。使用 POCKETPAW_ANTHROPIC_API_KEY、POCKETPAW_OPENAI_API_KEY 或 POCKETPAW_GOOGLE_API_KEY。完整列表请参阅 Configuration。

如果您更倾向于免费的本地选项，可以使用 Ollama（详见 Features 和 Configuration）。

功能特性

示例

你：  “每个周日晚上提醒我该把哪些回收箱拿出来”
Paw： 好的。我会查看回收日历，并在每周日晚上 6 点给你发消息。

你：  “找到那个内存泄漏问题，应用运行两小时就会崩溃”
Paw： 找到了。WebSocket 处理程序没有关闭连接。这是修复方案。

你：  “我需要一份关于我们产品发布的竞争对手分析报告”
Paw： 有 3 个代理正在处理。准备好后我会通知你。

架构设计

所有流程都通过事件驱动的消息总线进行。各个渠道发布消息，AgentLoop 接收并路由到您配置的后端。六种后端都实现了相同的 AgentBackend 协议，因此更换其中一种不会影响系统的其他部分。

桌面客户端（client/）是一个基于 Tauri 2.0 和 SvelteKit 的应用，通过 REST 和 WebSocket 与 Python 后端通信。它提供系统托盘集成、全局快捷键、多窗口支持（侧边栏、快速提问）以及用于处理后端安装的引导向导。

代理后端

安全性

二级 LLM（Guardian AI）会在每次工具调用前对其进行审查。此外，还有注入扫描、可配置的工具策略、需人工批准的计划模式、--security-audit 命令行选项、自审计守护进程以及追加式的审计日志。更多详情请参阅文档：pocketpaw.xyz/security。

配置

设置信息存储在 ~/.pocketpaw/config.json 中。您也可以使用以 POCKETPAW_ 开头的环境变量，或者通过仪表板的设置面板进行配置。API 密钥在静止状态下会被加密。

环境变量（.env 文件）

PocketPaw 自带一个 .env.example 文件，其中列出了所有支持的环境变量，并附有内联注释。在运行 PocketPaw 之前（尤其是从源代码克隆或使用 Docker 时），请将其复制到 .env 并填写所需的值：

# macOS / Linux
cp .env.example .env

# Windows（PowerShell）
Copy-Item .env.example .env

然后在编辑器中打开 .env 文件，取消注释并设置与您的配置相关的变量。例如：

# 大模型提供商
POCKETPAW_ANTHROPIC_API_KEY=sk-ant-...
POCKETPAW_AGENT_BACKEND=claude_agent_sdk   # 或 openai_agents、google_adk 等

# 可选：Telegram 机器人
POCKETPAW_TELEGRAM_BOT_TOKEN=...
POCKETPAW_ALLOWED_USER_ID=...

提示： 在 .env 中设置的变量会在启动时自动加载。您也可以直接在 shell 中导出这些变量，或者通过仪表板的 Settings 面板进行设置——这三种方法可以互换使用。

另外，您也可以直接在 shell 中导出变量：

export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."   # 使用 Claude SDK 后端时必需
export POCKETPAW_AGENT_BACKEND="claude_agent_sdk"  # 或 openai_agents、google_adk 等

注意： 使用 Claude SDK 后端时，必须提供来自 console.anthropic.com 的 Anthropic API 密钥。Claude Free/Pro/Max 计划中的 OAuth 令牌根据条款规定不允许第三方使用。如需免费的本地推理，建议使用 Ollama。

有关所有设置的详细参考，请参阅 配置指南。

开发

后端（Python）

先决条件：

• Python 3.11 或更高版本（在此下载）
• uv 包管理器

安装 uv：

[!WARNING] Windows 用户： 在运行下方安装脚本后，必须 打开一个新的终端窗口，uv 才会被识别。安装程序会更新您的 PATH 环境变量，但此更改不会应用于当前的终端会话——如果在安装后立即运行 uv，将会出现 CommandNotFoundException 错误。

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或通过 pip 安装
pip install uv

[!TIP] Windows： 若要在不打开新终端的情况下立即使用 uv，请运行：

$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

然后验证安装：uv --version

设置与运行：

# 1. 验证 Python 版本
python3 --version

# 2. 克隆并进入仓库
git clone https://github.com/pocketpaw/pocketpaw.git && cd pocketpaw

# 3. 安装开发依赖
uv sync --dev

# 4. 以开发模式运行 PocketPaw（自动重载）
uv run pocketpaw --dev

# 5. 运行测试
uv run pytest --ignore=tests/e2e    # 运行测试（2900+）

# 6. 代码检查与格式化
uv run ruff check . && uv run ruff format .

pip install pocketpaw[openai-agents]       # OpenAI Agents 后端
pip install pocketpaw[google-adk]          # Google ADK 后端
pip install pocketpaw[discord]             # Discord
pip install pocketpaw[slack]               # Slack
pip install pocketpaw[memory]              # Mem0 语义记忆
pip install pocketpaw[all]                 # 全部功能

桌面客户端（Tauri + SvelteKit）

原生桌面应用位于 client/ 目录下。它通过 REST/WebSocket 与 Python 后端连接。

先决条件：

• Bun（包管理器）
• Rust（用于 Tauri）
• Python 后端正在 localhost:8888 上运行

cd client
bun install                    # 安装依赖
bun run dev                    # Vite 开发服务器（http://localhost:1420）
bun run tauri dev              # 完整桌面应用（前端 + Tauri 框架）
bun run check                  # 类型检查
bun run tauri build            # 生产构建

技术栈： SvelteKit 2 + Svelte 5、Tailwind CSS 4、shadcn-svelte、Tauri 2.0（Rust）。完整架构详情请参阅 client/CLAUDE.md。

文档

pocketpaw.xyz 涵盖入门指南、后端、渠道、工具、集成、安全、记忆以及完整的 API 参考。

星标历史

贡献者

加入团队

• Twitter：@prakashd88
• Discord：discord.gg/asRrtm95Zc
• 邮箱：pocketpawai@gmail.com

欢迎提交 PR。一起共建吧。

许可证

MIT © PocketPaw 团队

专为那些更愿意拥有自己的 AI 而非租用它的人打造

PocketPaw 快速上手指南

PocketPaw 是一款运行在您本地机器上的自托管 AI 智能体。它拥有原生桌面应用和 Web 仪表盘，支持通过 Discord、Slack、WhatsApp、Telegram 或浏览器与您交互。无订阅费，无云端锁定，数据完全保留在本地。

⚠️ 注意：本项目目前处于 Beta 阶段，正在积极开发中，版本间可能存在不兼容的变更。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows (x64), macOS (Intel/Apple Silicon), 或 Linux。
• Python 版本：Python 3.11 或更高版本（终端安装必需）。
  • 下载地址：python.org
  • Windows 用户特别注意：安装 Python 时务必勾选 "Add Python to PATH"。
• 包管理器：pip（随 Python 自动安装）。

安装步骤

您可以选择下载原生桌面应用（推荐）或通过终端命令安装。

方式一：下载原生桌面应用（推荐）

桌面应用集成了后端安装程序，并提供系统托盘、全局快捷键、侧边栏等完整功能。

方式二：通过终端安装 (macOS / Linux)

1. 快速安装（单行命令）：

pip install pocketpaw && pocketpaw

2. 推荐安装（使用虚拟环境）：

# 1. 验证 Python 版本 (必须 3.11+)
python3 --version

# 2. 升级 pip
python3 -m pip install --upgrade pip

# 3. 创建并激活虚拟环境
python3 -m venv pocketpaw-env
source pocketpaw-env/bin/activate

# 4. 安装 PocketPaw
pip install pocketpaw

# 5. 运行
pocketpaw

3. 自动化脚本安装：

curl -fsSL https://pocketpaw.xyz/install.sh | sh

方式三：通过终端安装 (Windows PowerShell)

选项 A：自动安装脚本（推荐）

powershell -NoExit -Command "iwr -useb https://pocketpaw.xyz/install.ps1 | iex"

选项 B：手动安装

# 1. 验证 Python 版本
python --version

# 2. 升级 pip
python -m pip install --upgrade pip

# 3. (可选) 创建虚拟环境
python -m venv pocketpaw-env
.\pocketpaw-env\Scripts\Activate.ps1

# 4. 安装 PocketPaw
pip install pocketpaw

# 5. 启动仪表盘
pocketpaw

如果运行 pocketpaw 提示命令未找到，请尝试使用 python -m pocketpaw 或将 Python Scripts 目录添加到系统环境变量 PATH 中。

方式四：Docker 部署

git clone https://github.com/pocketpaw/pocketpaw.git && cd pocketpaw
cp .env.example .env
docker compose up -d

• 仪表盘地址：http://localhost:8888
• 获取访问令牌：docker exec pocketpaw cat /home/pocketpaw/.pocketpaw/access_token

基本使用

安装完成后，按照以下步骤配置并开始使用：

1. 访问仪表盘

在浏览器中打开 http://localhost:8888。

提示：首次启动时，系统健康状态可能显示为 UNHEALTHY。这是正常现象，因为尚未配置任何 AI 模型提供商。

2. 配置 API Key

要让 AI 功能正常工作，您需要配置至少一个模型提供商：

1. 在仪表盘中进入 Settings > API Keys。
2. 添加以下任一服务的密钥：
   • Anthropic: console.anthropic.com/settings/keys
   • OpenAI: platform.openai.com/api-keys
   • Google Gemini: aistudio.google.com/apikey
3. 保存设置。

本地免费方案：如果您希望完全离线运行，可以安装 Ollama，PocketPaw 会自动检测本地的 Ollama 服务。

3. 开始对话

配置完成后，您可以在仪表盘直接对话，或连接外部渠道（Discord, Slack, Telegram 等）。

使用示例：

• 定时提醒：

  用户："Every Sunday evening, remind me which recycling bins to put out" PocketPaw: "Done. I'll check the recycling calendar and message you every Sunday at 6pm."

• 代码调试：

  用户："Find that memory leak, the app crashes after 2 hours" PocketPaw: "Found it. The WebSocket handler never closes connections. Here's the fix."

• 任务协作：

  用户："I need a competitor analysis report for our product launch" PocketPaw: "3 agents working on it. I'll ping you when it's ready."

现在，您已经成功启动了属于您自己的本地 AI 智能体！