waku-agent

一个下午读完代码，本地运行你的个人 AI 助手

Waku agent 是一个本地优先的个人 AI 智能体框架，用 Python 编写，代码量少到可以在一个下午读完。它由四个核心模块组成：harness（运行环境）、loop（主循环）、memory（记忆存储）和 eval（评估），旨在解决个人 AI 助手在本地运行时的可读性、可控性和可评估性问题。它支持 OpenAI 和 Claude 等主流 LLM，使用 SQLite 存储记忆，强调透明和可审计的 AI 交互。用户可以通过简单的代码自定义智能体的行为，并利用内置的评估工具测试和优化其性能。该项目适合开发者快速构建和部署个人专属 AI 助手，尤其注重隐私和数据自主权。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1826

维护状态活跃

是否开源是

定价模式 free

项目数据

分类智能体

开发团队ShenSeanChen

所属国家

官网地址https://waku.one

GitHubhttps://github.com/ShenSeanChen/waku-agent

定价模式free

价格说明开源项目，MIT许可证，本地部署，完全免费。

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent-framework,ai-agent,ai-assistant,claude,evals,llm,llmops,local-first,openai,personal-assistant,python,sqlite

GitHub 星标★ 1826

30天Star增速

HF 下载量

上线时间2026-07-10 00:00:00

最近更新2026-09-23 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数4

使用教程

难度：入门约 10 分钟部署方式：本地安装 6 步

环境要求

Python 环境（README 未注明具体版本）
一个 LLM 服务商的 API Key（Anthropic 默认，也支持 OpenAI/Gemini/DeepSeek 等）
克隆源码方式需要 uv（用于 uv venv / uv pip / uv run）
可选：Telegram Bot Token，用于启用 Telegram 通道

安装与启动步骤

1克隆仓库

不想读代码可跳过本步，直接 pip install waku-agent；想读代码或参与贡献则克隆源码。
```
git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
```
2创建环境并安装

用 uv 建虚拟环境并以可编辑模式安装，注册出 waku 命令；uv run 无需激活环境。
```
uv venv && uv pip install -e .
```
3配置密钥

复制模板生成 .env，然后挑一个服务商、粘贴一个 key；首次运行也会提示该设置哪个 key。
```
cp .env.example .env
```
4终端对话

在终端里直接和 Waku 对话，首次运行会提示需要配置哪个密钥。
```
uv run waku
```
5启动面板

启动本地 Web 面板，浏览器访问 http://localhost:7777，可看到每个 turn 的流转过程。
```
uv run waku dashboard
```
6启用 Telegram

可选：在 .env 中设置 TELEGRAM_BOT_TOKEN，dashboard 启动时会同时拉起你的 bot。

关键配置

配置项	必填	说明	示例
`WAKU_PROVIDER`	是	选择模型服务商，如 Anthropic（默认）、OpenAI、Gemini、DeepSeek、OpenRouter 等	`openai`
`TELEGRAM_BOT_TOKEN`	否	填入后 dashboard 启动时会同时运行 Telegram 机器人	`123456789:AAExampleTokenxxxxxxxx`

如何确认成功

终端里 waku 能正常回复；浏览器打开 http://localhost:7777 能看到 Overview 面板与聊天 dock。

常见问题

Q：uv run waku 需要先激活虚拟环境吗？

A：不需要，README 明确说 uv run waku … 无需激活。若想整个会话用裸命令 waku，可 source .venv/bin/activate 一次。

Q：怎么把 waku 命令装到全局？

A：在仓库目录执行 uv tool install .，之后任何地方都能直接用 waku dashboard。

Q：不想克隆源码怎么办？

A：直接 pip install waku-agent，然后运行 waku 进入终端对话、waku dashboard 打开面板。

Q：记忆数据存在哪里？

A：就是一个 SQLite 文件 .waku/state.db，可以直接打开查看内容。

Q：数据会不会上传到云端？

A：dashboard 是你机器上的小型 Web 服务器，绑定 127.0.0.1，处理在本地进程中进行，数据不离开本机。

注意事项

README 没有给出各服务商对应 API Key 的环境变量名，首次运行 waku 时会提示需要设置哪一个。
dashboard 默认地址是 http://localhost:7777，也可用 make dashboard 启动。
除 uv run 外还有两种等价用法：source .venv/bin/activate 后用裸 waku，或 uv tool install . 全局安装。
模型适配层约 60 行（waku/loop/models.py），切换服务商只需设置 WAKU_PROVIDER 并粘贴 key。

核心亮点

代码极简，核心逻辑可快速通读，便于二次开发
本地优先，数据存 SQLite，隐私可控
内置 eval 工具，可量化评估智能体表现

不足之处

文档/社区待观察
早期项目，生态和模板较少

适用场景

个人知识库问答助手
本地自动化任务执行
AI 行为实验与评估

替代项目

LangChain、AutoGPT、CrewAI

项目介绍

waku-agent 是智能体领域的开源项目，由 ShenSeanChen 开发，是 2026 年新上线的项目。

在全站 13,090 个收录项目中，它的 GitHub 星标数（1,826）位列前 30%，在智能体分类中处于中上游。

近 42 天，它的 GitHub 星标从 1,295 增加到 1,826，净增 531。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-23。MIT许可证，本地部署，完全免费。

它主要面向的使用场景是：个人知识库问答助手。同类可对比的替代方案包括 LangChain、AutoGPT、CrewAI。

上一篇：PokeClaw

下一篇：knowledge-agent-template