adolfousier/opencrabs

# 🦀 OpenCrabs **自主的、自我改进的 AI 代理。单文件 Rust 二进制程序。覆盖所有渠道。** ``` ___ ___ _ / _ \ _ __ ___ _ _ / __|_ _ __ _| |__ ___ | (_) | '_ \/ -_) ' \ | (__| '_/ _` | '_ \(_-< \___/| .__/\___|_||_| \___|_| \__,_|_.__//__/ |_| 🦀 The autonomous, self-improving AI agent. Single Rust binary. Every channel. ``` **作者：** [Adolfo Usier](https://github.com/adolfousier) ## 为什么选择 OpenCrabs？ OpenCrabs 以**单文件二进制程序**运行在您的终端上——无需服务器、无需网关、无需基础设施。它直接从您的机器向 LLM 提供商发起直接的 HTTPS 调用。除了您自己的计算机，没有任何其他数据离开。 ### OpenCrabs 与 Node.js 代理框架对比 | | **OpenCrabs** (Rust) | **Node.js 框架**（例如 Open Claw） | |---|---|---| | **二进制大小** | **17–22 MB** 单文件，无依赖 | **1 GB+** `node_modules`，包含数百个传递依赖 | | **运行时** | 无——原生运行 | 需要 Node.js 运行时 + npm install | | **攻击面** | 零网络监听。仅允许出站 HTTPS | 服务器基础设施：开放端口、认证层、中间件 | | **API 密钥安全** | 密钥仅在您的机器上。`zeroize` 在 drop 时从 RAM 中清除，调试输出中显示 `[REDACTED]` | 密钥在环境变量或配置中。GC 无法保证内存清除。堆转储可能泄露密钥 | | **数据驻留** | 100% 本地——SQLite 数据库、embeddings、brain 文件，全部在 `~/.opencrabs/` 中 | 服务器端存储、潜在的多租户数据、网络传输 | | **供应链** | 单一编译后的二进制文件。Rust 的类型系统在编译时防止缓冲区溢出、use-after-free、数据竞争 | npm 生态：typosquatting、依赖混淆、原型污染 | | **内存安全** | 编译时保证——无 GC、无空指针、无数据竞争 | GC 管理、原型污染、类型强制转换 bug | | **并发** | tokio async + Rust 所有权 = 保证零数据竞争 | 单线程事件循环，工作线程共享内存不安全 | | **原生 TTS/STT** | 内置本地语音转文字（whisper.cpp）和文字转语音——约 130 MB 总栈，完全离线 | 无原生语音。需要外部 API（Google、AWS、Azure）或重型 Python 依赖（PyTorch，约 5 GB+） | | **遥测** | 零。无分析、无追踪、无远程日志 | 服务器基础设施通常包含监控、日志管道、APM | ### 保留在本地（永不离开您的机器） - 所有聊天会话和消息（SQLite） - 工具执行（bash、文件读写、git） - 记忆和 embeddings（本地向量搜索） - 本地 STT 模式下的语音转录（whisper.cpp，设备端） - Brain 文件、配置、API 密钥 ### 外出内容（仅在使用时） - 您发送给 LLM 提供商 API 的消息（Anthropic、OpenAI、GitHub Copilot 等） - 网络搜索查询（可选工具） - 通过 `gh` CLI 进行的 GitHub API 调用（可选工具） - 浏览器自动化（可选，`browser` 功能——通过 CDP 自动检测基于 Chromium 的浏览器，非 Firefox） - 动态工具 HTTP 请求（仅在 `tools.toml` 中定义 HTTP 工具时） ## 目录 - [截图](#-screenshots) - [为什么选择 OpenCrabs？](#why-opencrabs) - [核心功能](#-core-features) - [CLI 命令](#cli) - [支持的 AI 提供商](#-supported-ai-providers) - [代理到代理（A2A）协议](#-agent-to-agent-a2a-protocol) - [快速开始](#-quick-start) - [入门向导](#-onboarding-wizard) - [API 密钥（keys.toml）](#-api-keys-keystoml) - [配置（config.toml）](#-configuration-configtoml) - [命令（commands.toml）](#-commands-commandstoml) - [动态工具（tools.toml）](#-dynamic-tools-toolstoml) - [使用本地 LLM](#-using-local-llms) - [配置](#-configuration) - [工具系统](#-tool-system) - [键盘快捷键](#-keyboard-shortcuts) - [调试和日志](#-debug-and-logging) - [定时任务与心跳](#-cron-jobs--heartbeats) - [架构](#-architecture) - [项目结构](#-project-structure) - [开发](#-development) - [平台说明](#-platform-notes) - [故障排除](#-troubleshooting) - [配套工具](#-companion-tools) - [免责声明](#-disclaimers) - [贡献](#-contributing) - [许可证](#-license) - [致谢](#-acknowledgments) ## 📸 截图 https://github.com/user-attachments/assets/7f45c5f8-acdf-48d5-b6a4-0e4811a9ee23 ## 🎯 核心功能 ### AI 与提供商 | 功能 | 描述 | |---------|-------------| | **多提供商** | Anthropic Claude、OpenAI、GitHub Copilot（使用您的 Copilot 订阅）、OpenRouter（400+ 模型）、MiniMax、Google Gemini、z.ai GLM（通用 API + 编码 API）、Claude CLI、OpenCode CLI、Qwen Code CLI（每天 1000 次免费请求），以及任何 OpenAI 兼容 API（Ollama、LM Studio、LocalAI）。模型列表从提供商 API 实时获取——新模型立即可用。每个会话记住其提供商和模型，切换时自动恢复 | | **备用提供商** | 配置备用提供商链——如果主提供商失败，每个备用提供商按顺序自动尝试。任何已配置密钥的提供商都可以作为备用。配置：`[providers.fallback] providers = ["openrouter", "anthropic"]` | | **按提供商设置视觉模型** | 为每个提供商设置 `vision_model`——LLM 将 `analyze_image` 作为工具调用，使用同一提供商 API 上的视觉模型来描述图像。聊天模型保持不变，通过工具调用获得视觉能力。配置后 Gemini 视觉优先。首次运行时为已知提供商（例如 MiniMax）自动配置 | | **实时流式传输** | 逐字符响应流式传输，带有动画旋转器显示模型名称和实时文本 | | **本地 LLM 支持** | 使用 LM Studio、Ollama 或任何 OpenAI 兼容端点运行——100% 私有、零成本 | | **成本追踪** | 标题中显示每条消息的令牌计数和成本；`/usage` 显示按模型分组的全时间成本分解，包含历史会话的实际成本和估算成本 | | **上下文感知** | 实时上下文使用指示器，显示实际令牌计数（例如 `ctx: 45K/200K (23%)`）；70% 时自动压缩，包含工具开销预算；基于 tiktoken 的准确计数，与 API 实际数据校准 | | **三级记忆** | (1) **Brain MEMORY.md**——用户管理的持久记忆，每轮加载，(2) **每日日志**——位于 `~/.opencrabs/memory/YYYY-MM-DD.md` 的自动压缩摘要，(3) **混合记忆搜索**——FTS5 关键词搜索 + 本地向量 embeddings（embeddinggemma-300M，768 维）通过 Reciprocal Rank Fusion 组合。完全本地运行——无需 API 密钥、无成本、离线工作 | | **动态 Brain 系统** | 系统 brain 由工作区 MD 文件（SOUL、IDENTITY、USER、AGENTS、TOOLS、MEMORY）组装——所有文件可在回合之间实时编辑 | | **多代理编排** | 生成类型化子代理（General、Explore、Plan、Code、Research）并行执行任务。五个工具：`spawn_agent`、`wait_agent`、`send_input`、`close_agent`、`resume_agent`。每种类型获得特定角色的系统提示和过滤的工具注册表。可配置子代理提供商/模型。子代理在隔离会话中运行，带自动批准——无递归生成 | ### 多模态输入 | 功能 | 描述 | |---------|-------------| | **图片附件** | 将图片路径或 URL 粘贴到输入中——自动检测并作为视觉内容块附加，供多模态模型使用 | | **PDF 支持** | 按路径附加 PDF 文件——原生 Anthropic PDF 支持；对于其他提供商，通过 `pdf-extract` 本地提取文本 | | **文档解析** | 内置 `parse_document` 工具从 PDF、DOCX、、TXT、MD、JSON、XML 中提取文本 | | **语音（STT）** | 语音笔记通过 **API**（Groq Whisper `whisper-large-v3-turbo`）或 **本地**（whisper.cpp 通过 `whisper-rs`，设备端运行）转录。在 `/onboard:voice` 中选择模式。本地模式：选择模型大小（Tiny 75 MB / Base 142 MB / Small 466 MB / Medium 1.5 GB），从 HuggingFace 下载，零 API 成本。默认包含 | | **语音（TTS）** | 代理通过 **API**（OpenAI TTS `gpt-4o-mini-tts`）或 **本地**（Piper TTS，通过 Python venv 设备端运行）用音频回复语音笔记。在 `/onboard:voice` 中选择模式。本地模式：选择语音（Ryan / Amy / Lessac / Kristin / Joe / Cori），从 HuggingFace 自动下载，零 API 成本。如果禁用则回退到文本 | | **附件指示器** | 附加的图片在输入标题栏中显示为 `[IMG1:filename.png]` | | **图片生成** | 代理通过 Google Gemini（`gemini-3.1-flash-image-preview` "Nano Banana"）使用 `generate_image` 工具生成图片——通过 `/onboard:image` 启用。在所有渠道中作为原生图片/附件返回 | ### 消息集成 | 功能 | 描述 | |---------|-------------| | **Telegram 机器人** | 功能完整的 Telegram 机器人——所有者 DM 共享 TUI 会话，群组获得按群组隔离的会话（按聊天 ID 键控）。支持照片/语音、允许的用户 ID、允许的聊天/群组 ID、`respond_to` 过滤器（`all`/`dm_only`/`mention`）。被动群组消息捕获——即使机器人未被提及，所有消息也会存储以提供上下文 | | **WhatsApp** | 运行时通过 QR 码配对或从入门向导连接。文本 + 图片，与 TUI 共享会话，手机白名单（`allowed_phones`），会话在重启后保持 | | **Discord** | 功能完整的 Discord 机器人——文本 + 图片 + 语音。所有者 DM 共享 TUI 会话，公会频道获得按频道隔离的会话。允许的用户 ID、允许的频道 ID、`respond_to` 过滤器。通过 `discord_send`（17 个操作）完全主动控制：`send`、`reply`、`react`、`unreact`、`edit`、`delete`、`pin`、`unpin`、`create_thread`、`send_embed`、`get_messages`、`list_channels`、`add_role`、`remove_role`、`kick`、`ban`、`send_file`。生成的图片作为原生 Discord 文件附件发送 | | **Slack** | 通过 Socket Mode 的功能完整的 Slack 机器人——所有者 DM 共享 TUI 会话，频道获得按频道隔离的会话。允许的用户 ID、允许的频道 ID、`respond_to` 过滤器。通过 `slack_send`（17 个操作）完全主动控制：`send`、`reply`、`react`、`unreact`、`edit`、`delete`、`pin`、`unpin`、`get_messages`、`get_channel`、`list_channels`、`get_user`、`list_members`、`kick_user`、`set_topic`、`send_blocks`、`send_file`。生成的图片作为原生 Slack 文件上传发送。机器人令牌 + 应用令牌来自 `api.slack.com/apps`（需要 Socket Mode）。**所需机器人令牌权限：** `chat:write`、`channels:history`、`groups:history`、`im:history`、`mpim:history`、`users:read`、`files:read`、`files:write`、`reactions:write`、`app_mentions:read` | | **Trello** | 默认仅工具——AI 仅在通过 `trello_send` 明确调用时对 Trello 进行操作。通过配置中的 `poll_interval_secs` 选择加入轮询；启用后，仅允许用户的 `@bot_username` 提及触发响应。通过 `trello_send`（22 个操作）完全管理卡片：`add_comment`、`create_card`、`move_card`、`find_cards`、`list_boards`、`get_card`、`get_card_comments`、`update_card`、`archive_card`、`add_member_to_card`、`remove_member_from_card`、`add_label_to_card`、`remove_label_from_card`、`add_checklist`、`add_checklist_item`、`complete_checklist_item`、`list_lists`、`get_board_members`、`search`、`get_notifications`、`mark_notifications_read`、`add_attachment`。API 密钥 + 令牌来自 `trello.com/power-ups/admin`，可配置看板 ID 和成员 ID 白名单 | #### 文件和媒体输入支持 当用户在任何渠道发送文件、图片或文档时，代理自动接收内容——无需手动转发。例如：用户上传仪表板截图到 Trello 卡片并评论 *"我看到这个错误"* ——代理获取附件，通过视觉管道处理，然后提供完整上下文进行回复。 | 渠道 | 图片（入） | 文本文件（入） | 文档（入） | 音频（入） | 图片生成（出） | |---------|-------------|-----------------|----------------|------------|-----------------| | **Telegram** | ✅ 视觉管道 | ✅ 内联提取 | ✅ / PDF 注意 | ✅ STT | ✅ 原生照片 | | **WhatsApp** | ✅ 视觉管道 | ✅ 内联提取 | ✅ / PDF 注意 | ✅ STT | ✅ 原生图片 | | **Discord** | ✅ 视觉管道 | ✅ 内联提取 | ✅ / PDF 注意 | ✅ STT | ✅ 文件附件 | | **Slack** | ✅ 视觉管道 | ✅ 内联提取 | ✅ / PDF 注意 | ✅ STT | ✅ 文件上传 | | **Trello** | ✅ 卡片附件 → 视觉 | ✅ 内联提取 | — | — | ✅ 卡片附件 + 嵌入 | | **TUI** | ✅ 粘贴路径 → 视觉 | ✅ 粘贴路径 → 内联 | — | ✅ STT | ✅ `[IMG: name]` 显示 | 图片如果支持多模态输入则传递给活动模型的视觉管道，否则路由到 `analyze_image` 工具（Google Gemini 视觉）。文本文件（`.txt`、`.md`、`.json`、`.csv`、源代码等）作为 UTF-8 提取并内联包含最多 8000 字符——在 TUI 中只需粘贴或输入文件路径。 ### 终端 UI | 功能 | 描述 | |---------|-------------| | **光标导航** | 完整光标移动：左/右箭头、Ctrl+左/右跳转单词、Home/End、Delete、Backspace | | **输入历史** | 持久命令历史（`~/.opencrabs/history.txt`），启动时加载，最多 500 条 | | **内联工具批准** | Claude Code 风格 `❯ Yes / Always / No` 选择器，带箭头键导航 | | **内联计划批准** | 交互式计划审查选择器（批准 / 拒绝 / 请求更改 / 查看计划） | | **会话管理** | 创建、重命名、删除会话，持久化 SQLite 存储；每个会话记住其提供商和模型——切换会话自动恢复提供商（无需手动 `/models`）；每个会话的令牌计数和上下文百分比 | | **分屏** | 水平（会话中的 `|`）和垂直（会话中的 `_`）分屏——tmux 风格。每个分屏运行自己的会话，具有独立的提供商、模型和上下文。并排运行 10 个会话，全部并行处理。`Tab` 循环焦点，`Ctrl+X` 关闭分屏 | | **并行会话** | 多个会话可以同时向不同提供商发送进行中的请求。在一个会话中发送消息，切换到另一个，再发送一个——两者并行处理。后台会话自动批准工具调用；切换回来时会看到结果 | | **流式传输时滚动** | 在流式传输时向上滚动，不会被拖回底部；滚动回底部或发送消息时自动滚动重新启用 | | **压缩摘要** | 自动压缩在聊天中显示完整摘要作为系统消息——准确看到代理记住的内容 | | **语法高亮** | 100+ 语言，带行号，通过 syntect | | **Markdown 渲染** | 富文本格式，包含代码块、标题、列表和内联样式 | | **工具上下文持久化** | 工具调用组保存到数据库，会话重新加载时重建——不会丢失工具历史 | | **多行输入** | Alt+Enter / Shift+Enter 换行；Enter 发送 | | **中止处理** | 3 秒内按两次 Escape 取消任何进行中的请求 | | **Bang 操作符（`!cmd`）** | 直接从输入运行任何 shell 命令——无需 LLM 往返。输出目录上下文中显示为系统消息 | | **自动更新** | 启动时和后台每 24 小时检查 GitHub 是否有新版本。发现新版本时静默安装并热重启。通过 `[agent] auto_update = false` 在 `config.toml` 中禁用以改为提示 | ### 代理能力 | 功能 | 描述 | |---------|-------------| | **完整终端访问** | 30+ 内置工具（文件 I/O、glob、grep、网络搜索、代码执行、图片生成/分析、记忆搜索、定时任务），加上**系统上的任何 CLI 工具**通过 `bash`——GitHub CLI、Docker、SSH、Python、Node、ffmpeg、curl 以及其他一切都可以直接使用 | | **按会话隔离** | 每个会话是独立的代理，有自己的提供商、模型、上下文和工具状态。会话可以并行运行不同提供商的任务——在一个会话中向 Claude 提问，同时让 Kimi 在另一个会话中编写代码 | | **自维持** | 代理可以修改自己的源代码、构建、测试，并通过 Unix `exec()` 热重启 | | **自我改进** | 从经验中学习——将可重用工作流保存为自定义命令，将经验教训写入记忆，更新自己的 brain 文件。全部本地化，没有数据离开您的机器 | | **动态工具** | 通过 `~/.opencrabs/tools.toml` 在运行时定义自定义工具——代理可以像内置工具一样自主调用它们。HTTP 和 shell 执行器、模板参数（`{{param}}`），无需重启即可启用/禁用。`tool_manage` 元工具允许代理动态创建、删除和重新加载工具 | | **浏览器自动化** | 通过 CDP（Chrome DevTools 协议）原生控制浏览器。自动检测您的默认基于 Chromium 的浏览器（Chrome、Brave、Edge、Arc、Vivaldi、Opera、Chromium）并使用其配置文件——您的登录、cookie 和扩展继承。7 个浏览器工具：导航、点击、输入、截图、eval JS、提取内容、等待元素。有头或无头模式，自动检测显示。**注意：** 不支持 Firefox（无 CDP）——如果 Firefox 是您的默认浏览器，OpenCrabs 回退到第一个可用的 Chromium 浏览器。功能在 `browser` 下（默认包含） | | **自然语言命令** | 告诉 OpenCrabs 创建斜杠命令——它通过 `config_manager` 工具自动写入 `commands.toml` | | **实时设置** | 代理可以在运行时读写 `config.toml`；设置 TUI 屏幕（按 `S`）显示当前配置；批准策略在重启后保持。默认：自动批准（使用 `/approve` 更改） | | **网络搜索** | 默认 DuckDuckGo（内置，无需密钥）+ EXA AI（神经，通过 MCP 免费）；Brave Search 可选（密钥在 `keys.toml` 中） | | **调试日志** | `--debug` 标志启用文件日志；`DEBUG_LOGS_LOCATION` 环境变量用于自定义日志目录 | | **代理到代理（A2A）** | 实现 A2A 协议 RC v1.0 的 HTTP 网关——通过 JSON-RPC 2.0 的点对点代理通信。支持 `message/send`、`message/stream`（SSE）、`tasks/get`、`tasks/cancel`。内置 `a2a_send` 工具允许代理主动调用远程 A2A 代理。可选 Bearer 令牌认证。包含多代理辩论（蜂群），具有置信度加权共识。任务在重启后持久化 | | **配置文件** | 从同一安装运行多个隔离实例。每个配置文件有自己的配置、密钥、记忆、会话和数据库。使用 `opencrabs profile create ` 创建，使用 `-p ` 切换。使用 `profile migrate` 在配置文件之间迁移配置。导出/导入共享。令牌锁隔离防止两个配置文件使用相同的机器人凭证 | ### CLI | 命令 | 描述 | |---------|-------------| | `opencrabs` | 启动交互式 TUI（默认） | | `opencrabs chat` | 启动 TUI，可选 `--session ` 恢复，`--onboard` 强制向导 | | `opencrabs run ` | 非交互式执行单个提示。`--auto-approve` / `--yolo` 无人值守。`--format text\|json\|markdown` | | `opencrabs agent` | 交互式 CLI 代理——终端中的多轮对话，无需 TUI。`-m ` 单消息模式 | | `opencrabs status` | 系统概览：版本、提供商、渠道、数据库、brain、动态工具 | | `opencrabs doctor` | 完整诊断：配置、提供商连接、数据库、brain、渠道、PATH 中的 CLI 工具 | | `opencrabs init` | 初始化配置（`--force` 覆盖） | | `opencrabs config` | 显示当前配置（`--show-secrets` 显示密钥） | | `opencrabs onboard` | 运行入门设置向导 | | `opencrabs channel list` | 列出所有配置的渠道及启用/禁用状态 | | `opencrabs channel doctor` | 对所有启用的渠道运行健康检查 | | `opencrabs memory list` | 列出 brain 文件和记忆条目 | | `opencrabs memory get ` | 显示特定记忆或 brain 文件的内容 | | `opencrabs memory stats` | 记忆统计：文件数、总大小、条目数 | | `opencrabs session list` | 列出所有会话，包含提供商、模型、令牌计数（`--all` 包含已归档） | | `opencrabs session get ` | 显示会话详情和最近消息 | | `opencrabs db init` | 初始化数据库 | | `opencrabs db stats` | 显示数据库统计 | | `opencrabs db clear` | 清除所有会话和消息（`--force` 跳过确认） | | `opencrabs cron add\|list\|remove\|enable\|disable\|test` | 管理计划的定时任务 | | `opencrabs logs status\|view\|clean\|open` | 日志管理 | | `opencrabs service install\|start\|stop\|restart\|status\|uninstall` | OS 服务管理（macOS 上为 launchd，Linux 上为 systemd） | | `opencrabs daemon` | 以无头守护进程模式运行——仅渠道，无 TUI | | `opencrabs completions ` | 生成 shell 补全（bash、zsh、fish、powershell） | | `opencrabs version` | 打印版本并退出 | 全局标志：`--debug`（启用文件日志）、`--config `（自定义配置文件）、`--profile ` / `-p `（以命名配置文件运行）。 ### 配置文件——多实例螃蟹代理 从同一安装运行多个隔离的 OpenCrabs 实例。每个配置文件有自己的配置、brain 文件、记忆、会话、数据库和网关服务。 | 命令 | 描述 | |---------|-------------| | `opencrabs profile create ` | 创建带有新配置和 brain 文件的新配置文件 | | `opencrabs profile list` | 列出所有配置文件及上次使用时间戳 | | `opencrabs profile delete ` | 删除配置文件及其所有数据 | | `opencrabs profile export -o profile.tar.gz` | 将配置文件导出为可移植存档 | | `opencrabs profile import profile.tar.gz` | 从存档导入配置文件 | | `opencrabs profile migrate --from --to ` | 在配置文件之间复制配置和 brain 文件（无数据库或会话） | | `opencrabs -p ` | 以指定配置文件启动 OpenCrabs | **默认配置文件：** `~/.opencrabs/`——与以前完全一样。无需迁移。从不接触配置文件的用户看不到任何差异。 **命名配置文件**位于 `~/.opencrabs/profiles//`，完全隔离： ``` ~/.opencrabs/ ├── config.toml # default profile ├── opencrabs.db ├── profiles.toml # profile registry ├── locks/ # token-lock files └── profiles/ ├── hermes/ # named profile │ ├── config.toml │ ├── keys.toml │ ├── opencrabs.db │ ├── SOUL.md │ └── memory/ └── scout/ └── ... ``` **令牌锁隔离：** 两个配置文件不能使用相同的机器人凭证（Telegram 令牌、Discord 令牌等）。启动时，每个配置文件获取其渠道令牌的锁。如果另一个配置文件已持有该锁，渠道拒绝启动——防止两个实例争用同一个机器人。 **配置文件迁移：** 使用 `opencrabs profile migrate --from default --to hermes` 将所有 `.md` brain 文件、`.toml` 配置文件和 `memory/` 条目复制到新配置文件。会话和数据库不复制——配置文件全新开始。添加 `--force` 覆盖目标配置文件中的现有文件。迁移后，自定义新配置文件的 `SOUL.md`、`IDENTITY.md` 和 `config.toml` 以赋予其不同的个性和提供商设置。 ### 守护进程和服务 将配置文件作为后台服务运行： ``` # Install as system service (macOS launchd / Linux systemd) opencrabs -p hermes service install opencrabs -p hermes service start # Each profile gets its own service # macOS: com.opencrabs.daemon.hermes # Linux: opencrabs-hermes.service # Manage independently opencrabs -p hermes service status opencrabs -p hermes service stop opencrabs -p hermes service uninstall ``` 多个配置文件可以作为同时运行的守护进程服务运行，完全隔离。 **环境变量：** 设置 `OPENCRABS_PROFILE=hermes` 以选择配置文件，无需 `-p` 标志。适用于 systemd 服务、定时任务和守护进程模式。 ## 🌐 支持的 AI 提供商 | 提供商 | 认证 | 模型 | 流式传输 | 工具 | 备注 | |----------|------|--------|-----------|-------|-------| | [Anthropic Claude](#anthropic-claude) | API 密钥 | Claude Opus 4.6、Sonnet 4.5、Haiku 4.5+ | ✅ | ✅ | 成本追踪、自动重试 | | [OpenAI](#openai) | API 密钥 | GPT-5 Turbo、GPT-5 | ✅ | ✅ | | | [GitHub Copilot](#github-copilot) | OAuth | GPT-4o、Claude Sonnet 4+ | ✅ | ✅ | 使用您的 Copilot 订阅——无 API 费用 | | [OpenRouter](#openrouter--400-models-one-key) | API 密钥 | 400+ 模型 | ✅ | ✅ | 免费模型可用（DeepSeek-R1、Llama 3.3 等） | | [Google Gemini](#google-gemini) | API 密钥 | Gemini 2.5 Flash、2.0、1.5 Pro | ✅ | ✅ | 1M+ 上下文、视觉、图片生成 | | [MiniMax](#minimax) | API 密钥 | M2.7、M2.5、M2.1、Text-01 | ✅ | ✅ | 有竞争力的定价、自动配置视觉 | | [z.ai GLM](#zai-glm) | API 密钥 | GLM-4.5 到 GLM-5 Turbo | ✅ | ✅ | 通用 API + 编码 API 端点 | | [Claude CLI](#claude-code-cli) | CLI 认证 | 通过 `claude` 二进制 | ✅ | ✅ | 使用您的 Claude Code 订阅 | | [OpenCode CLI](#opencode-cli) | 无 | 免费模型（Mimo 等） | ✅ | ✅ | 免费——无需 API 密钥或订阅 | | [Qwen Code CLI](#qwen-code-cli) | OAuth / API 密钥 | Qwen3-Coder-Plus、Qwen3.5-Plus、Qwen3.6-Plus | ✅ | ✅ | 每天 1000 次免费请求，通过 Qwen OAuth——无需 API 密钥 | | [自定义](#custom-openai-compatible) | 可选 | 任意 | ✅ | ✅ | Ollama、LM Studio、Groq、NVIDIA、任何 OpenAI 兼容 API | ### Anthropic Claude **模型：** `claude-opus-4-6`、`claude-sonnet-4-5-20250929`、`claude-haiku-4-5-20251001`，以及遗留 Claude 3.x 模型 在 `keys.toml` 中**设置**： ``` [providers.anthropic] api_key = "sk-ant-api03-YOUR_KEY" ``` **功能：** 流式传输、工具、成本追踪、带退避的自动重试 #### Claude Code CLI 使用您的 Claude Code CLI。OpenCrabs 为完成生成启动本地 `claude` CLI。 **设置：** 1. 安装 [Claude Code CLI](https://github.com/anthropics/claude-code) 并认证（`claude login`） 2. 在 `config.toml` 中启用： ``` [providers.claude_cli] enabled = true ``` OpenCrabs 在本地处理所有工具、记忆和上下文——CLI 仅仅是 LLM 后端。 ### OpenAI **模型：** GPT-5 Turbo、GPT-5 在 `keys.toml` 中**设置**： ``` [providers.openai] api_key = "sk-YOUR_KEY" ``` ### GitHub Copilot **使用您的 GitHub Copilot 订阅**——无 API 费用，无需管理令牌。OpenCrabs 通过与 VS Code 和其他 Copilot 工具相同的 OAuth 设备流进行认证。 **设置**——在入门向导中选择 GitHub Copilot 并按 Enter。您将看到一个一次性代码，在 [github.com/login/device](https://github.com/login/device) 输入。授权后，模型从 Copilot API 自动获取。 **要求：** 有效的 [GitHub Copilot](https://github.com/features/copilot) 订阅（个人、企业或企业）。

手动配置（无向导）

OAuth 令牌在入门期间自动保存。如果需要重新认证，运行 `/onboard:provider` 并选择 GitHub Copilot。 在 `config.toml` 中启用： ``` [providers.github] enabled = true default_model = "gpt-4o" base_url = "https://api.githubcopilot.com/chat/completions" ```

**功能：** 流式传输、工具、`api.githubcopilot.com` 上的 OpenAI 兼容 API。Copilot 特定头（`copilot-integration-id`、`editor-version`）自动注入。短期 API 令牌每约 25 分钟在后台刷新。 ### OpenRouter — 400+ 模型，一个密钥 在 `keys.toml` 中**设置**——在 [openrouter.ai/keys](https://openrouter.ai/keys) 获取密钥： ``` [providers.openrouter] api_key = "sk-or-YOUR_KEY" ``` 通过单个 API 密钥访问来自每个主要提供商的 400+ 模型——Anthropic、OpenAI、Google、Meta、Mistral、DeepSeek、Qwen 等等。包含**免费模型**（DeepSeek-R1、Llama 3.3、Gemma 2、Mistral 7B）以及发布时的 stealth/preview 模型。 模型列表在入门期间和通过 `/models` 从 OpenRouter API **实时获取**——添加新模型时无需更新二进制。 ### Google Gemini **模型：** `gemini-2.5-flash`、`gemini-2.0-flash`、`gemini-1.5-pro`——从 Gemini API 实时获取 在 `keys.toml` 中**设置**——在 [aistudio.google.com](https://aistudio.google.com) 获取密钥： ``` [providers.gemini] api_key = "AIza..." ``` 在 `config.toml` 中启用并设置默认模型： ``` [providers.gemini] enabled = true default_model = "gemini-2.5-flash" ``` **功能：** 流式传输、工具使用、视觉、1M+ 令牌上下文窗口、`/models` 端点的实时模型列表 ### MiniMax **模型：** `MiniMax-M2.7`、`MiniMax-M2.5`、`MiniMax-M2.1`、`MiniMax-Text-01` **设置**——从 [platform.minimax.io](https://platform.minimax.io) 获取您的 API 密钥。添加到 `keys.toml`： ``` [providers.minimax] api_key = "your-api-key" ``` MiniMax 是具有竞争力的定价的 OpenAI 兼容提供商。它不公开 `/models` 端点，因此模型列表来自 `config.toml`（预配置了可用模型）。 ### z.ai GLM **模型：** `glm-4.5`、`glm-4.5-air`、`glm-4.6`、`glm-4.7`、`glm-5`、`glm-5-turbo`——从 z.ai API 实时获取 **设置**——从 [open.bigmodel.cn](https://open.bigmodel.cn) 获取您的 API 密钥。添加到 `keys.toml`： ``` [providers.zhipu] api_key = "your-api-key" ``` 在 `config.toml` 中启用并选择端点类型： ``` [providers.zhipu] enabled = true default_model = "glm-4.7" endpoint_type = "api" # "api" (General API) or "coding" (Coding API) ``` z.ai GLM（智谱 AI）提供两种可在入门或 `/models` 中选择的端点类型： - **通用 API**（`api`）——标准聊天完成，位于 `open.bigmodel.cn/api/paas/v4` - **编码 API**（`coding`）——代码优化端点，位于 `codeapi.bigmodel.cn/api/paas/v4` 两者使用相同的 API 密钥和模型名称。端点类型可在入门向导或 `/models` 对话框中切换。 **功能：** 流式传输、工具、OpenAI 兼容 API、`/models` 端点的实时模型列表 ### OpenCode CLI 使用 [OpenCode](https://github.com/opencode-ai/opencode) CLI 作为免费 LLM 后端——无需 API 密钥或订阅。OpenCrabs 为完成生成启动本地 `opencode` 二进制。 **设置：** 1. 安装 [OpenCode CLI](https://github.com/opencode-ai/opencode)（`go install github.com/opencode-ai/opencode@latest` 或从 releases 下载） 2. 在 `config.toml` 中启用： ``` [providers.opencode_cli] enabled = true default_model = "opencode/mimo-v2-pro-free" ``` 模型从 `opencode models` 实时获取。免费模型如 `mimo-v2-pro-free` 无需任何认证即可使用。 **功能：** 流式传输、工具、扩展思考支持、NDJSON 事件 ### Qwen Code CLI 使用 [Qwen Code](https://github.com/qwen-code/qwen-code) CLI 作为免费 LLM 后端——**每天 1000 次免费请求**，通过 Qwen OAuth。OpenCrabs 为完成生成启动本地 `qwen` 二进制。 **设置：** 1. 安装 Qwen Code CLI（`npm install -g @qwen-code/qwen-code` 或 `brew install qwen-code`） 2. 认证：运行 `qwen` 并按照 OAuth 流程（或设置 `DASHSCOPE_API_KEY` 进行 API 密钥认证） 3. 在 `config.toml` 中启用： ``` [providers.qwen_code_cli] enabled = true default_model = "qwen3-coder-plus" ``` **可用模型：** `qwen3-coder-plus`、`qwen3.5-plus`、`qwen3.6-plus`、`qwen3-coder-480a35`、`qwen3-coder-30ba3b`、`qwen3-max-2026-01-23` **功能：** 流式传输、工具、256K 上下文窗口、NDJSON 事件协议（Gemini CLI 分支） ### 自定义（OpenAI 兼容） **用于：** Ollama、LM Studio、LocalAI、Groq 或任何 OpenAI 兼容 API。 在 `config.toml` 中**设置**——每个自定义提供商需要一个名称（`custom.` 后的标签）： ``` [providers.custom.lm_studio] enabled = true base_url = "http://localhost:1234/v1" # or your endpoint default_model = "qwen2.5-coder-7b-instruct" # Optional: list your available models — shows up in /models and /onboard # so you can switch between them without editing config models = ["qwen2.5-coder-7b-instruct", "llama-3-8B", "mistral-7B-instruct"] ``` **多个自定义提供商**共存——定义任意多个，使用不同名称，通过 `/models` 切换： ``` [providers.custom.lm_studio] enabled = true base_url = "http://localhost:1234/v1" default_model = "qwen2.5-coder-7b-instruct" [providers.custom.ollama] enabled = false base_url = "http://localhost:11434/v1" default_model = "mistral" ``` `custom.` 后的名称是您选择的标签（例如 `lm_studio`、`nvidia`、`groq`）。`enabled = true` 的那个是活动的。密钥使用相同标签放在 `keys.toml` 中。所有配置的自定义提供商持久化——通过 `/models` 切换只是切换 `enabled`。 #### 使用 NVIDIA API + Kimi K2.5 免费原型设计 [Kimi K2.5](https://build.nvidia.com/moonshotai/kimi-k2.5) 是前沿规模的多模态混合专家（MoE）模型，在 **NVIDIA API 目录**上**免费**提供——无需设置计费或信用卡。它处理复杂推理和图像/视频理解，是付费模型（如 Claude 或 Gemini）的强大免费替代品，适用于实验和代理工作流。 **使用 OpenCrabs 自定义提供商设置测试和验证。** **快速开始：** 1. 在 [NVIDIA API 目录](https://build.nvidia.com/) 注册并验证您的账户 2. 转到 [Kimi K2.5 模型页面](https://build.nvidia.com/moonshotai/kimi-k2.5) 并点击 **获取 API 密钥**（或"查看代码"查看自动生成的密钥） 3. 通过 `/models` 或 `config.toml` 在 OpenCrabs 中配置： ``` [providers.custom.nvidia] enabled = true base_url = "https://integrate.api.nvidia.com/v1" default_model = "moonshotai/kimi-k2.5" ``` ``` # keys.toml [providers.custom.nvidia] api_key = "nvapi-..." ``` **提供商优先级：** MiniMax > OpenRouter > Anthropic > OpenAI > GitHub Copilot > Gemini > z.ai GLM > Claude CLI > OpenCode CLI > 自定义。第一个 `enabled = true` 的提供商用于新会话。每个提供商在 `keys.toml` 中有自己的 API 密钥——不共享或混淆。 **按会话提供商：** 每个会话记住它使用的提供商和模型。在一个会话切换到 Claude，在另一个切换到 Kimi——当您 `/sessions` 切换时，提供商自动恢复。无需每次都 `/models`。新会话继承当前提供商。 ### 备用提供商 如果您的首选提供商宕机，备用提供商按顺序自动尝试。任何已配置 API 密钥的提供商都可以作为备用： ``` [providers.fallback] enabled = true providers = ["openrouter", "anthropic"] # tried in order on failure ``` 在运行时，如果对主提供商的请求失败，每个备用都会被尝试直到成功 当 AI 请求需要权限的工具时，聊天中会显示内联审批提示。审批是会话感知的：后台会话会自动批准工具调用以免阻塞，切换会话不会丢失待处理的审批。 | 快捷键 | 操作 | |--------|------| | `↑` / `↓` | 导航审批选项 | | `Enter` | 确认所选选项 | | `D` / `Esc` | 拒绝工具请求 | | `V` | 切换参数详情 | **审批选项（TUI 和所有渠道）：** | 选项 | 效果 | |------|------| | **是** | 批准此次工具调用 | | **始终（会话）** | 自动批准此会话的所有工具（重启时重置） | | **YOLO（永久）** | 永久自动批准所有工具，持久化到 `config.toml` | | **否** | 拒绝此次工具调用 | 使用 `/approve` 随时更改审批策略（持久化到 `config.toml`）： | 策略 | 描述 | |------|------| | **仅批准** | 每次工具执行前都提示。如果你想审查代理的每个操作，请使用此选项。设置方式：`/approve` → "仅批准（始终询问）" | | **允许全部（会话）** | 仅对当前会话自动批准所有工具，重启时重置 | | **YOLO 模式** | 无需审批执行所有操作（新用户的默认选项）。设置方式：`/approve` → "YOLO 模式" | ## 🔍 调试和日志 OpenCrabs 使用**条件日志系统**——默认不生成日志文件。 ``` # Stack traces on crash RUST_BACKTRACE=1 opencrabs # Verbose console output (no file logging) RUST_LOG=debug opencrabs # Debug mode: rolling file logs to ~/.opencrabs/logs/, auto-cleanup after 7 days opencrabs -d # Both: file logs + verbose console output RUST_LOG=debug opencrabs -d ``` 无论通过 `cargo install opencrabs` 安装还是从源码构建，这四种方式都相同。 ``` # Log management opencrabs logs status # Check logging status opencrabs logs view # View recent entries opencrabs logs clean # Clean old logs opencrabs logs clean -d 3 # Clean logs older than 3 days ``` **启用调试模式（`-d`）时：** - 日志文件创建在 `~/.opencrabs/logs/` - DEBUG 级别包含线程 ID、文件名、行号 - 每日滚动轮转，嘈杂的 crate（hyper、h2、reqwest）抑制到 warn 级别 **禁用时（默认）：** - 不创建日志文件 - 仅 stderr 输出警告和错误 - 干净的工作区 ## 🧠 大脑系统和三层记忆 OpenCrabs 的大脑是**动态且自我维持的**。代理不从硬编码的系统提示中组装其个性、知识和行为，而是从工作区的文件中获取，这些文件可以在回合之间编辑。 ### 大脑工作区 大脑从 `~/.opencrabs/` 读取 markdown 文件： ``` ~/.opencrabs/ # Home — everything lives here ├── SOUL.md # Personality, tone, hard behavioral rules ├── IDENTITY.md # Agent name, vibe, style, workspace path ├── USER.md # Who the human is, how to work with them ├── AGENTS.md # Workspace rules, memory system, safety policies ├── TOOLS.md # Environment-specific notes (SSH hosts, API accounts) ├── MEMORY.md # Long-term curated context (never touched by auto-compaction) ├── SECURITY.md # Security policies and access controls ├── BOOT.md # Startup checklist (optional, runs on launch) ├── HEARTBEAT.md # Periodic task definitions (optional) ├── BOOTSTRAP.md # First-run onboarding wizard (deleted after setup) ├── config.toml # App configuration (provider, model, approval policy) ├── keys.toml # API keys (provider, channel, STT/TTS) ├── commands.toml # User-defined slash commands ├── tools.toml # Runtime-defined agent tools (HTTP, shell) ├── opencrabs.db # SQLite — sessions, messages, plans └── memory/ # Daily memory logs (auto-compaction summaries) └── YYYY-MM-DD.md # One per day, multiple compactions stack ``` 大脑文件每个回合都会重新读取——在消息之间编辑它们，代理会立即反映这些变化。缺失的文件会被静默跳过；始终存在一个硬编码的大脑前言。 ### 三层记忆架构 | 层级 | 位置 | 用途 | 管理方 | |------|------|------|--------| | **1. 大脑 MEMORY.md** | `~/.opencrabs/MEMORY.md` | 持久的、精选的知识，每回合加载到系统大脑中 | 你（用户） | | **2. 每日记忆日志** | `~/.opencrabs/memory/YYYY-MM-DD.md` | 自动压缩摘要，包含每个会话的结构化分解 | 自动（压缩时） | | **3. 混合记忆搜索** | `memory_search` 工具（FTS5 + 向量） | 混合语义搜索——BM25 关键词 + 向量嵌入（768 维，本地 GGUF）通过倒数排名融合。无 API 密钥，零成本，离线运行 | 代理（通过工具调用） | **工作原理：** 1. 当上下文达到 70% 时，自动压缩将对话总结为结构化分解（当前任务、决策、修改的文件、错误、下一步） 2. 摘要保存到每日日志 `~/.opencrabs/memory/2026-02-15.md`（一天内的多次压缩堆叠在同一文件中） 3. 摘要会在聊天中显示给你，让你看到被记住的内容 4. 文件在后台被索引到 FTS5 数据库，以便代理可以使用 `memory_search` 搜索过去的日志 5. 大脑 `MEMORY.md` 永远不会被自动压缩触及——它保持为你精选的、始终加载的上下文 #### 混合记忆搜索（FTS5 + 向量嵌入） 记忆搜索通过**倒数排名融合（RRF）**结合两种策略以获得两全其美的召回： 1. **FTS5 关键词搜索**——BM25 排名的全文匹配，带 porter 词干提取 2. **向量语义搜索**——通过本地 GGUF 模型（embeddinggemma-300M，约 300 MB）生成 768 维嵌入 嵌入模型在首次 TUI 启动时自动下载（约 300 MB，一次性），完全在 CPU 上运行。**无 API 密钥，无云服务，无按查询费用，离线工作。** 如果模型尚未可用（首次启动，仍在下载），搜索会优雅地降级到仅 FTS。 **为什么选择本地嵌入而非 OpenAI/云？** | | 本地（embeddinggemma-300M） | 云 API（如 OpenAI） | |---|---|---| | **成本** | 永久免费 | 约 $0.0001/查询，累积起来 | | **隐私** | 100% 本地，什么都不离开你的机器 | 数据发送到第三方 | | **延迟** | ~2ms（进程内，无网络） | 100-500ms（HTTP 往返） | | **离线** | 无需互联网即可工作 | 需要互联网 | | **设置** | 自动，无需 API 密钥 | 需要 API 密钥 + 计费 | | **质量** | 代码/会话召回优秀（768 维） | 通用场景略好 | | **大小** | 约 300 MB 一次性下载 | 不适用 | ### 用户定义的斜杠命令 用自然语言告诉 OpenCrabs：*"创建一个运行 deploy.sh 的 /deploy 命令"*——它会通过 `config_manager` 工具将命令写入 `~/.opencrabs/commands.toml`： ``` [[commands]] name = "/deploy" description = "Deploy to staging server" action = "prompt" prompt = "Run the deployment script at ./src/scripts/deploy.sh for the staging environment." ``` 命令与内置命令一起出现在自动补全中。每次代理响应后，`commands.toml` 会自动重新加载——无需重启。旧的 `commands.json` 文件会在首次加载时自动迁移。 ### 自我维持架构 OpenCrabs 可以修改自己的源代码、构建、测试和热重启——由代理通过 `rebuild` 工具或用户通过 `/rebuild` 触发： ``` /rebuild # User-triggered: build → restart prompt rebuild tool # Agent-triggered: build → ProgressEvent::RestartReady → restart prompt ``` **工作原理：** 1. 代理使用其内置工具（read、write、edit、bash）编辑源文件 2. `SelfUpdater::build()` 异步运行 `cargo build --release` 3. 成功时，发出 `ProgressEvent::RestartReady` → 桥接到 `TuiEvent::RestartReady` 4. TUI 切换到 **RestartPending** 模式——用户按 Enter 确认 5. `SelfUpdater::restart(session_id)` 通过 Unix `exec()` 替换进程 6. 新二进制文件以 `opencrabs chat --session ` 启动——恢复相同的对话 7. 发送一条隐藏的唤醒消息给代理，以便它问候用户并从中断处继续 **两条触发路径：** | 路径 | 入口点 | 信号 | |------|--------|------| | **代理触发** | `rebuild` 工具（代理编辑源文件后调用） | `ProgressCallback` → `RestartReady` | | **用户触发** | `/rebuild` 斜杠命令 | 直接 `TuiEvent::RestartReady` | **关键细节：** - 运行中的二进制文件在内存中——磁盘上的源文件更改在重启前不会影响它 - 如果构建失败，代理保持运行，可以读取编译器错误来修复它们 - 通过 SQLite 的会话持久化意味着重启不会丢失对话上下文 - 重启后，代理会自动唤醒并带会话上下文——无需用户输入 - 大脑文件（`SOUL.md`、`MEMORY.md` 等）每个回合都会重新读取，因此编辑会立即生效，无需重建 - 用户定义的斜杠命令（`commands.toml`）也在每次代理响应后自动重新加载 - 热重启仅限 Unix（`exec()` 系统调用）；在 Windows 上构建/测试步骤可以工作，但重启需要手动重新启动 **模块：** - `src/brain/self_update.rs` — `SelfUpdater` 结构体，包含 `auto_detect()`、`build()`、`test()`、`restart()` - `src/brain/tools/rebuild.rs` — `RebuildTool`（代理可调用，发出 `ProgressEvent::RestartReady`） ### 自我改进代理OpenCrabs 通过三种本地机制从经验中学习——数据永远不会离开你的机器： **1. 程序记忆——来自经验的自定义命令** 当代理完成复杂工作流、克服错误或遵循用户纠正时，它可以通过 `config_manager add_command` 将该工作流保存为可重用的斜杠命令。下次会话时，命令会出现在自动补全中，代理知道它的存在。 **2. 情景记忆——经验教训** 代理在工作时将重要知识写入 `~/.opencrabs/` 大脑文件： - `MEMORY.md` — 基础设施细节、故障排除模式、架构决策 - `USER.md` — 你的偏好、沟通风格、项目上下文 - `memory/YYYY-MM-DD.md` — 集成、修复和决策的每日日志 - 自定义文件（如 `DEPLOY.md`）——领域特定知识 **3. 跨会话召回——混合搜索** `memory_search` 和 `session_search` 工具使用混合 FTS5 + 向量语义搜索（倒数排名融合）从过去的会话和记忆文件中找到相关上下文。通过 `embeddinggemma-300M` 的本地嵌入——无需 API 调用。 **与云端"自我改进"代理的关键区别：** 你的记忆文件、命令和大脑文件 100% 本地且属于你。使用本地模型（LM Studio、Ollama），一切都保留在你的机器上。使用云提供商（Anthropic、MiniMax、OpenRouter），对话会通过他们的 API——但这些提供商默认按其服务条款注重隐私，你可以在设置中选择退出日志记录和训练数据。无论哪种方式，你的自我改进数据（技能、记忆、命令）永远不会离开你的机器。 ## ⏰ 定时任务和心跳 OpenCrabs 在你的机器上作为守护进程运行——一个始终在线的持久终端代理。这使得计划任务和后台任务变得原生且简单。 ### 定时任务——计划隔离会话 定时任务在后台作为隔离会话运行。每个任务有自己的会话、提供商、模型和上下文——与你的主聊天完全独立。 ``` # Add a cron job via CLI opencrabs cron add \ --name "morning-briefing" \ --cron "0 9 * * *" \ --tz "America/New_York" \ --prompt "Check my email, calendar, and weather. Send a morning briefing." \ --deliver telegram:123456789 # List all jobs opencrabs cron list # Enable/disable opencrabs cron enable morning-briefing opencrabs cron disable morning-briefing # Remove opencrabs cron remove morning-briefing ``` 代理还可以通过 `cron_manage` 工具从任何渠道自主创建、列出和管理定时任务： | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `--cron` | 必填 | 标准 cron 表达式（如 `"0 9 * * *"`） | | `--tz` | `UTC` | 计划时区 | | `--prompt` | 必填 | 要执行的指令 | | `--provider` | `[cron]` 默认或当前 | 覆盖提供商（如 `anthropic`、`gemini`、`minimax`） | | `--model` | `[cron]` 默认或当前 | 覆盖模型 | | `--thinking` | `off` | 思考模式：`off`、`on`、`budget` | | `--auto-approve` | `true` | 自动批准工具调用（隔离会话） | | `--deliver` | 无 | 传递结果的渠道（如 `telegram:123456`、`discord:789`、`slack:C0123`） | **提供商优先级：** 每任务 `--provider` > config.toml 中的 `[cron] default_provider` > 会话的活动提供商。为定时任务设置全局默认路由到更便宜的提供商，同时将交互会话保持在高级提供商： ``` [cron] default_provider = "minimax" default_model = "MiniMax-M2.7" ``` ### 心跳——主动后台检查 作为守护进程运行时，OpenCrabs 可以执行定期心跳检查。在工作区配置 `HEARTBEAT.md`（`~/.opencrabs/HEARTBEAT.md`），包含要监控的事项清单： ``` # Heartbeat Checklist - Check for urgent unread emails - Check calendar for events in the next 2 hours - If anything needs attention, message me on Telegram - Otherwise, reply HEARTBEAT_OK ``` 心跳提示每个回合都会加载到代理的大脑。当心跳触发时，代理读取 `HEARTBEAT.md` 并执行操作——检查邮件、日历、通知或你配置的任何内容。 ### 心跳 vs 定时任务 | | 心跳 | 定时任务 | |---|-----------|----------| | **时机** | 周期性（每 N 分钟） | 精确计划（cron 表达式） | | **会话** | 主会话（共享上下文） | 隔离会话（独立） | | **上下文** | 有对话历史 | 每次运行都是全新上下文 | | **用例** | 批量定期检查 | 独立计划任务 | | **模型** | 当前会话模型 | 每个任务可配置 | | **成本** | 每个周期单轮 | 每次运行完整会话 | **经验法则：** 使用心跳进行受益于对话上下文的轻量级监控。使用定时任务进行需要精确时间、不同模型或隔离的独立任务。 ### 开机自启动 要保持 OpenCrabs 始终运行，将其设置为随系统自动启动。 以下示例显示**默认配置文件**的手动设置。对于命名配置文件，在命令参数中将 `daemon` 替换为 `-p daemon`。 #### Linux（systemd） ``` mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/opencrabs.service << 'EOF' [Unit] Description=OpenCrabs AI Agent After=network.target [Service] ExecStart=%h/.cargo/bin/opencrabs daemon Restart=on-failure RestartSec=5 Environment=OPENCRABS_HOME=%h/.opencrabs [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable opencrabs systemctl --user start opencrabs # Check status systemctl --user status opencrabs # View logs journalctl --user -u opencrabs -f ``` #### macOS（launchd） ``` cat > ~/Library/LaunchAgents/com.opencrabs.agent.plist << 'EOF' Label com.opencrabs.agent ProgramArguments /usr/local/bin/opencrabs daemon RunAtLoad KeepAlive StandardOutPath /tmp/opencrabs.log StandardErrorPath /tmp/opencrabs.err EOF launchctl load ~/Library/LaunchAgents/com.opencrabs.agent.plist # Check status launchctl list | grep opencrabs # Stop and unload launchctl unload ~/Library/LaunchAgents/com.opencrabs.agent.plist ``` #### Windows（任务计划程序） 1. 按 `Win + R`，输入 `taskschd.msc`，按 Enter 2. 点击右侧面板中的**创建基本任务** 3. 名称：`OpenCrabs`，描述：`OpenCrabs AI Agent` 4. 触发器：**当我登录时** 5. 操作：**启动程序** 6. 程序：`C:\Users\\.cargo\bin\opencrabs.exe`（或你的二进制文件所在位置） 7. 参数：`daemon` 8. 勾选**在完成前打开属性对话框** 9. 在属性 > 设置中，勾选**如果任务失败，每 1 分钟重启一次** 或通过 PowerShell： ``` $action = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.cargo\bin\opencrabs.exe" -Argument "daemon" $trigger = New-ScheduledTaskTrigger -AtLogon $settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) Register-ScheduledTask -TaskName "OpenCrabs" -Action $action -Trigger $trigger -Settings $settings -Description "OpenCrabs AI Agent" ``` ## 🏗️ 架构 ``` Presentation Layer ↓ CLI (Clap) + TUI (Ratatui + Crossterm) ↓ Brain Layer (Dynamic system brain, user commands, config management, self-update) ↓ Application Layer ↓ Service Layer (Session, Message, Agent, Plan) ↓ Data Access Layer (SQLx + SQLite) ↓ Integration Layer (LLM Providers, LSP) ``` **关键技术：** | 组件 | Crate | |-----------|-------| | 异步运行时 | Tokio | | 终端 UI | Ratatui + Crossterm | | CLI 解析 | Clap（derive） | | 数据库 | SQLx（SQLite） | | 序列化 | Serde + TOML | | HTTP 客户端 | Reqwest | | 语法高亮 | Syntect | | Markdown | pulldown-cmark | | LSP 客户端 | Tower-LSP | | 提供商注册 | Crabrace | | 记忆搜索 | qmd（FTS5 + 向量嵌入） | | 错误处理 | anyhow + thiserror | | 日志 | tracing + tracing-subscriber | | 安全 | zeroize | ## 📁 项目结构 ``` opencrabs/ ├── src/ │ ├── main.rs # Entry point │ ├── lib.rs # Library root (crate root — required by Rust) │ ├── error/ # Error types (OpenCrabsError, ErrorCode) │ ├── logging/ # Conditional logging system │ ├── app/ # Application lifecycle │ ├── brain/ # Intelligence layer — LLM providers, agent, tools, brain system │ │ ├── agent/ # Agent service + context management │ │ ├── provider/ # Provider implementations (Anthropic, GitHub Copilot, OpenAI-Compatible: OpenRouter, Minimax, z.ai GLM, Custom) │ │ ├── tools/ # Tool system (read, write, bash, glob, grep, memory_search, etc.) │ │ ├── tokenizer.rs # Token counting (tiktoken-based) │ │ ├── prompt_builder.rs # BrainLoader — assembles system brain from workspace files │ │ ├── commands.rs # CommandLoader — user-defined slash commands (TOML) │ │ └── self_update.rs # SelfUpdater — build, test, hot-restart via exec() │ ├── channels/ # Messaging integrations + voice (feature-gated) │ │ ├── factory.rs # ChannelFactory — shared factory for channel agent services │ │ ├── telegram/ # Telegram bot (agent, handler) │ │ ├── whatsapp/ # WhatsApp Web client (agent, handler, store) │ │ ├── discord/ # Discord bot (agent, handler) │ │ ├── slack/ # Slack bot via Socket Mode (agent, handler) │ │ ├── trello/ # Trello board poller (agent, client, handler, models) │ │ └── voice/ # STT (Groq Whisper / whisper.cpp) + TTS (OpenAI / Piper) │ ├── cli/ # Command-line interface (Clap) │ ├── config/ # Configuration (config.toml + keys.toml) │ ├── db/ # Database layer (SQLx + SQLite) │ ├── services/ # Business logic (Session, Message, File, Plan) │ ├── memory/ # Memory search (FTS5 + vector embeddings via qmd) │ ├── tui/ # Terminal UI (Ratatui) │ │ ├── onboarding.rs # 8-step onboarding wizard (state + logic) │ │ ├── onboarding_render.rs # Wizard rendering │ │ ├── splash.rs # Splash screen │ │ ├── app.rs # App state + event handling │ │ ├── render.rs # Main render dispatch │ │ └── runner.rs # TUI event loop │ ├── utils/ # Utilities (retry, etc.) │ ├── migrations/ # SQLite migrations │ ├── tests/ # 1,827 tests (see TESTING.md) │ ├── benches/ # Criterion benchmarks │ ├── assets/ # Icons, screenshots, visual assets │ ├── scripts/ # Build and setup scripts │ └── docs/ # Documentation templates ├── Cargo.toml ├── config.toml.example ├── keys.toml.example └── LICENSE.md ``` ## 🛠️ 开发 ### 从源码构建 ``` # Development build cargo build # Release build (optimized, LTO, stripped) cargo build --release # Small release build cargo build --profile release-small # Run tests (1,827 tests across 60+ modules) cargo test --all-features # See TESTING.md for full test coverage documentation # Run benchmarks cargo bench # Format + lint cargo fmt cargo clippy -- -D warnings ``` ### 功能标志 | 功能 | 描述 | |-----------|-------------| | `telegram` | Telegram 机器人集成（默认：启用） | | `whatsapp` | WhatsApp Web 集成（默认：启用） | | `discord` | Discord 机器人集成（默认：启用） | | `slack` | Slack 机器人集成（默认：启用） | | `trello` | Trello 看板轮询 + 卡片管理（默认：启用） | | `local-stt` | 通过 rwhisper 的本地语音转文本（基于 candle，纯 Rust） | | `local-tts` | 通过 Piper 的本地文本转语音（需要 python3） | | `profiling` | 启用 pprof 火焰图分析（仅 Unix） | ### 性能 | 指标 | 值 | |--------|-------| | 二进制大小 | 34 MB（release，stripped，LTO） | | 空闲 RAM（RSS） | 57 MB | | 活跃 RAM（100 条消息） | ~20 MB | | 启动时间 | < 50 ms | | 数据库操作 | < 10 ms（会话），< 5 ms（消息） | | 嵌入引擎 | embeddinggemma-300M（约 300 MB，本地 GGUF，自动下载） | #### 记忆搜索（qmd — FTS5 + 向量嵌入） 混合语义搜索：FTS5 BM25 关键词匹配 + 768 维向量嵌入通过倒数排名融合。嵌入模型在本地运行——**无 API 密钥，零成本，离线工作**。 使用 release 构建通过 `cargo bench --bench memory` 基准测试： | 操作 | 时间 | 备注 | |--------|------|-------| | 打开存储 | 1.81 ms | 冷启动（创建 DB + schema） | | 索引文件 | 214 µs | 插入内容和文档 | | 哈希跳过 | 19.5 µs | 已索引，未更改——快速路径 | | FTS 搜索（10 文档） | 397 µs | 2 词 BM25 查询 | | FTS 搜索（50 文档） | 2.57 ms | 典型用户语料库 | | F 搜索（100 文档） | 9.22 ms | | | FTS 搜索（500 文档） | 88.1 ms | 大语料库 | | 向量搜索（10 文档） | 247 µs | 768 维余弦相似度 | | 向量搜索（50 文档） | 1.02 ms | 768 维余弦相似度 | | 向量搜索（100 文档） | 2.04 ms | 768 维余弦相似度 | | 混合 RRF（50 文档） | 3.49 ms | FTS + 向量 → 倒数排名融合 | | 插入嵌入 | 301 µs | 单个 768 维向量 | | 批量重索引（50 文件） | 11.4 ms | 从冷启动，包括存储打开 | | 停用文档 | 267 µs | 剪枝单个条目 | **基准测试**（release 构建，内存 SQLite，criterion）： | 操作 | 时间 | |---|---| | 索引 50 文件（首次运行） | 11.4 ms | | 每文件索引 | 214 µs | | 哈希跳过（未更改文件） | 19.5 µs | | FTS 搜索（10 文档） | 397 µs | | FTS 搜索（50 文档） | 2.57 ms | | FTS 搜索（100 文档） | 9.2 ms | | 向量搜索（10 文档，768 维） | 247 µs | | 向量搜索（50 文档，768 维） | 1.02 ms | | 向量搜索（100 文档，768 维） | 2.04 ms | | 混合 RRF（FTS + 向量，50 文档） | 3.49 ms | | 插入嵌入 | 301 µs | | 停用文档 | 267 µs | ## 🐛 平台说明 ### Linux ``` # Debian/Ubuntu sudo apt-get install build-essential pkg-config libssl-dev cmake # Fedora/RHEL sudo dnf install gcc gcc-c++ make pkg-config openssl-devel cmake # Arch sudo pacman -S base-devel pkg-config openssl cmake ``` #### 旧 CPU（Sandy Bridge / 仅 AVX） 默认 release 二进制需要 AVX2（Haswell 2013+）。如果你有仅支持 AVX 的旧 CPU（Sandy Bridge/Ivy Bridge，2011-2012），从源码构建： ``` RUSTFLAGS="-C target-cpu=native" cargo build --release ``` 在[发布页面](https://github.com/adolfousier/opencrabs/releases)也提供了仅 AVX CPU 的预构建 `*-compat` 二进制。如果你的 CPU 完全没有 AVX（2011 年之前），向量嵌入被禁用，搜索降级到仅 FTS 关键词匹配。 ### macOS 需要 **macOS 15（Sequoia）** 或更高版本。 ``` # Install build dependencies brew install cmake pkg-config ``` #### macOS 14（Sonoma）或更早版本的 Metal GPU 崩溃 运行 OpenCrabs 时如果看到此错误： ``` dyld: Symbol not found: _OBJC_CLASS_$_MTLResidencySetDescriptor ``` 这是因为 `llama.cpp`（用于本地嵌入）编译时包含 Metal GPU 支持，并无条件链接需要 macOS 15+ 的 Metal 框架。目前无法通过 Rust `llama-cpp-sys-2` crate 在构建时禁用 Metal。 **修复：** 更新到 macOS 15（Sequoia）或更高版本。 ### Windows 需要 CMake、NASM 和 Visual Studio Build Tools 来处理原生加密依赖： ``` # Option 1: Install build tools # - CMake (add to PATH) # - NASM (add to PATH) # - Visual Studio Build Tools ("Desktop development with C++") # Option 2: Use WSL2 (recommended) sudo apt-get install build-essential pkg-config libssl-dev ``` 详细故障排除请参阅 [BUILD_NOTES.md]( # Read a specific tweet node dist/cli.js x tweet "Hello world" # Post a tweet node dist/cli.js x reply "text" # Reply to tweet node dist/cli.js x like # Like a tweet node dist/cli.js x follow # Follow a user ``` **Instagram 命令：** ``` node dist/cli.js ig like node dist/cli.js ig comment "text" node dist/cli.js ig dm "message" node dist/cli.js ig follow node dist/cli.js ig followers -n 10 node dist/cli.js ig posts -n 3 ``` **LinkedIn 命令：** ``` node dist/cli.js linkedin like node dist/cli.js linkedin comment "text" node dist/cli.js linkedin connect node dist/cli.js linkedin search "query" -n 10 node dist/cli.js linkedin engage --query="query" # Full engagement session ``` **功能：** 人类行为（随机延迟、自然打字）、跨重启的会话持久化、内置速率限制、防检测、研究优先工作流（首先抓取目标，随着时间分散参与度）。 ## ⚠️ 免责声明 ### 开发状态 OpenCrabs 正在积极开发中。虽然功能正常，但可能包含错误或不完整的功能。 ### 代币费用责任 **你有责任监控和管理自己的 API 使用量和费用。** - 云提供商（Anthropic、OpenAI 等）的 API 费用由你负责 - 在你的提供商处设置计费提醒 - 考虑使用本地 LLM 以实现零成本运营 - 使用内置成本跟踪器监控支出 ### 支持 云 API 问题、计费问题和账户问题应直接联系各自的提供商。OpenCrabs 提供工具；你管理你的 API 关系。 ## 🤝 贡献 欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ``` # Setup git clone https://github.com/adolfousier/opencrabs.git cd opencrabs cargo build cargo test # Make changes, then submit a PR ``` ## 📄 许可证 **MIT 许可证**——详见 [LICENSE.md](LICENSE.md)。 ## 🙏 致谢 - **[Claude Code](https://github.com/anthropics/claude-code)** — 灵感来源 - **[Crabrace](https://crates.io/crates/crabrace)** — 提供商注册 - **[Ratatui](https://ratatui.rs/)** — 终端 UI 框架 - **[Anthropic](https://anthropic.com/)** — Claude API ## 📞 支持 - **问题：** [GitHub Issues](https://github.com/adolfousier/opencrabs/issues) - **讨论：** [GitHub Discussions](https://github.com/adolfousier/opencrabs/discussions) - **文档：** [Documentation](https://github.com/adolfousier/opencrabs/tree/main/src/docs) ## Star 历史图表 [](https://www.star-history.com/#adolfousier/opencrabs) ## ✨ 敬请期待 **由 Rust 🦀 构建 by [Adolfo Usier](https://github.com/adolfousier)** [最新发布](https://github.com/adolfousier/opencrabs/releases/tag/v0.2.81)

标签：DLL 劫持, Docker, LLM, Ratatui, Rust, TUI, Unmanaged PE, 单二进制, 可视化界面, 大语言模型, 安全防御评估, 开源, 开源框架, 持续集成, 无服务器, 本地运行, 终端工具, 网络流量审计, 网络调试, 自主Agent, 自动化, 自我修复, 通知系统