waku-agent

环境要求

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

安装与启动步骤

1. 1克隆仓库

   不想读代码可跳过本步，直接 pip install waku-agent；想读代码或参与贡献则克隆源码。

   git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent

   复制

2. 2创建环境并安装

   用 uv 建虚拟环境并以可编辑模式安装，注册出 waku 命令；uv run 无需激活环境。

   uv venv && uv pip install -e .

   复制

3. 3配置密钥

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

   cp .env.example .env

   复制

4. 4终端对话

   在终端里直接和 Waku 对话，首次运行会提示需要配置哪个密钥。

   uv run waku

   复制

5. 5启动面板

   启动本地 Web 面板，浏览器访问 http://localhost:7777，可看到每个 turn 的流转过程。

   uv run waku dashboard

   复制

6. 6启用 Telegram

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

关键配置

如何确认成功

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

常见问题

注意事项

• 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。