kayaclaw/kayaclaw

# kayaclaw 一个在经过加固的 Docker 容器中运行的个人 AI agent。前端接入 Telegram，使用 SQLite 作为记忆存储，通过配置文件选择您偏好的 LLM 提供商。于新加坡开发。采用 MIT 许可证。 ## 当前可用功能 (0.1) 1. **Telegram 连接器**，仅支持文本，使用单一 chat-id 白名单（`ALLOWED_TELEGRAM_CHAT_IDS` 环境变量）。 2. **DeepInfra 提供商**，通过兼容 OpenAI 的 API 实现端到端访问。默认模型：Llama 3.3 70B Instruct。 3. **PydanticAI 运行时**，支持与模型无关的工具调用。自带您的 LLM：当今大多数主流提供商都使用通用的 HTTP 格式，kayaclaw 支持所有这些提供商（DeepInfra、OpenRouter、Groq、Together、您自托管的 vLLM）。只需修改一行配置，即可切换不同的模型。 4. **SQLite 记忆**，存储在命名的 Docker 卷中，保留每个聊天记录，并在容器重启后依然存在。 5. **加固容器**：`docs/discovery/container/SECURITY.md` 中的 20 项控制措施已验证了 16 项（其余 4 项延期项已被明确跟踪）。 6. **本地 Docker** 部署。使用 `docker compose up` 即可完成部署。 7. **提供商注册表** 从 `config.yaml` 加载。默认配置了 DeepInfra。Schema 支持在不修改代码的情况下添加更多提供商。 8. **品牌解耦代码**：项目名称仅存在于两个源文件（`pyproject.toml`、`agent/__about__.py`）中。 9. **公开代码库**，采用 MIT 许可证，`NOTICES.md` 中注明了第三方依赖的版权声明。 10. **README** 记录了可用功能、开发中功能以及明确不在 0.x 版本规划内的内容。 ## 状态 0.1 版本的代码量很少，足以在一个坐下来的时间段内读完。三个深思熟虑的选择使其保持了精简： - 库的充分利用。PydanticAI 处理 LLM 协议，python-telegram-bot 处理 bot 生命周期，使用标准库中的 sqlite3。 - 严格的范围。一个连接器，一个受信任的用户，没有插件系统，没有管理 UI。 - 将反臃肿作为一种准则。每个模块都有硬性的大小上限，由 CI 中的 `bash scripts/loc.sh` 强制执行。新功能必须证明其存在的价值，否则就不会被发布。 ## 快速开始 前置条件：带有 Compose v2 插件的 Docker 20.10+。使用 `docker compose version` 进行验证。 克隆并复制模板： ``` git clone https://github.com/kayaclaw/kayaclaw && cd kayaclaw cp .env.example .env cp config.example.yaml config.yaml ``` 在 `.env` 中填入以下三个值： - 来自 [@BotFather](https://t.me/BotFather) 的 `TELEGRAM_BOT_TOKEN` - 来自 [@userinfobot](https://t.me/userinfobot) 的 `ALLOWED_TELEGRAM_CHAT_IDS` - 来自 [openrouter.ai](https://openrouter.ai) 的 `OPENROUTER_API_KEY`。示例默认附带 OpenRouter 作为起点，因为一个密钥即可获取多种模型（Llama、Claude、Gemini 等）。您可以切换到 DeepInfra、Groq 或任何兼容 OpenAI 的提供商；详情请参阅下文的“切换提供商”。 启动服务： ``` docker compose up -d ``` 从您加入白名单的 Telegram 聊天中发送消息。bot 会通过配置的 LLM 进行回复。 如果未回复，请使用 `docker compose logs -f` 检查日志。使用 `docker compose down` 停止。 ## 切换提供商 kayaclaw 适用于任何支持兼容 OpenAI 的 HTTP 格式的提供商。无论该提供商提供什么模型，您都可以将您的 agent 指向它。以下配置是起点。相同的格式适用于该提供商提供的任何其他模型：将其列在 `allowed_models` 中，并在 `agents.personal-assistant.model` 中引用它。 ### DeepInfra（默认） DeepInfra 在其自有基础设施上托管开源模型。在 [deepinfra.com](https://deepinfra.com) 注册，创建 API 密钥，在您的 `.env` 中设置 `DEEPINFRA_API_KEY`。`config.example.yaml` 中的默认配置使用 Llama 3.3 70B Instruct。DeepInfra 提供的任何模型都以相同的方式工作。 ### OpenRouter OpenRouter 通过一个兼容 OpenAI 的端点路由到许多上游模型。在 [openrouter.ai](https://openrouter.ai) 注册，创建 API 密钥，在您的 `.env` 中设置 `OPENROUTER_API_KEY`，然后在 `config.yaml` 中选择任意模型。 Llama 3.3 70B Instruct： ``` providers: openrouter: kind: openai_compatible base_url: https://openrouter.ai/api/v1 api_key_env: OPENROUTER_API_KEY allowed_models: - meta-llama/llama-3.3-70b-instruct agents: personal-assistant: model: openrouter/meta-llama/llama-3.3-70b-instruct system_prompt: "You are a helpful assistant." connectors: - telegram ``` Anthropic Claude (sonnet-4.5)： ``` providers: openrouter: kind: openai_compatible base_url: https://openrouter.ai/api/v1 api_key_env: OPENROUTER_API_KEY allowed_models: - anthropic/claude-sonnet-4.5 agents: personal-assistant: model: openrouter/anthropic/claude-sonnet-4.5 system_prompt: "You are a helpful assistant." connectors: - telegram ``` Google Gemini 2.0 Flash： ``` providers: openrouter: kind: openai_compatible base_url: https://openrouter.ai/api/v1 api_key_env: OPENROUTER_API_KEY allowed_models: - google/gemini-2.0-flash-001 agents: personal-assistant: model: openrouter/google/gemini-2.0-flash-001 system_prompt: "You are a helpful assistant." connectors: - telegram ``` 任何其他 OpenRouter 提供的模型都以相同的方式工作：将其列在 `allowed_models` 中，并在 `agents.personal-assistant.model` 中引用它。 ### Groq Groq 在其自有的推理硬件上运行开源模型。在 [console.groq.com](https://console.groq.com) 注册，创建 API 密钥，在您的 `.env` 中设置 `GROQ_API_KEY`。Llama 3.3 70B Versatile： ``` providers: groq: kind: openai_compatible base_url: https://api.groq.com/openai/v1 api_key_env: GROQ_API_KEY allowed_models: - llama-3.3-70b-versatile agents: personal-assistant: model: groq/llama-3.3-70b-versatile system_prompt: "You are a helpful assistant." connectors: - telegram ``` 任何其他 Groq 提供的模型都以相同的方式工作。 ### 回退链 如果主要的 LLM 调用失败，kayaclaw 可以按顺序尝试备选项。每个条目使用与 `agents..model` 相同的 `/` 格式。provider 键必须已存在于 `providers:` 中，并且该模型必须在该 provider 的 `allowed_models` 中。在 `config.yaml` 中添加一个顶级的 `fallback:` 块： ``` fallback: - groq/llama-3.3-70b-versatile - deepinfra/meta-llama/Llama-3.3-70B-Instruct ``` 顺序很重要；最多限制为 5 个条目。每次尝试都是一次计费的 LLM 调用。 当整个链路在单条用户消息上耗尽时，bot 将回复 `"Having trouble reaching the LLM right now, please try again in a minute."` 并在 CRITICAL 级别记录故障摘要。 ## 验证安全态势 kayaclaw 是独立可验证的，而不仅仅是口头声明： - **容器加固清单：** [`docs/discovery/container/SECURITY.md`](docs/discovery/container/SECURITY.md)。已实施 16 项控制措施，4 项推迟至第二阶段。每项控制都有一个可运行的 `docker inspect` 或 `docker run` 验证命令。任何人都可以克隆代码库并重新验证每项声明。 - **漏洞披露政策：** [`SECURITY.md`](SECURITY.md)。说明了如何通过 GitHub Security Advisories 或 `security@kayaclaw.ai` 私下报告安全问题。 - **实时容器检查：** 在 `docker compose up` 之后执行 `docker inspect kayaclaw-agent-1 -f '{{.HostConfig.ReadonlyRootfs}} {{.HostConfig.CapDrop}} {{.HostConfig.SecurityOpt}}'` 将返回 `true [ALL] [no-new-privileges:true]`。 ## 1.x 版本讨论的起点 以下内容被明确排除在 0.x 版本的范围之外。小巧精炼正是其价值主张；在没有明确理由的情况下添加其中任何一项都会削弱这种价值。如果您想提出添加的理由，请开启一个 issue： - Web UI / 仪表板 - 多用户、多租户或多 bot 部署 - WhatsApp、Slack、Discord、Gmail 连接器 - 超出文本回复范围的工具/函数调用（无文件操作、网络搜索或容器内执行 bash） - 计划任务 / cron - 基于成本的路由或按消息的路由 - VPS 部署自动化 - 流式响应 - 向量召回 / RAG - 情景记忆摘要 - 图像、音频、视频输入 ## 许可证 MIT。请参阅 [`LICENSE`](LICENSE) 和 [`NOTICES.md`](NOTICES.md) 了解第三方归属声明。 ## 来源 kayaclaw 是对 [NanoClaw](https://github.com/qwibitai/nanoclaw) 容器安全态势的净室重新实现，使用 Python 编写。NanoClaw 仅作为设计参考。本项目中不包含任何 NanoClaw 的源代码。可以使用 `git log --all --full-history -- agent/` 验证净室声明。完整的归属信息请参见 [`NOTICES.md`](NOTICES.md)。

标签：DeepInfra, DLL 劫持, DNS解析, Docker Compose, Docker容器, Llama 3.3, LLM集成, Made in Singapore, OpenRouter, PydanticAI, Python, python-telegram-bot, SQLite, Telegram机器人, Together AI, vLLM, 个人AI助手, 大语言模型, 安全加固容器, 安全控制, 开源项目, 持久化记忆, 提示词注入, 攻击面发现, 无后门, 本地部署, 聊天记录, 自托管LLM, 请求拦截, 跨平台模型, 轻量级应用, 逆向工具, 配置驱动