## 欢迎贡献！Windows 优先！ [English](README.md) | [简体中文](README_zh.md)

轻量级 • 安全 • 实用的 Agent

# 📷 预览

📚 Professional Learning Helper	⏰ 24/7 Online News Collcetor	🔜 On Call Personal Life Assistant

# 🤔 为什么选择 CloseClaw - ⚡ **快速部署** - 轻量级、易于部署，并配备受保护的编排循环（orchestration loop）以确保稳健的性能。实用的个人 AI agent，一分钟内即可就绪。 - 🧠 **结构化记忆管理** - 结构化的记忆管理系统，包括长期记忆构建和向量化记忆检索支持。保证长期记忆。认知完全可定制。 - 🛡️ **有效的安全保障** - 清晰且严格的沙盒权限系统，包括守护者审查（Guardian-Review）机制和轻量级 Windows OS 级沙盒。不再担心 AI 幻觉删除您的收件箱。 - 💓 **主动执行** - 配备 Heartbeat 和 Cron 服务以支持处理任何计划任务，并定期唤醒以自动处理长期任务。主动 Agent，时刻与您同在。 - 🔌 **MCP 可扩展性** - 支持原生 MCP 可扩展性，兼容任何 OpenClaw 技能和工具。庞大的生态系统。轻松武装您的 agent。 # ✨ 核心特性 ### 👮 Guardian 监控设计 - Guardian Agent 会在执行前智能地审查动作，并拦截高影响的连接动作。 - 将 MCP/网络工具置于相同的安全策略下，允许在 `config.yaml` 中自由配置高风险工具监督池。 ### 🔒 共识模式 = 更安全的自动化 - 在 `consensus` 模式下，Guardian Agent 可以首先自动审查敏感调用。 - 在保持严格控制的同时减少持续的批准疲劳。 ### 🧱 坚实的本地基础 - `PathSandbox` 在 `workspace_root` 内部强制执行严格的本地边界。 - 在工具执行前阻止路径遍历和写入工作区外的操作。 ### 🪟 OS 级轻量级沙盒 - `受限令牌（Restricted Token）`、`低完整性和作业对象（Job-Object）约束` 为受保护工具（默认：`shell`）强制执行 OS 级别的受限执行。 - 高度可定制：只有 `os_sandbox_protected_tools` 中的工具支付隔离成本；低风险工具（例如 `read_file`）保持快速。 - 支持故障安全选项：当沙盒后端不可用时，`os_sandbox_fail_closed: true` 会阻止执行。 ``` Tool Call -> SafetyGuard -> PathSandbox -> Guardian/Auth -> OS-Level Sandbox -> Execute ``` # 📡 渠道支持 | Channel | 定位 | 启动提示 | | --- | --- | --- | | `CLI` | 💻 快速、本地且支持管道 | 本地交互式终端 | | `Telegram` | ✈️ 移动指挥中心（推荐） | 轮询已开始 | | `Feishu / Lark` | 🏢 专业工作流 | 打印 webhook 地址（主机/端口） | | `Discord` | 🎮 丰富的 Markdown 支持 | Gateway 已启动 | | `WhatsApp` | 🟢 通过桥接在网络上可达 | 打印桥接 URL | | `QQ` | 🐧 经典的中文社交生态系统 | Gateway 已启动 | WhatsApp 桥接协议详情： - [docs/WhatsApp_Bridge_Protocol.md](docs/WhatsApp_Bridge_Protocol.md) # 🤖 LLM 提供商 | Provider | 运行时路径 | 备注 | | --- | --- | --- | | `openai` / `openai-compatible` | 原生 provider 路径 | 默认友好，快速设置 | | `gemini` | LiteLLM 运行时 | 需要 `.[providers]` 额外依赖 | | `anthropic` | LiteLLM 运行时 | 需要 `.[providers]` 额外依赖 | # 🚀 快速开始 ### 1) 安装 ``` git clone https://github.com/closeclaw/closeclaw.git cd closeclaw pip install -e . ``` 可选额外依赖： ``` pip install -e ".[telegram]" pip install -e ".[discord]" pip install -e ".[whatsapp]" pip install -e ".[qq]" pip install -e ".[voice]" pip install -e ".[fastapi]" pip install -e ".[providers]" ``` ### 2) 创建配置 ``` cp config.example.yaml config.yaml ``` 最小配置： ``` agent_id: "closeclaw-main" workspace_root: "your/workspace" llm: provider: "openai-compatible" model: "gpt-4" api_key: "sk-..." base_url: "https://api.openai.com/v1" channels: - type: "cli" enabled: true safety: admin_user_ids: ["cli_user"] default_need_auth: false ``` ### 3) 运行 Agent 模式（仅 CLI）： ``` closeclaw agent --config config.yaml ``` Gateway 模式： ``` closeclaw gateway --config config.yaml ``` ### ✨ 这就是您的 agent！ ## 🐳 Docker（可选） Docker 支持是可选的。如果您希望获得可复制的运行时和更轻松的部署交接，请使用本节。 ### 1) 一次性准备（复制/粘贴） macOS/Linux： ``` cp .env.example .env cp config.example.yaml config.yaml mkdir -p workspace runtime-data ``` Windows PowerShell： ``` Copy-Item .env.example .env Copy-Item config.example.yaml config.yaml New-Item -ItemType Directory -Force -Path workspace, runtime-data ``` ### 2) 最小配置检查 在 `config.yaml` 中，确保： - `workspace_root: "/workspace"`（对于 Linux 容器很重要） - 至少为您目标模式启用了一个渠道： - `agent` 模式：可以启用 `cli` - `gateway` 模式：必须至少启用一个非 CLI 渠道 - 您的 provider/channel 依赖项包含在 `.env` 的 `INSTALL_EXTRAS` 中 - Telegram gateway 示例：`INSTALL_EXTRAS=[providers,telegram]` ### 3) 构建并启动（推荐 docker compose） ``` docker compose build docker compose up -d closeclaw-gateway docker compose ps docker compose logs -f closeclaw-gateway ``` ### 4) 健康验证（重要） Gateway 容器健康检查： ``` docker compose exec closeclaw-gateway closeclaw runtime-health --config /app/config.yaml --mode gateway --json ``` CLI 配置健康检查： ``` docker compose run --rm closeclaw-cli runtime-health --config /app/config.yaml --mode agent --json ``` 预期结果： - 退出代码 `0` - JSON 包含 `"healthy": true` ### 5) 常见错误（快速修复） - `workspace_root does not exist: /app/D:` - 原因：Linux 容器内的 `config.yaml` 使用了 Windows 路径。 - 修复：设置 `workspace_root: "/workspace"`。 - `No channels enabled for mode=gateway` - 原因：运行 gateway 模式时仅启用了 CLI。 - 修复：启用至少一个非 CLI 渠道。 - `python-telegram-bot is required` - 原因：镜像中未安装渠道依赖。 - 修复：设置 `.env` `INSTALL_EXTRAS=[providers,telegram]`，然后重新构建。 - `docker compose run --rm closeclaw-cli closeclaw ...` 失败 - 原因：重复的 `closeclaw` 命令。 - 修复：使用 `docker compose run --rm closeclaw-cli runtime-health ...`。 ### 6) 停止和清理 ``` docker compose down ``` ### 7) 可选冒烟测试脚本 使用 Bash 运行： ``` bash tests/test_docker.sh ``` 在 PowerShell 上，显式调用 Bash： ``` bash tests/test_docker.sh ``` 操作加固详情记录在 [docs/Docker_Runbook.md](docs/Docker_Runbook.md)。 ## 🎯 运行模式 | Mode | 运行内容 | 典型用途 | |---|---|---| | `agent` | 仅 CLI | 本地交互式调试 / 开发 | | `gateway` | 仅非 CLI 渠道 | Bot 网关部署 | | `all` | CLI + 所有启用的渠道 | 完整的本地集成运行 | ## 🧱 架构概览 ``` closeclaw/ ├─ runner.py # Runtime entry + channel/heartbeat/cron orchestration ├─ agents/ │ └─ core.py # AgentCore: orchestration loop and execution lifecycle ├─ services/ │ ├─ tool_execution_service.py # Tool routing + middleware + auth handling │ └─ context_service.py # Context shaping, compaction, transcript windowing ├─ memory/ │ └─ memory_manager.py # Memory retrieval and persistence coordination ├─ channels/ # CLI / Telegram / Feishu / Discord / WhatsApp / QQ adapters ├─ tools/ # File / Shell / Web / Scheduler / Memory helper tools └─ mcp/ # MCP transport, pool, bridge, and health integration ``` ### 核心职责 - `runner`：启动编排（channels, heartbeat, cron, agent 生命周期） - `AgentCore`：编排循环 + 工具决策和执行流程 - `ToolExecutionService`：工具路由、中间件、认证交互 - `ContextService`：记录整形（transcript shaping）和压缩策略 - `MemoryManager`：记忆检索和持久化层 ### 主要模块 - `closeclaw/runner.py` - `closeclaw/agents/core.py` - `closeclaw/services/tool_execution_service.py` - `closeclaw/services/context_service.py` - `closeclaw/memory/memory_manager.py` ## 🔐 安全模型 CloseClaw 采用分层控制： 1. ✅ **人工授权** - 带有 `need_auth=True` 的工具需要明确批准。 2. ✅ **工作区沙盒** - 文件路径经过规范化并限制在 `workspace_root` 内。 3. ✅ **命令黑名单** - 高风险 shell 模式在执行前被阻止。 4. ✅ **审计日志** - 运行时操作记录到 `safety.audit_log_path`。 ## 🧰 内置工具 工具组： - 📁 文件工具：读/写/编辑/删除/列出/存在/大小/行范围操作 - 🖥️ Shell 工具：shell 执行 + pwd - 🌍 网络工具：web_search + fetch_url - ⏲️ 调度助手：call_cron - 🧠 记忆助手：写入/编辑记忆文件 网络搜索行为： - 提供商目前目标为 Brave Search API - 在配置 `web_search.enabled=true` 和 key 之前默认禁用 ## ⚙️ 配置参考 ### llm 关键字段：`provider`, `model`, `api_key`, `base_url`, `temperature`, `max_tokens`, `timeout_seconds` Gemini 示例： ``` llm: provider: "gemini" model: "gemini-2.5-flash" api_key: "YOUR_GEMINI_API_KEY" temperature: 0.2 max_tokens: 4096 ``` Anthropic 示例： ``` llm: provider: "anthropic" model: "claude-3-7-sonnet" api_key: "YOUR_ANTHROPIC_API_KEY" temperature: 0.2 max_tokens: 4096 ``` ### web_search ``` web_search: enabled: false provider: "brave" brave_api_key: "BSA-..." timeout_seconds: 30 ``` ### 其他高影响部分 - `safety`：管理员、默认认证、黑名单、审计设置 - `context_management`：token 窗口、阈值、保留 - `orchestrator`：步数、运行时间、无进度限制 - `heartbeat`：间隔、静默时段、队列守卫、路由 - `cron`：存储路径、时区、启用/禁用 ### `Memory and Soul`（工作区个性化） 首次运行后，进入您的工作区本地文件夹： ``` /CloseClaw Memory/ ``` 您可以通过编辑这些文件来个性化运行时行为： - `AGENTS.md`：agent 策略/人设和协作偏好 - `SOUL.md`：长期身份、语气和行为风格 - `USER.md`：用户特定偏好和约束 - `TOOLS.md`：工具使用约定和边界 - `SKILLS.md`：技能级指导和触发约定 - `HEARTBEAT.md`：定期主动行为指令 - `memory/YYYY-MM-DD.md`：日级记忆笔记和上下文快照 提示： - 保持指令简洁、明确且无冲突。 - 偏好在 `SOUL.md` 中设置稳定规则，在日常 `memory/` 笔记中设置任务范围指导。 - 如果行为发生漂移，首先检查 `AGENTS.md` + `SOUL.md`，然后修剪冲突笔记。 ## 📦 MCP 设置教程 CloseClaw 支持： - MCP server 健康诊断 - 通过 `MCPBridge` 进行 MCP 工具投影 ### Step 0: 规划服务器布局 ``` / mcp_servers/ weather_server/ docs_server/ ``` ### Step 1: 准备服务器 - 仓库中的 Python 服务器，或 - 通过 `npx` / `npx.cmd` 的 npm 托管服务器 ### Step 2: 在 `config.yaml` 中配置 ``` mcp: servers: - id: "local-stdio" transport: "stdio" command: "python" args: ["-m", "your_mcp_server"] timeout_seconds: 30 - id: "remote-http" transport: "http" base_url: "https://example.com" endpoint: "/mcp" timeout_seconds: 15 max_retries: 2 retry_backoff_seconds: 0.2 ``` ### Step 3: 验证健康 ``` closeclaw mcp --config config.yaml closeclaw mcp --config config.yaml --json ``` ### Step 4: 启动运行时 ``` closeclaw agent --config config.yaml ``` ### Step 5: 快速故障排除 - stdio 不健康：手动验证命令和参数 - http 不健康：验证 base_url + 端点可达性 - 配置被忽略：验证通过 `--config` 传递的是同一个文件 - 工具未被选择：检查引导路径和工具名称冲突 ## 🧠 记忆布局 ``` / CloseClaw Memory/ state.json audit.log memory.sqlite HEARTBEAT.md MEMORY.md AGENTS.md SOUL.md USER.md TOOLS.md SKILLS.md memory/ YYYY-MM-DD.md ``` 为什么采用此布局： - 将操作工件排除在源代码根目录之外 - 使备份和迁移更容易 - 支持从遗留的分散路径进行确定性升级 ## 🧪 测试 聚焦套件： ``` python -m pytest tests/test_config.py -q python -m pytest tests/test_tools.py tests/test_tool_execution_service.py -q python -m pytest tests/test_runner.py tests/test_heartbeat_service.py tests/test_cron_service.py -q ``` 完整套件： ``` python -m pytest tests -q ``` ## 🔁 迁移说明 兼容性行为包括： - 遗留 `state.json` 升级到 `CloseClaw Memory/state.json` - 遗留 `phase5` 配置键映射到 `orchestrator` - 内存工件在可能的情况下迁移到统一布局 ## 🩺 故障排除 1. 网络搜索 key 缺失 - 设置 `web_search.enabled=true` - 设置 `web_search.provider=brave` - 设置有效的 `web_search.brave_api_key` 2. 工具调用意外地需要批准 - 检查 `safety.default_need_auth` - 检查工具级 `need_auth` 行为 3. Heartbeat 未触发 - 检查 `heartbeat.enabled` - 检查 `CloseClaw Memory/HEARTBEAT.md` - 检查静默时段 + 队列守卫设置 4. Cron 不活动 - 检查 `cron.enabled` - 检查 `cron.store_file` 写入权限 - 使用 cron list/run-now 诊断 🪟 Windows 说明（找不到入口命令） 如果 PowerShell 提示无法识别 `closeclaw`： 1. 激活您的虚拟环境。 2. 重新安装可编辑包以便生成脚本。 3. 使用模块模式作为后备。 ``` pip install -e . python -m closeclaw agent --config config.yaml Get-Command closeclaw ``` ## 🤝 贡献指南 欢迎并感谢您的贡献。 ### 1) Fork 并创建功能分支 ``` git checkout -b feat/your-change-name ``` ### 2) 在打开 Pull Request 之前在本地运行测试 聚焦套件： ``` python -m pytest tests/test_config.py -q python -m pytest tests/test_tools.py tests/test_tool_execution_service.py -q python -m pytest tests/test_runner.py tests/test_heartbeat_service.py tests/test_cron_service.py -q ``` 完整套件： ``` python -m pytest tests -q ``` ### 3) 提交 Pull Request 请包括： - 清晰的问题陈述和范围 - 更改了什么以及为什么 - 测试证据（命令 + 结果） - 如果行为/配置发生更改，请提供迁移说明 ### 4) 我们目前最欢迎什么 - 🐞 错误发现、问题报告和直接修复 - 🧪 更强的 channels/providers/integration 路径测试覆盖率 - 🪟🍎 跨平台加固，包括 macOS 兼容性改进 - 📚 文档清晰度、入门改进和示例 ### 5) Issue 质量检查清单 对于错误报告，请附上： - 运行时使用的命令和完整的错误输出 - 最小配置（隐藏机密信息） - 环境详细信息（OS、Python 版本、可选依赖项） 感谢您帮助改进 CloseClaw。

CloseClaw: 小巧的运行时，坚固的护栏，严肃的自动化。

标签：AI安全, Chat Copilot, CloseClaw, Discord, DLL 劫持, DNS 反向解析, LangChain, OpenClaw, Petitpotam, Python, QQ, RAG, Telegram, WhatsApp, 个人助理, 向量检索, 多平台机器人, 大语言模型, 学习助手, 安全, 开源, 新闻收集, 无后门, 沙箱, 编排框架, 网络调试, 自动化, 记忆管理, 请求拦截, 超时处理, 轻量级, 逆向工具, 长期记忆, 飞书