# Kocoro：面向 macOS 的本地 AI Agent 运行时与开发框架

> Kocoro 是一个专为 macOS 设计的本地 AI Agent 运行时，提供交互式 TUI、守护进程模式、丰富的本地工具集（文件操作、GUI 控制、浏览器自动化）以及 MCP 集成能力，支持 Shannon Cloud 连接和云端工作流委托。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-13T06:15:53.000Z
- 最近活动: 2026-05-13T06:25:40.298Z
- 热度: 150.8
- 关键词: AI Agent, macOS, 本地运行时, MCP协议, Shannon, 命令行工具, 自动化, GUI控制
- 页面链接: https://www.zingnex.cn/forum/thread/kocoro-macos-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/kocoro-macos-ai-agent
- Markdown 来源: ingested_event

---

## 项目概述与定位\n\nKocoro 是一个专为 macOS 系统打造的本地 AI Agent 运行时环境，由 Shannon 团队开发维护。它不仅仅是一个命令行工具，而是一个完整的 Agent 开发框架，旨在让开发者和高级用户能够在本地机器上构建、运行和管理 AI Agent。\n\n项目的核心定位是"本地优先"——与完全依赖云服务的 AI 助手不同，Kocoro 强调在本地执行代码、访问文件、控制系统资源，同时保持与云端服务的灵活连接能力。这种架构设计既保护了用户数据隐私，又提供了强大的本地计算能力。\n\n## 核心架构组件\n\nKocoro 采用模块化架构，主要包含以下核心组件：\n\n### 命令行界面（shan CLI）\n\nshan 是 Kocoro 的主命令行工具，支持多种运行模式：\n\n- **交互式 TUI 模式**：启动一个终端用户界面，支持与 Agent 的持续对话\n- **一次性模式**：直接执行单个查询并返回结果\n- **自动确认模式**：通过 `-y` 标志跳过工具调用确认，适合自动化脚本\n\nCLI 设计遵循 Unix 哲学，简洁而强大，可以通过管道和脚本与其他工具集成。\n\n### 守护进程（Daemon）\n\n守护进程是 Kocoro 的核心服务组件，提供以下功能：\n\n- **WebSocket 连接**：与 Shannon Cloud 建立持久连接，接收来自 Slack、LINE、飞书、Telegram 等渠道的消息\n- **本地 HTTP API**：在 localhost:7533 提供 RESTful API，供本地应用和脚本调用\n- **多 Agent 管理**：支持同时运行多个命名 Agent，每个 Agent 拥有独立的配置和会话历史\n- **任务调度**：基于 launchd 的本地定时任务管理\n\n守护进程采用"claim-ack"消息协议，支持多 Agent 并发处理，最多可同时运行 5 个 Agent。\n\n### 本地工具集\n\nKocoro 提供了丰富的本地工具，覆盖文件操作、系统控制、GUI 交互等多个层面：\n\n#### 文件与文档操作\n\n- **file_read/file_write/file_edit**：文件读写和编辑，支持行号定位和批量替换\n- **glob/grep**：文件搜索和内容检索，支持正则表达式\n- **directory_list**：目录内容列举\n- **archive_inspect/archive_extract**：压缩包查看和解压（支持 zip、tar、tar.gz）\n- **pdf_to_text/docx_to_text/xlsx_to_text/pptx_to_text**：文档格式转换和文本提取\n\n#### Shell 与系统控制\n\n- **bash**：执行 shell 命令，120 秒超时，支持安全命令自动批准\n- **system_info**：获取系统信息（OS、架构、CPU、内存、磁盘）\n- **process**：进程管理（列表、端口查询、终止进程）\n- **http**：HTTP 客户端，支持网络白名单\n\n#### macOS GUI 控制\n\n- **accessibility**：通过 macOS 无障碍 API 读取和控制 UI 元素\n- **computer**：鼠标键盘控制（基于 CGEvent，支持 CJK 字符和 emoji）\n- **screenshot**：屏幕截图（全屏、窗口、区域）\n- **applescript**：执行 AppleScript 脚本\n- **clipboard/notify**：剪贴板读写和桌面通知\n- **browser**：浏览器自动化（优先 Playwright MCP，支持 chromedp 回退）\n- **ghostty**：Ghostty 终端控制（标签页、分屏、输入）\n\n这些工具使 Agent 能够像人类用户一样与 macOS 系统交互，从文件管理到应用控制，覆盖了日常操作的各个方面。\n\n## MCP 集成架构\n\nKocoro 实现了 Model Context Protocol（MCP），这是一个开放的协议标准，用于 AI 模型与外部工具的通信。通过 MCP，Kocoro 可以：\n\n- **作为 MCP 客户端**：连接到外部 MCP 服务器（如文件系统、SQLite 数据库、GitHub 等），扩展工具能力\n- **作为 MCP 服务器**：通过 `shan mcp serve` 将本地工具暴露给 MCP 客户端（如 Claude Desktop、Cursor 等）\n\nMCP 配置支持多级合并：全局配置（`~/.shannon/config.yaml`）、项目配置（`.shannon/config.yaml`）和本地覆盖（`.shannon/config.local.yaml`），提供了灵活的配置管理能力。\n\n## 命名 Agent 与个性化配置\n\nKocoro 支持创建多个命名 Agent，每个 Agent 拥有独立的：\n\n- **指令文件（AGENT.md）**：定义 Agent 的角色、能力和行为准则\n- **记忆文件（MEMORY.md）**：跨会话持久化的记忆信息\n- **配置文件（config.yaml）**：工具白名单、MCP 服务器、模型参数等\n- **自定义命令（commands/）**：Agent 专属的斜杠命令\n- **附加技能（_attached.yaml）**：绑定的技能列表\n\n这种设计允许用户为不同场景创建专门的 Agent，例如：\n\n- **ops-bot**：运维监控助手，专注于系统健康检查和故障排查\n- **reviewer**：代码审查助手，专注于代码质量和安全问题\n- **writer**：写作助手，专注于内容创作和文档整理\n\n## 安全与权限模型\n\nKocoro 采用多层安全防护机制：\n\n### 工具调用权限\n\n- **硬阻断**：危险命令（如 `rm -rf /`、`mkfs`、`dd` 等）始终被拒绝\n- **自动批准**：只读工具（如 file_read、grep）在工作目录内自动批准\n- **安全命令**：常用安全命令（如 `ls`、`git status`、`go test`）自动批准\n- **交互确认**：破坏性操作需要用户确认\n- **命令拆分**：复合命令（`&&`、`||`、`|`、`;`）被拆分为子命令分别检查\n\n### 文件系统保护\n\n- 符号链接解析保护\n- 敏感文件模式匹配（`.env`、`.pem`、`id_rsa` 等）\n- 允许目录白名单\n\n### 审计日志\n\n所有工具调用记录到 `~/.shannon/logs/audit.log`，采用 JSON Lines 格式，自动脱敏敏感信息（AWS 密钥、JWT、Bearer Token、PEM 标记等）。\n\n## 会话管理与持久化\n\nKocoro 的会话系统支持：\n\n- **会话持久化**：对话历史保存为 JSON 文件，支持断点续聊\n- **会话搜索**：基于 SQLite FTS5 的全文检索\n- **会话恢复**：通过 `/sessions` 命令浏览和恢复历史会话\n- **上下文压缩**：当上下文窗口压力过高时，自动压缩历史消息\n\n每个命名 Agent 拥有独立的会话目录，确保不同 Agent 的对话历史相互隔离。\n\n## 记忆系统\n\nKocoro 实现了多层次的记忆机制：\n\n### 结构化记忆（MEMORY.md）\n\nAgent 可以将重要信息写入记忆文件，实现跨会话的知识积累。记忆文件支持分类组织，便于检索和管理。\n\n### 情景记忆（Episodic Memory）\n\n通过可选的云端记忆服务，Kocoro 可以从历史会话中提取相关记忆，在新会话中自动注入上下文。这是一项 opt-in 功能，默认关闭，用户可以在设置中启用。\n\n### 技能系统\n\n技能（Skill）是可复用的 Agent 能力模块，遵循 Anthropic SKILL.md 规范。技能可以：\n\n- 全局安装到 `~/.shannon/skills/`\n- 绑定到特定 Agent\n- 通过 `use_skill` 工具动态激活\n\nKocoro 内置了两个自动安装的技能：`kocoro`（平台配置助手）和 `kocoro-generative-ui`（可视化助手）。\n\n## 云端集成与混合架构\n\n虽然 Kocoro 强调本地执行，但它也提供了灵活的云端集成能力：\n\n### Shannon Cloud 连接\n\n- **消息渠道集成**：通过 WebSocket 连接 Shannon Cloud，接收来自 Slack、LINE、飞书、Telegram 的消息\n- **远程研究**：通过 `/research` 命令委托云端执行深度研究任务\n- **多 Agent 编排**：通过 `/swarm` 命令启动云端多 Agent 协作\n- **图片生成**：通过云端 API 生成图片（gpt-image-2）\n\n### 模型提供商选择\n\nKocoro 支持多种模型提供商：\n\n- **Shannon Cloud**：云端托管的模型服务\n- **自托管 Gateway**：本地部署的 Shannon Gateway\n- **Ollama**：本地运行的开源模型（如 Llama 3.1、Qwen3 等）\n\n这种灵活性允许用户根据隐私需求和性能要求选择合适的模型后端。\n\n## 开发者生态与扩展性\n\nKocoro 为开发者提供了丰富的扩展接口：\n\n### 生命周期钩子\n\n支持在工具调用前后、会话开始和结束时执行自定义脚本：\n\n```yaml\nhooks:\n  PreToolUse:\n    - matcher: \"bash\"\n      command: \".shannon/hooks/check-bash.sh\"\n  PostToolUse:\n    - matcher: \"file_edit|file_write\"\n      command: \".shannon/hooks/post-edit.sh\"\n```\n\n### 自定义命令\n\n通过在 `commands/` 目录下创建 Markdown 文件，可以添加自定义的斜杠命令。\n\n### HTTP API\n\n守护进程提供的本地 HTTP API 支持：\n\n- 发送消息并获取回复\n- 会话管理和搜索\n- Agent 列表和配置重载\n- SSE 事件流（用于实时更新）\n\n这为构建自定义客户端和自动化脚本提供了便利。\n\n## 安装与使用\n\nKocoro 提供多种安装方式：\n\n- **npm**：`npm install -g @kocoro/kocoro`\n- **安装脚本**：`curl -fsSL ... | sh`\n- **Go 源码**：`go install .`\n\n安装后通过 `shan --setup` 配置端点和 API 密钥，即可开始使用。\n\n## 应用场景与价值\n\nKocoro 适用于多种场景：\n\n- **个人自动化**：文件整理、系统监控、定时任务\n- **开发辅助**：代码审查、项目分析、文档生成\n- **知识管理**：笔记整理、资料归档、信息检索\n- **智能客服**：通过消息渠道接入，提供自动化回复\n- **研究助手**：网络搜索、资料汇总、报告生成\n\n对于注重数据隐私、希望在本地运行 AI Agent 的 macOS 用户而言，Kocoro 提供了一个功能完备、安全可控的解决方案。\n\n## 项目展望\n\n作为一个活跃开发的开源项目，Kocoro 未来可能在以下方向持续演进：\n\n- 扩展更多本地工具（如更多浏览器自动化能力）\n- 优化与开源模型的兼容性\n- 增强多模态能力（图像理解、语音交互）\n- 提供更丰富的技能市场\n- 改进跨平台支持（目前仅限 macOS）\n\n对于希望深入探索 AI Agent 技术的开发者来说，Kocoro 不仅是一个实用工具，更是一个学习和实验的优秀平台。