Octopal 是一个本地自主 AI 智能体平台，其核心智能体名为 Octo，可以驻留在你的电脑或服务器上。你可以通过 Telegram、WhatsApp 或专用桌面应用与 Octo 沟通。Octopal 的设计目标是执行任何任务、运行定时活动、托管自动化流水线、进行网络研究，并与 API、MCP、A2A、技能等协同工作。其核心理念是打造一个你可以信任的 AI 智能体。
【架构与安全模型】 Octo 作为主推理智能体，长期运行在系统内部，负责对话、记忆、策略、路由和高层决策。对外部世界的通信则交给专门的工作者（子智能体）。工作者是短生命周期、一次性的智能体，仅为完成特定任务目标而生成，运行在隔离的 Docker 环境中，不持有系统或私有上下文，任务完成后实例即被删除。这种协调者/工作者分离的架构可防止上下文污染、提示注入和恶意环境操作。即使工作者安装并运行了恶意代码，也只会停留在其容器内，不会危害主系统。Docker 是默认的工作者启动器，工作者拥有独立的临时工作区，对 Octo 主工作区的访问需通过 allowed_paths 显式授权。Docker 模式在 CLI 或守护进程不可用、或工作者镜像无法构建时会失败关闭（fail closed）。若要在无 Docker 的情况下运行受信任的本地开发任务，需显式选择 same_env，Octopal 不会自动降级隔离。仪表板和网关 API 可通过令牌保护，Tailscale 集成可私密暴露仪表板而无需开放公共端口。
【模型提供商】 Octopal 允许为 Octo 选择一个模型提供商，并在需要时为工作者选择不同的提供商。支持的提供商目录包括：前沿 API（OpenAI、Anthropic、Google Gemini、Mistral、OpenRouter、Together AI、Groq）、订阅和基于计划的路线（Codex、Z.ai、Minimax）、本地和自定义路线（Ollama、自定义 OpenAI 兼容）。
【智能体间协作（A2A）】 Octo 可以通过 A2A 与其他 Octopal 实例或其他智能体通信，将独立智能体组成工作团队。多个 Octopal 实例可作为私有智能体网络协作；其他智能体和编码运行时（如 Codex、Claude Code、Gemini 等）可作为受信任对等方连接；一个智能体可以请求 Octopal 使用其记忆、工作者、工具或本地上下文。当前 A2A 集成默认私密，对等方需显式配置，使用 bearer 令牌认证，通过 agent card 发现 Octopal，并在 A2A HTTP+JSON 接口上交换文本及显式允许的结构化 JSON、文件 URL 和原始文件部分。
【记忆系统】 Octopal 将记忆分层存储：MEMORY.md 保存工作记忆和持久笔记；memory/canon/ 存储经审核的长期知识；USER.md 存储用户偏好和交互风格；SOUL.md 存储助手身份、语气和行为原则；HEARTBEAT.md 存储周期性职责、监控循环和后台义务。语义检索使用强制性的本地、仅 CPU 的 ONNX 运行时，不依赖 PyTorch。在 Linux、Windows 和 macOS 上，首次运行时启动会下载并验证固定的 intfloat/multilingual-e5-small 包。
【渠道与仪表板】 Octopal 可通过 Telegram、WhatsApp 或专用桌面应用进行通信，渠道支持文本、图片/文件附件、支持的反应，以及一个短暂的宽限窗口，以便后续消息在 Octo 开始执行前合并到同一轮次。仪表板提供实时操作界面，包括 Octo 状态和网关健康、活跃工作者和工作历史、通信日志、仪表板操作、基于令牌的访问保护，以及可选的 Tailscale 感知私密访问。
【技能与连接器】 Octopal 支持工作区本地技能包，位于 workspace/skills/<skill-id>/。技能可包含 SKILL.md 指令、就绪检查、隔离的 Python 或 JS/TS 运行时环境，并可通过桌面应用轻松安装。连接器是外部服务的集成层，当前连接器表面包括 Google 服务和面向 GitHub 的工作流。
【多语言与主题】 Octopal 桌面 UI 支持英语、法语、西班牙语和中文（普通话），并支持浅色和深色主题。
【核心命令与故障排除】 项目提供 WhatsApp 设置、工作者模板、记忆维护、手动构建仪表板等命令。GitHub 发布使用基于日期的版本，位于 src/octopal/_version.py，标签形如 vYYYY.MM.DD 或 vYYYY.MM.DD.N。故障排除涵盖 Telegram 机器人启动但不回复、WhatsApp 消息未到达、模型提供商配置、网络搜索或抓取问题等。浏览器工具默认使用 auto，启动时在空闲回环端口上启动固定的 PinchTab 容器，并在 data/managed-web 下创建私有服务器令牌，自动派生独立的主机和 Docker 工作者 URL。若 Docker、PinchTab 或其健康检查不可用，Octopal 会继续在 Playwright 上运行。
【许可证】 MIT，详见 LICENSE。
