Necoclaw 使用指南

📥 安装

系统要求

项目	最低配置	推荐配置
操作系统	Windows 10 / macOS 10.15 / Ubuntu 20.04	Windows 11 / macOS 14+ / Ubuntu 22.04
CPU	1 核	2 核+
内存	200 MB	1 GB+
磁盘	200 MB	500 MB+
网络	需要能访问 LLM API（除非用本地 Ollama）

下载与启动

1. 前往 下载页 获取对应平台的安装包
2. 解压到任意目录，例如 D:\necoclaw\ 或 ~/necoclaw/
3. 启动 Necoclaw

   # Windows: 双击 start.bat
   # macOS / Linux: 在终端运行
   chmod +x start.sh
   ./start.sh

4. 浏览器打开 http://localhost:24088 进入 WebUI

常用命令

necoclaw start        # 启动 Agent（含 WebUI）
necoclaw doctor       # 检测系统环境
necoclaw onboard      # 首次配置向导
necoclaw --help       # 查看所有命令

🔑 配置 LLM

Necoclaw 需要至少一个 LLM 供应商才能驱动 AI 对话。有三种配置方式：

方式一：免费快速接入（推荐新手）

1. 访问 api.necoclaw.ai 注册账号
2. 在面板中获取 API Key（每日赠送 200 万 免费 Token，每日打卡再送 10 万）
3. 回到 WebUI，进入左侧 🔀 LLM 路由 › 供应商市场
4. 点击 "+ Custom Provider" 添加自定义供应商
5. 填写信息：

   字段	填写内容
   名称	NECOCLAW 官方
   API 类型	openai
   Base URL	https://api.necoclaw.ai/v1
   API Key	你在 api.necoclaw.ai 获取的 sk-xxx

6. 保存后，系统会自动拉取该供应商支持的模型列表并配置路由

方式二：本地 Ollama（离线运行）

1. 安装 Ollama：ollama.com
2. 拉取模型：ollama pull qwen3:14b
3. Necoclaw 会自动检测本地 Ollama 并添加为供应商，无需手动配置

方式三：手动添加供应商

在 🔀 LLM 路由 › 供应商市场 页面点击 "添加供应商"，填写：

字段	说明	示例
名称	供应商显示名	OpenAI / DeepSeek / Claude
API 类型	接口协议	openai（大部分都选这个）
Base URL	API 地址	https://api.openai.com/v1
API Key	你的密钥	sk-xxx...
默认模型	首选模型	gpt-4o

也可以直接编辑配置文件 config.yaml：

llm:
  providers:
    - id: my-openai
      api_type: openai
      base_url: https://api.openai.com/v1
      api_key: sk-xxx
      model: gpt-4o
  routes:
    - role: default
      provider_id: my-openai

💬 第一次对话

1. 点击左侧 💬 智能对话
2. 在左下方的聊天列表中，点击 Neco（默认管家）
3. 在底部输入框中输入消息，按 Enter 发送
4. Neco 会根据你的消息自动调用合适的工具——搜索、文件操作、代码执行等

🪞 数字分身（联系人）

Necoclaw 的"联系人"就是你创建的 AI 数字分身，每个分身有独立的角色、人格、记忆和技能。

创建分身

1. 在 💬 智能对话 页面，点击左侧聊天列表上方的 ➕ 按钮
2. 填写分身信息：

   字段	说明
   名称	分身的名字，如"产品经理小李"
   角色描述	分身的性格、专业领域、行为风格等。这是分身的"灵魂"
   头像	选择一个 emoji 或上传图片

3. 点击 保存，分身会出现在聊天列表中
4. 点击分身头像即可开始与 TA 对话

👥 群聊

群聊可以让多个 AI 分身同时参与讨论——它们会各自从自己的角色角度发言、争论、达成共识、分工执行。

创建群聊

1. 在聊天列表上方点击 👥 群聊按钮
2. 填写群聊名称，如"项目脑暴群"
3. 选择要加入的分身（至少 2 个），如"产品经理 + 技术负责人 + 研究员"
4. 点击 创建群聊

群聊的工作方式

你在群里发一条消息后，每个分身会按顺序轮流发言：

📋 定时任务

让 AI 在指定时间自动执行任务，不需要你在电脑前。

创建定时任务

1. 点击左侧 📋 任务看板
2. 点击 "新建任务"
3. 填写任务信息：

   字段	说明	示例
   任务名	简短描述	每日新闻摘要
   Prompt	AI 要执行的指令	搜索今天的AI领域新闻，总结为5条要点
   Schedule	Cron 表达式	0 8 * * *（每天早上8点）
   执行分身	哪个分身执行	Neco / 自定义分身
   回复到	结果发到哪里	某个联系人 / 群聊 / 飞书群

4. 点击 保存，任务将在指定时间自动运行

Cron 表达式速查

表达式	含义
0 8 * * *	每天 8:00
0 9 * * 1	每周一 9:00
0 */2 * * *	每 2 小时
0 8,18 * * *	每天 8:00 和 18:00
30 8 1 * *	每月 1 号 8:30

🎯 技能中心

技能是 Necoclaw 的"能力插件"。每个技能教会 AI 一种新的工作流程或专业能力。

内置技能

系统自带 70+ 种内置技能，涵盖：

从 Skill Hub 安装技能

1. 点击左侧 🎯 技能中心
2. 切换到 "Skill Hub" 标签页
3. 选择一个 Hub 源（默认已有社区技能源）
4. 浏览或搜索你需要的技能
5. 点击 "安装" 按钮，即刻生效

添加 GitHub 技能源

你可以将任何 GitHub 仓库作为技能源：

1. 在 Skill Hub 页面点击 "+" 按钮
2. 输入 GitHub 仓库地址，如 owner/repo
3. 系统会自动发现仓库中的技能并列出
4. 选择需要的技能安装即可

创建自定义技能

在技能中心的 "我的技能" 标签页点击 "新建"，用自然语言描述即可：

{
  "name": "周报生成器",
  "description": "根据本周对话记录自动生成周报",
  "trigger": "用户说'生成周报'或'本周总结'",
  "content": "# 周报生成流程\n1. 回顾本周所有对话记录\n2. 提取关键工作项和成果\n3. 按类别分组整理\n4. 生成 Markdown 格式周报\n5. 可选：保存为 .docx 文件"
}

🔀 LLM 路由

LLM 路由是 Necoclaw 的智能模型调度中心。它决定每条对话用哪个模型、走哪个供应商，并自动管理额度和费用。

路由状态

在 🔀 LLM 路由 › 路由状态 页面可以看到：

路由规则

路由规则决定不同类型的请求使用哪个供应商和模型：

角色 (Role)	用途	推荐模型
default	默认对话	gpt-4o / deepseek-chat / qwen-plus
fast	快速任务（翻译、摘要）	gpt-4o-mini / deepseek-chat
reasoning	复杂推理	o1 / claude-3.5-sonnet / deepseek-reasoner
creative	创意写作	claude-3.5-sonnet / gpt-4o
embedding	向量嵌入（记忆搜索）	text-embedding-3-small

供应商市场

在 🔀 LLM 路由 › 供应商市场 可以：

📡 消息渠道

除了 WebUI，Necoclaw 还支持接入多种消息平台。配置后，你可以通过这些平台直接与 AI 对话。

渠道	协议	说明
🌐 WebUI	内置	默认启用，浏览器直接访问
✈️ Telegram	Bot API	创建 Bot → 填入 Token
🎮 Discord	WebSocket	创建 Bot → 填入 Token
📱 飞书	WebSocket 长连接	企业应用 → 填入 App ID/Secret
💬 钉钉	Stream 模式	机器人 → 填入 Token
💼 Slack	Socket Mode	App → 填入 Bot Token
🐧 QQ	OneBot v11	需要 OneBot 实现（如 go-cqhttp）
💚 微信	WeChatFerry	需要 WeChatFerry 客户端

在 📡 渠道管理 页面配置。每个渠道填入对应的 Token/Key 即可接入。

🧠 记忆系统

Necoclaw 拥有 5 层记忆体系，让 AI 越用越懂你：

层级	名称	说明	存储方式
1	即时记忆	当前对话的上下文	内存（对话结束即释放）
2	短期记忆	近期对话摘要	自动摘要 → 数据库
3	长期记忆	你的偏好、习惯、知识	向量数据库（语义搜索）
4	角色人格	分身的性格和风格定义	配置文件
5	共享记忆	团队的共同知识库	向量数据库

在 🧠 长期记忆 页面可以：

🔄 更新升级

Necoclaw 内置自动更新系统。当有新版本可用时，WebUI 顶部会出现更新横幅。

1. 看到更新横幅后，点击 "立即更新"
2. 系统会自动：备份数据 → 下载新版本 → 替换二进制 → 重启
3. 更新期间会显示重连提示，等待几秒后自动恢复

❓ 常见问题

Q: 对硬件有什么要求？
A: 极低。1 核 CPU、200MB 内存、普通办公电脑即可长期运行，不依赖 GPU。

Q: 配了多个供应商，Necoclaw 怎么选？
A: 通过路由规则。你可以为不同类型的任务（快速/推理/创意）指定不同供应商。也可以全用 default 走同一个。

Q: 分身之间真的能自己聊天？
A: 是的。在群聊中，你发一条消息后，多个分身会依次从自己的角色角度回复，形成多角色讨论。

Q: 记忆会占用 Token 额度吗？
A: 记忆经过压缩优化，只占极少额度。长期记忆以摘要形式存储，语义搜索消耗的 Embedding Token 很少。

Q: 如何使用本地模型？
A: 安装 Ollama，拉取模型后 Necoclaw 自动检测。也可以手动添加任何兼容 OpenAI 格式的本地服务。

Q: 数据存在哪里？
A: 所有数据在本地 ~/.necoclaw/（Windows: %USERPROFILE%\.necoclaw\）。包括 memory.db（记忆）、config.yaml（配置）、skills/（技能）等。

Q: 自定义技能难不难？
A: 不难。用自然语言描述工作流程，保存为 JSON 格式即可。AI 会按你描述的步骤执行。

Q: 定时任务在电脑关机后还会执行吗？
A: 不会。定时任务需要 Necoclaw 保持运行。如果你需要 7×24 小时运行，可以将 Necoclaw 部署在服务器上。

Q: 支持哪些文档格式？
A: 读取：.docx .doc .xlsx .xls .pptx .pdf .csv .txt .md .json
写入：.docx .xlsx .pptx .csv .txt .md .json .html

Q: 进化数据可以重置吗？
A: 可以。在 📈 成长日志 中可以查看、调整或重置 AI 的学习数据。

文档持续更新中… 有问题可以在 GitHub Issues 反馈