{"id":50329580,"url":"https://github.com/CraftOS-dev/CraftBot","last_synced_at":"2026-06-15T00:01:26.001Z","repository":{"id":327683447,"uuid":"1108131694","full_name":"CraftOS-dev/CraftBot","owner":"CraftOS-dev","description":"A Personal AI Assistant that creates and operates its own SaaS tools","archived":false,"fork":false,"pushed_at":"2026-06-08T09:40:51.000Z","size":197784,"stargazers_count":340,"open_issues_count":32,"forks_count":32,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-08T11:24:22.150Z","etag":null,"topics":["agent-architecture","ai","ai-agents","computer-use-agent","content-engineering","help-wanted","llm","open-source","proactive-agent","tool-use"],"latest_commit_sha":null,"homepage":"https://craftos.net/craftbot.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CraftOS-dev.png","metadata":{"files":{"readme":"README.cn.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-02T04:11:26.000Z","updated_at":"2026-06-06T09:28:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"013916fe-8cad-4bc6-a417-c46bfc66669b","html_url":"https://github.com/CraftOS-dev/CraftBot","commit_stats":null,"previous_names":["zfoong/whitecollaragent","zfoong/craftbot","craftos-dev/craftbot"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/CraftOS-dev/CraftBot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CraftOS-dev%2FCraftBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CraftOS-dev%2FCraftBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CraftOS-dev%2FCraftBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CraftOS-dev%2FCraftBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CraftOS-dev","download_url":"https://codeload.github.com/CraftOS-dev/CraftBot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CraftOS-dev%2FCraftBot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34342089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-architecture","ai","ai-agents","computer-use-agent","content-engineering","help-wanted","llm","open-source","proactive-agent","tool-use"],"created_at":"2026-05-29T09:00:27.893Z","updated_at":"2026-06-15T00:01:25.989Z","avatar_url":"https://github.com/CraftOS-dev.png","language":"Python","funding_links":[],"categories":["🤖 AI Agents \u0026 Assistants"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/living_ui_banner.gif\" alt=\"CraftBot Banner\" width=\"1280\"/\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/craftbot_logo_text_small.png\" alt=\"CraftBot\" width=\"400\"/\u003e\n\u003c/div\u003e\n\n大多数 Agent 框架止步于对话和工具调用,CraftBot 走得更远。它会自己构建、演进并运行 SaaS 工具,然后通过这套工具层与你沟通,并替你完成自动化工作。\n\n除此之外,CraftBot 拥有通用 Agent 框架的全部核心能力。它像一位远程员工一样执行任务、记住你的偏好与目标,并主动帮助你规划和推进对你重要的事情。\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OS-Windows-blue?logo=windows\u0026logoColor=white\" alt=\"Windows\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OS-macOS-lightgrey?logo=apple\u0026logoColor=white\" alt=\"macOS\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OS-Linux-yellow?logo=linux\u0026logoColor=black\" alt=\"Linux\"\u003e\n\n\n  \u003ca href=\"https://github.com/CraftOS-dev/CraftBot\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/CraftOS-dev/CraftBot?style=social\" alt=\"GitHub Repo stars\"\u003e\n  \u003c/a\u003e\n\n  \u003cimg src=\"https://img.shields.io/github/license/CraftOS-dev/CraftBot\" alt=\"License\"\u003e\n\n  \u003ca href=\"https://discord.gg/ZN9YHc37HG\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\t\n[![SPONSORED BY E2B FOR STARTUPS](https://img.shields.io/badge/SPONSORED%20BY-E2B%20FOR%20STARTUPS-ff8800?style=for-the-badge)](https://e2b.dev/startups)\n\u003c/div\u003e\n\n\u003cp align=\"center\" style=\"display: inline-block\"\u003e\n\u003ca href=\"https://www.producthunt.com/products/craftbot?embed=true\u0026amp;utm_source=badge-top-post-badge\u0026amp;utm_medium=badge\u0026amp;utm_campaign=badge-craftbot\" target=\"_blank\" rel=\"noopener noreferrer\" style=\"display: inline-block\"\u003e\n\t\u003cimg alt=\"CraftBot - Self-hosted proactive AI assistant that lives locally | Product Hunt\" width=\"250\" height=\"54\" src=\"https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1110300\u0026amp;theme=dark\u0026amp;period=daily\u0026amp;t=1776679679509\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://theresanaiforthat.com/ai/craftbot/?ref=featured\u0026v=10277523\" target=\"_blank\" rel=\"nofollow\"\u003e\u003cimg width=\"265\" src=\"https://media.theresanaiforthat.com/featured-on-taaft.png?width=600\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e | \u003ca href=\"README.ja.md\"\u003e日本語\u003c/a\u003e | \u003ca href=\"README.zh-TW.md\"\u003e繁體中文\u003c/a\u003e | \u003ca href=\"README.ko.md\"\u003e한국어\u003c/a\u003e | \u003ca href=\"README.es.md\"\u003eEspañol\u003c/a\u003e | \u003ca href=\"README.pt-BR.md\"\u003ePortuguês\u003c/a\u003e | \u003ca href=\"README.fr.md\"\u003eFrançais\u003c/a\u003e | \u003ca href=\"README.de.md\"\u003eDeutsch\u003c/a\u003e\n\u003c/p\u003e\n\n## ✨ 核心特性\n\n除了能够创建并运行自有 SaaS 工具,CraftBot 还具备 Agent 框架的全部核心能力,可以作为一个通用 AI Agent 陪你处理任务、工具、记忆与日常工作流。\n\n- **Living UI.** 在 CraftBot 内部构建、导入或演进自定义应用。Agent 始终感知 UI 状态,并能直接读取、写入和操作其中的数据。\n- **多任务与会话路由.** 还在手动敲 `/new` 吗?CraftBot 能自行判断何时开启新会话、何时继续旧任务,让对话与上下文保持统一。\n- **自托管与 BYOK.** 灵活的 LLM 提供商体系,支持 OpenAI、Google Gemini、Anthropic Claude、OpenRouter 等。也可以用 Ollama 自行托管模型,实现零 Token 消耗。\n- **记忆系统.** 通过 RAG + Agent 文件系统 + 蒸馏,从你与 CraftBot 的交互中构建本地知识库。CraftBot 会在午夜「做梦」,整合一整天发生的事件。\n- **主动型 Agent.** 学习你的偏好、习惯和人生目标,然后主动进行规划并发起任务(当然要经过你的同意),帮你在生活中变得更好。\n- **外部工具集成.** 内置凭据与 OAuth 支持,可连接 Google Workspace、Slack、Notion、Zoom、LinkedIn、Discord 和 Telegram(还有更多正在路上)。\n- **Skills 与 MCP.** 已就绪 150+ MCP 与 170+ Skills,支持快速安装新的 Skills 与 MCP,也可以从已完成的任务中一键创建或改进 Skills。\n- **跨平台支持.** 完整支持 Windows、macOS 和 Linux,提供平台特定的代码分支以及 Docker 容器化方案。\n- **浏览器界面与 CLI 支持.** 用最适合你的方式使用 CraftBot:日常使用走简洁的浏览器 UI,脚本和无界面环境则可以走 CLI。\n\n---\n\n## 🧰 快速开始\n\n- **自带密钥 (BYOK)** — 灵活的 LLM 提供商系统，支持 OpenAI、Google Gemini、Anthropic Claude、BytePlus 和本地 Ollama 模型。可轻松切换提供商。\n- **记忆系统** — 在午夜整理并汇总一天中发生的事件。\n- **主动式代理** — 学习你的偏好、习惯和人生目标，然后进行规划并启动任务（当然需要你的批准）来帮助你改善生活。\n- **Living UI** — 在 CraftBot 中构建、导入或演进自定义应用。代理始终感知 UI 的状态，并可直接读取、写入和操作其数据。\n- **外部工具集成** — 连接 Google Workspace、Slack、Notion、Zoom、LinkedIn、Discord 和 Telegram（更多即将推出！），支持嵌入式凭据和 OAuth。\n- **MCP** — 模型上下文协议（Model Context Protocol）集成，通过外部工具和服务扩展代理能力。\n- **技能系统** — 可扩展的技能框架，内置任务规划、研究、代码审查、Git 操作等技能。\n- **跨平台** — 完整支持 Windows、macOS 和 Linux，具有平台特定代码变体和 Docker 容器化。\n\n\u003e [!IMPORTANT]\n\u003e **GUI 模式已弃用。** CraftBot 不再支持 GUI（桌面自动化）模式。请改用 Browser 或 CLI 模式。\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/craftbot_readme_features.png\" alt=\"CraftBot Banner\" width=\"1280\"/\u003e\n\t\u003cimg src=\"assets/craftbot_features_custom.png\" alt=\"CraftBot Banner\" width=\"1280\"/\u003e\n\u003c/div\u003e\n\n---\n\n\n## 🧰 环境设置\n\n### 前置要求\n- Python **3.10+**\n- `git`（克隆仓库所需）\n- 你所选 LLM 提供商的 API Key（OpenAI、Gemini 或 Anthropic）\n- `Node.js` **18+**（可选 - 仅浏览器界面需要）\n- `conda`（可选 - 如未找到，安装器会提供自动安装 Miniconda 的选项）\n\n### 我该选哪种方式？\n\n\u003e **不确定？选方案一。** 它会帮你搞定所有事。\n\n| | 方案一 — 服务安装 | 方案二 — Conda 安装 | 方案三 — 手动安装 |\n|---|---|---|---|\n| **适合谁** | 大多数用户、新手、测试 | 想要独立环境的 Conda 用户 | 进阶用户、自定义 Python、完全控制 |\n| **自动管理 Python 环境？** | ✅ 自动 | ✅ 自动 | ❌ 你自己管理 |\n| **后台运行？** | ✅ 是，作为服务 | ❌ 否 | ❌ 否 |\n| **启动方式** | `python craftbot.py install` | `python install.py --conda` | `python install.py` |\n\n---\n\n### ⭐ 方案一 — 服务安装（推荐）\n\n**适合你，如果：** 你希望 CraftBot 开箱即用——后台服务、开机自启、桌面快捷方式，无需手动操作。\n\n`craftbot.py` 全程自动处理：Python 环境、依赖安装、后台进程管理和自启注册。\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/CraftOS-dev/CraftBot.git\ncd CraftBot\n\n# 2. 安装、注册自启动并运行 CraftBot\npython craftbot.py install\n```\n\n就这么简单。终端会自动关闭,CraftBot 在后台运行,浏览器自动打开。同时还会创建一个**桌面快捷方式**,方便你随时重新打开浏览器。\n\n**安装完成后管理服务:**\n\n```bash\npython craftbot.py start      # 在后台启动 CraftBot\npython craftbot.py stop       # 停止 CraftBot\npython craftbot.py restart    # 重启 CraftBot\npython craftbot.py status     # 查看运行状态以及是否已启用自启动\npython craftbot.py logs       # 查看近期日志输出\npython craftbot.py uninstall  # 停止运行、移除自启动并卸载所有依赖包\n```\n\n\u003e [!TIP]\n\u003e 执行 `install` 或 `start` 之后会自动创建 **CraftBot 桌面快捷方式**。如果关闭了浏览器,双击该快捷方式即可重新打开。\n\n---\n\n## 🌱 Living UI\n\n**Living UI 是会随你的需求一同演进的系统/应用/仪表盘。**\n\n- 想要一个内置 AI 协作伙伴的看板?\n- 一套完全贴合你工作流的定制 CRM?\n- 一个 CraftBot 能替你读取并操作的公司仪表盘?\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/CraftOS-dev/CraftBot.git\ncd CraftBot\n\n# 2. 安装到 conda 环境\npython install.py --conda\n\n# 3. 运行 CraftBot\nconda run -n craftbot python run.py\n\n# 如果 conda 不在 PATH 中（仅 Windows）：\n\u0026\"$env:USERPROFILE\\miniconda3\\Scripts\\conda.exe\" run -n craftbot python run.py\n```\n\n\u003e [!NOTE]\n\u003e 每次运行 CraftBot 时，请使用 `conda run -n craftbot python run.py`。此方式没有后台服务——由你手动启停。\n\n---\n\n### 方案三 — 手动安装（pip）\n\n**适合你，如果：** 你希望完全掌控 Python 环境，不需要任何自动服务或后台进程，自己管理 CraftBot。\n\n`install.py`（不带参数）会对当前激活的 Python 环境执行标准 pip 安装。通过 `run.py` 手动启停 CraftBot。\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/CraftOS-dev/CraftBot.git\ncd CraftBot\n\n# 2. 在当前 Python 环境中安装依赖\npython install.py\n\n# 3. 运行 CraftBot\npython run.py\n```\n\n首次运行会引导你完成 API Key 设置和偏好配置。\n\n\u003e [!NOTE]\n\u003e 如果未安装 Node.js，安装器会提供详细指引。你也可以完全跳过浏览器模式，直接使用 CLI 模式——无需 Node.js：`python run.py --cli`\n\n### 安装完成后你可以做什么？\n- 用自然语言与代理交流\n- 让它执行复杂的多步骤任务\n- 输入 `/help` 查看可用命令\n- 连接 Google、Slack、Notion 等服务\n\n### 🖥️ 界面模式\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/WCA_README_banner.png\" alt=\"CraftOS Banner\" width=\"1280\"/\u003e\n\u003c/div\u003e\n\nCraftBot 支持多种 UI 模式。根据你的偏好选择：\n\n| 模式 | 命令 | 要求 | 最适合 |\n|------|---------|--------------|----------|\n| **浏览器** | `python run.py` | Node.js 18+ | 现代 Web 界面，最易使用 |\n| **CLI** | `python run.py --cli` | 无 | 命令行，轻量级 |\n\n**浏览器模式**是默认的推荐模式。如果你没有 Node.js，安装器会提供安装指引，或者你可以使用 **CLI 模式**。\n\n---\n\n## 🧬 Living UI\n\n**Living UI 是随你需求而进化的系统/应用/仪表盘。**\n\n需要一个内置 AI 副驾的看板？量身定制符合你工作流程的 CRM？\n一个 CraftBot 能读取并驱动的公司仪表盘？\n将它作为 Living UI 启动——它与 CraftBot 并行运行，并随着你的需求变化而成长。\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/living-ui-example.png\" alt=\"Living UI example\" width=\"1280\"/\u003e\n\u003c/div\u003e\n\n### 创建 Living UI 的三种方式\n\n1. **从零构建.** 用自然语言描述你想要的东西,CraftBot 会搭好数据模型、后端 API 和 React 前端,并通过一套结构化的设计流程与你不断迭代。\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/living-ui-custom-build.png\" alt=\"Building a Living UI from scratch\" width=\"448\"/\u003e\n\u003c/div\u003e\n\n2. **从市场安装.** 在 [living-ui-marketplace](https://github.com/CraftOS-dev/living-ui-marketplace) 中浏览社区构建的 Living UI。\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/living-ui-marketplace.png\" alt=\"Living UI marketplace\" width=\"448\"/\u003e\n\u003c/div\u003e\n\n3. **导入现有项目.** 把 Go、Node.js、Python、Rust 或者静态源码、GitHub 仓库交给 CraftBot,它会自动识别运行时、配置健康检查,并把它封装成一个 Living UI。\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/living-ui-import.png\" alt=\"Importing an existing project as a Living UI\" width=\"448\"/\u003e\n\u003c/div\u003e\n\n### 让 Agent 持续参与的不断演进\n\nLiving UI 永远没有「完成」这一说。需求一变,就让 Agent 给它加功能、改版页面或接入新数据源。\n\nCraftBot 嵌入在每个 Living UI 之中,并且**对其状态保持感知**:它可以读取当前 DOM 和表单值、通过 REST API 查询应用数据,并代替你触发操作。\n\n### 让 SaaS 工具保持开放与鲜活\n\n构建、定制并不断演进属于自己的 Living UI,减少对那些从未真正为你量身定制的订阅工具的依赖。\n\n我们正在积极寻找愿意展示自己 Living UI 的开发者,并支持将它们导出到 **[Living UI 市场](https://craftos.net/marketplace)**。欢迎提交 PR!\n\n---\n \n# 三个 5 分钟内可以试玩的 Living UI\n \n- **📋 看板** — 把所有任务、跟进事项和待办集中到一个地方,CraftBot 可以接手运营,替你完成 PM 工作。\n- **📊 习惯追踪器** — 培养并追踪自己的习惯,用类 GitHub 风格的活动日历像写代码一样维护你的习惯。\n- **🐦 Luolinglo** — 不是多邻国,但你可以学习新语言、做单词卡片,并和 CraftBot 一起练习。\n\n## 🧩 架构概览\n\n| 组件 | 说明 |\n|-----------|-------------|\n| **代理基础层 (Agent Base)** | 核心编排层，管理任务生命周期、协调各组件并处理主要的代理循环。 |\n| **LLM 接口** | 统一接口，支持多个 LLM 提供商（OpenAI、Gemini、Anthropic、BytePlus、Ollama）。 |\n| **上下文引擎** | 生成优化的提示词，支持 KV-cache。 |\n| **动作管理器** | 从动作库中检索和执行动作。自定义动作易于扩展。 |\n| **动作路由器** | 根据任务需求智能选择最佳匹配的动作，需要时通过 LLM 解析输入参数。 |\n| **事件流** | 实时事件发布系统，用于任务进度跟踪、UI 更新和执行监控。 |\n| **记忆管理器** | 基于 RAG 的语义记忆，使用 ChromaDB。处理记忆分块、向量化、检索和增量更新。 |\n| **状态管理器** | 全局状态管理，跟踪代理执行上下文、对话历史和运行时配置。 |\n| **任务管理器** | 管理任务定义，支持简单和复杂任务模式，创建待办事项，多步骤工作流跟踪。 |\n| **技能管理器** | 加载并将可插拔技能注入代理上下文。 |\n| **MCP 适配器** | 模型上下文协议集成，将 MCP 工具转换为原生动作。 |\n\n---\n \n# CraftBot 与其他方案的对比\n \n|                                  | v0 / Lovable / Bolt | OpenClaw | Claude Code | **CraftBot**                            |\n| -------------------------------- | ------------------- | -------------------- | -------------------- | --------------------------------------- |\n| **构建自定义应用**           | ✅ 一次性生成         | 🚫                   | ✅ (手动)          | ✅ 对话式持续构建                       |\n| **Agent 能操作应用**       | 🚫                  | ⚠️ 通过工具调用      | 🚫                   | ✅ 内置于每个 Living UI         |\n| **持久化的 Agent 记忆**      | 🚫                  | ✅            | ✅                   | ✅ RAG + Agent 文件系统 + 蒸馏        |\n| **自托管**     | ⚠️ 部分支持         | ✅                   | 🚫 SaaS              | ✅ MIT 协议,运行在你自己的机器上                    |\n| **模型无关**     | ✅         | ✅                   | ⚠️ 部分支持              | ✅ 主流厂商 + OpenRouter                    |\n \n---\n\n## 🔧 故障排查与常见问题\n\n### install.py\n\n| 参数 | 说明 |\n|------|-------------|\n| `--conda` | 使用 conda 环境（可选） |\n\n### run.py\n\n| 参数 | 说明 |\n|------|-------------|\n| （无） | 以**浏览器**模式运行（推荐，需要 Node.js） |\n| `--cli` | 以 **CLI** 模式运行（轻量级） |\n\n**安装示例：**\n```bash\n# 简单 pip 安装（不使用 conda）\npython install.py\n\n# 使用 conda 环境（推荐 conda 用户使用）\npython install.py --conda\n```\n\n**运行 CraftBot：**\n\n```powershell\n# 浏览器模式（默认，需要 Node.js）\npython run.py\n\n# CLI 模式（轻量级）\npython run.py --cli\n\n# 使用 conda 环境\nconda run -n craftbot python run.py\n\n# 如果 conda 不在 PATH 中，使用完整路径\n\u0026\"$env:USERPROFILE\\miniconda3\\Scripts\\conda.exe\" run -n craftbot python run.py\n```\n\n**Linux/macOS (Bash):**\n```bash\n# 浏览器模式（默认，需要 Node.js）\npython run.py\n\n# CLI 模式（轻量级）\npython run.py --cli\n\n# 使用 conda 环境\nconda run -n craftbot python run.py\n```\n\n### 🔧 后台服务（推荐）\n\n将 CraftBot 作为后台服务运行，关闭终端后仍可继续运行。系统会自动创建桌面快捷方式，随时可重新打开浏览器。\n\n```bash\n# 安装依赖、注册开机自启、启动 CraftBot\npython craftbot.py install\n```\n\n就这样。终端会自动关闭，CraftBot 在后台运行，浏览器自动打开。\n\n```bash\n# 其他服务命令：\npython craftbot.py start    # 在后台启动 CraftBot\npython craftbot.py status   # 检查是否正在运行\npython craftbot.py stop     # 停止 CraftBot\npython craftbot.py restart  # 重启 CraftBot\npython craftbot.py logs     # 查看最近日志输出\n```\n\n| 命令 | 说明 |\n|---------|-------------|\n| `python craftbot.py install` | 安装依赖、注册开机自启、启动 CraftBot、打开浏览器，并自动关闭终端 |\n| `python craftbot.py start` | 在后台启动 CraftBot（若已运行则自动重启，终端自动关闭） |\n| `python craftbot.py stop` | 停止 CraftBot |\n| `python craftbot.py restart` | 停止并重启 CraftBot |\n| `python craftbot.py status` | 检查 CraftBot 是否在运行，以及自动启动是否已启用 |\n| `python craftbot.py logs` | 显示最近日志（使用 `-n 100` 查看更多行） |\n| `python craftbot.py uninstall` | 停止 CraftBot、注销自启、卸载 pip 包并清理 pip 缓存 |\n\n\u003e [!TIP]\n\u003e 执行 `craftbot.py start` 或 `craftbot.py install` 后，系统会自动创建 **CraftBot 桌面快捷方式**。如果不小心关闭了浏览器，双击快捷方式即可重新打开。\n\n\u003e [!NOTE]\n\u003e **安装：** 安装器会在缺少依赖时提供清晰的指引。如果未找到 Node.js，会提示你安装或切换到 CLI 模式。安装会自动检测 GPU 可用性，必要时回退到仅 CPU 模式。\n\n\u003e [!TIP]\n\u003e **首次设置：** CraftBot 会引导你完成引导流程，配置 API Key、代理名称、MCP 和技能。\n\n\u003e [!NOTE]\n\u003e **Playwright Chromium：** WhatsApp Web 集成可选。如果安装失败，代理在其他任务上仍能正常工作。可稍后手动安装：`playwright install chromium`\n\n---\n\n## 🔧 故障排除与常见问题\n\n### 缺少 Node.js（浏览器模式）\n运行 `python run.py` 时看到 **\"npm not found in PATH\"**：\n1. 从 [nodejs.org](https://nodejs.org/) 下载（选择 LTS 版本）\n2. 安装并重启终端\n3. 再次运行 `python run.py`\n\n**替代方案：** 使用 CLI 模式（不需要 Node.js）：\n```bash\npython run.py --cli\n```\n\n### 安装时依赖失败\n安装器现在会提供更详细的错误信息和解决方案。如果安装失败:\n- **检查 Python 版本:** 确认已安装 Python 3.10+ (`python --version`)\n- **检查网络连接:** 安装过程中需要下载依赖\n- **清理 pip 缓存:** 运行 `pip install --upgrade pip` 后再次尝试\n\n### Playwright 安装失败\nPlaywright Chromium 的安装是可选项。即使失败:\n- Agent 在执行其他任务时**仍可正常工作**\n- 可以先跳过,稍后再用 `playwright install chromium` 安装\n- 仅在使用 WhatsApp Web 集成时才需要\n\n更详细的排查请参阅 [INSTALLATION_FIX.md](INSTALLATION_FIX.md)。\n\n---\n## 🐳 使用容器运行\n\n仓库根目录包含一份 Docker 配置,内含 Python 3.10、关键系统包(包括用于 OCR 的 Tesseract)以及 `environment.yml`/`requirements.txt` 中定义的所有 Python 依赖,确保 Agent 在隔离环境中也能稳定运行。\n\n下面是用容器运行 Agent 的步骤。\n\n### 构建镜像\n\n在仓库根目录执行:\n\n```bash\ndocker build -t craftbot .\n```\n\n### 运行容器\n\n镜像默认以 `python -m app.main` 启动 Agent。如需交互式运行:\n\n```bash\ndocker run --rm -it craftbot\n```\n\n需要传入环境变量时,可以挂载一个 env 文件(例如基于 `.env.example`):\n\n```bash\ndocker run --rm -it --env-file .env craftbot\n```\n\n通过 `-v` 挂载需要持久化到容器外的目录(例如数据或缓存目录),并根据你的部署需求调整端口或其他参数。镜像内置了 OCR(`tesseract`)所需的系统依赖和常见的 HTTP 客户端,让 Agent 可以直接在容器内处理文件和网络 API。\n\n镜像默认使用 Python 3.10,并已打包好 `environment.yml`/`requirements.txt` 中的依赖,因此 `python -m app.main` 开箱即用。\n\n---\n\n## 🤝 如何参与贡献\n\n欢迎提交 PR!工作流(fork → 从 `dev` 创建分支 → 提 PR)详见 [CONTRIBUTING.md](CONTRIBUTING.md)。所有 PR 都会自动跑 lint + 冒烟测试 CI。\n\n\u003e [!IMPORTANT]\n\u003e **CraftBot** 仍在积极开发中,每周都有改进。如果有问题或希望更快交流,欢迎加入 [Discord](https://discord.gg/ZN9YHc37HG),或发邮件至 thamyikfoong(at)craftos.net。\n\n---\n\n## 🧾 许可证\n\n本项目基于 [MIT License](LICENSE) 开源。你可以自由地使用、托管以及商业化运营本项目(如果用于分发或商业化,需要保留对本项目的署名)。\n\n---\n\n## ⭐ 致谢\n\n由 [CraftOS](https://craftos.net/) 及贡献者共同开发与维护。\n如果你觉得 **CraftBot** 有帮助,欢迎给仓库点 ⭐ 并分享给身边的人!\n\n---\n\n## Star 历史\n\n\u003ca href=\"https://www.star-history.com/?repos=CraftOS-dev%2FCraftBot\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=CraftOS-dev/CraftBot\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=CraftOS-dev/CraftBot\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=CraftOS-dev/CraftBot\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCraftOS-dev%2FCraftBot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCraftOS-dev%2FCraftBot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCraftOS-dev%2FCraftBot/lists"}