dominicci13/openclaw-assistant

# OpenClaw Assistant 一个我运行在开源 [OpenClaw](https://github.com/openclaw/openclaw) agent gateway 上的 hardened、self-hosted 的个人助手——以 Claude 作为大脑，可通过 Telegram 访问（并在本地通过 Claude Desktop 访问）。基于 **security-first（安全优先）** 和 local-first（本地优先）原则构建，随后无需重写代码便迁移到了 VPS 上。 这个仓库也兼作作品集：展示了如何在 **将 model 视为潜在可被劫持** 的前提下，为一个 always-on agent 扩展真正的功能——邮件、cloud drives、日历、只读 GitHub 以及真正的 web 浏览器。采用最小权限 scopes、单一受审计的 egress chokepoint、无 delete/overwrite tool、每次发送需经过 consent gate，以及 prompt-injection defense in depth（深度提示注入防御）。它所接触的凭证是真正的“皇冠明珠”，因此该设计旨在 *限制被入侵的 model* ，而不仅仅是交付功能。 ## Security model - **Containment.** 使用 Docker、non-root、read-only rootfs、dropped capabilities，无 host Docker socket，零发布端口（Telegram 通过出站 long-polls 连接；没有任何外部拨入）。 - **单一受审计的 egress chokepoint.** gateway 位于一个没有出站路由的 `internal` Docker 网络上；一个 Squid proxy 执行 **default-DENY（默认拒绝）domain allowlist**，并且是连接到互联网的唯一路径——甚至包括 gateway→sidecar 的 RPC。egress log 即为审计跟踪记录。 - **Least privilege.** tool 默认被拒绝；仅启用最小集合。Shell/exec、filesystem 和 automation groups 保持拒绝状态。每项 capability 都是经过深思熟虑、逐个添加的，且各自位于独立的 credential-isolated sidecar 中。 - **无破坏性 tool.** 任何地方（邮件、drive、日历、GitHub）都 **没有 delete tool**，且 drives 绝不会覆盖——“modify（修改）”意味着读取 + 创建新内容。日历的就地更新是唯一记录在案的例外。 - **浏览受到限制且仅限公开内容.** 一个独立的 headless-Chromium sidecar 用于渲染 JS-heavy pages；它不持有 **任何 credentials**，其 remote-control port 受 token 保护，且只能由 gateway 访问，并且每一次页面抓取仍需通过 egress allowlist。其 scope 被刻意限制为公开——Claw 浏览是为了 *读取*（票价、日程、价格），而不是登录账户或提交表单。一个 DNS-only forwarder 允许 gateway 在不获得任何新出站路由的情况下 *解析* 主机名。 - **针对唯一对外操作的 consent gate.** 向外部收件人发送邮件需要一个 model 永远看不到的全新 TOTP code；发给自己则可豁免。 - **Prompt-injection defense in depth（深度提示注入防御）.** (1) system-prompt 规则——摄入的内容（电子邮件、网页、文件、仓库内容、图像/语音转录）是 *data, never instructions（数据，绝不是指令）*；(2) 对不可信内容进行结构化标签化；(3) 通过代码强制执行的 gate——被劫持的 model 没有任何无需同意即可发送 / 删除 / 写入 GitHub 的 tool 可以调用，也无法访问 allowlist 之外的域名。第 3 层是真正的边界。 - **Secrets isolation.** 每个 sidecar 仅持有自身的 provider credentials，以 read-only 方式挂载，绝不与 gateway 或彼此共享；通过 env/files 注入，绝不提交。 ## 邮件安全 Mail 可以读取、起草以及 **发送——但发送是受限的**。任何账户都不存在 delete tool。 | 账户 | 发送 | 删除 | |---|---|---| | Gmail | 外部收件人需 TOTP consent (`gmail.send`) | **token** (`readonly`+`compose`; delete → 403) | | Outlook | 外部收件人需 TOTP consent (`Mail.Send`) | tool 层级（无 delete tool） | | iCloud | 外部收件人需 TOTP consent (SMTP) | tool 层级（无 delete/expunge 代码） | | Claw (`claw.*@gmail.com`) | 用于 assistant→you 通知的 **send-only** 身份 (`gmail.send`) | 不适用（无读取/删除） | 仅发送给您自己地址的邮件会跳过该代码；任何外部收件人则必须经过该代码。电子表格附件由服务端根据数据生成（model 绝不会通过 base64 携带字节）。 ## 架构 ``` ┌─► mail sidecar (Gmail · Outlook · iCloud · Claw send-only) Telegram ─► openclaw- ├─► drive sidecar (OneDrive · Google Drive) (you) gateway ────┼─► calendar sidecar (Google · Outlook · iCloud) (Claude) ├─► github sidecar (read-only: repos, files, code search) │ └─► browser sidecar (headless Chromium — public pages only) │ │ name lookups ─► dns forwarder (resolves names; grants the gateway no egress) │ └─ all egress (incl. the RPC above) ─► openclaw-proxy (Squid) default-DENY allowlist ─► internet ``` - **openclaw-gateway** — OpenClaw agent (Claude)。不持有 **任何** provider credentials。 - **openclaw-proxy** — Squid；唯一的出站路径；default-DENY allowlist + audit log。 - **四个独立的 MCP sidecars** (`mcp-mail/`, `mcp-drive/`, `mcp-calendar/`, `mcp-github/`) —— 每个 都是自建的 Python MCP server，bearer-authed，仅持有各自的 credentials。mail sidecar 也支持用于 Claude Desktop 的 stdio 通信。 - **openclaw-browser** (`browser/`) — 一个 hardened headless-Chromium sidecar，gateway 通过 token-gated remote-CDP endpoint 对其进行驱动；不持有 credentials，其所有 egress 都被强制通过 proxy。 - **openclaw-dns** (`dns/`) — 一个 DNS-only forwarder，允许 gateway 解析主机名 （浏览器 SSRF 检查所需），而无需被授予任何通往互联网的路由。 ## 快速开始 需要 Docker。Secrets 通过未跟踪的 `.env` 文件和凭证挂载（已提供模板）提供： ``` cp .env.example .env # root: per-sidecar bearer tokens, TOTP, OpenAI key cp instance/config/.env.example instance/config/.env # gateway: telegram/anthropic/tavily/gateway token cp instance/config/openclaw.json.example instance/config/openclaw.json # set your Telegram user id # 按能力划分的 credentials（仅 sidecar，一次性同意）——参见每个 sidecar 的 README： # instance/{gmail,outlook,icloud,clawmail}/ mail (OAuth tokens / app passwords) # instance/{onedrive,gdrive}/ drive # instance/{gcal,mscal,icloudcal}/ calendar # instance/github/token 细粒度的 READ-ONLY GitHub PAT docker compose up -d # gateway + squid + dns forwarder + five sidecars ``` ## 布局 | 路径 | 角色 | |---|---| | `docker-compose.yml` | Gateway + Squid + DNS forwarder + 五个 sidecars；hardenings 配置在此处 | | `proxy/squid.conf` · `proxy/allowlist.txt` | Egress chokepoint：配置 + default-DENY allowlist | | `mcp-mail/` | Mail MCP server：3 个账户 + Claw send-only，send-with-consent，附件 | | `mcp-drive/` | Drive MCP server：OneDrive + Google Drive，读取 + 创建（无 delete/overwrite） | | `mcp-calendar/` | Calendar MCP server：Google + Outlook + iCloud，读取 + 创建 + 更新 | | `mcp-github/` | GitHub MCP server：只读的 repo/file/code 访问 | | `browser/` | Headless-Chromium CDP sidecar：渲染 JS 页面，仅限公开网站，无 credentials | | `dns/` | DNS-only forwarder：允许 gateway 解析名称而无需授予其 egress 权限 | | `instance/config/openclaw.json.example` | Hardened gateway 配置（已脱敏） | 实际的凭证、token、日志、agent workspace 以及上游 OpenClaw 的克隆 **均不** 被跟踪（见 `.gitignore`）。 ## 作者 由 **Brian Ramírez** ([@dominicci13](https://github.com/dominicci13)) 构建 —— 自动化 & AI 工作流专家。更多详情请见我的 [GitHub 主页](https://github.com/dominicci13) 和 [LinkedIn](https://linkedin.com/in/bdramirez)。

标签：AI助手, DLL 劫持, NIDS, 个人助理, 大语言模型, 容器化, 最小权限, 请求拦截, 逆向工具, 零信任架构