Copaw Console
CoPaw 控制台指南
控制台是 CoPaw 内置的 Web 管理界面。运行 copaw app 后，在浏览器中打开 http://127.0.0.1:8088/
即可进入。
访问控制台
# 启动 CoPaw
copaw app
在浏览器中打开
http://127.0.0.1:8088/
聊天
路径：聊天 → 聊天
这是你和 CoPaw 对话的地方。打开控制台后默认就是这个页面。
发送消息
：在底部输入框中输入内容，按 Enter 或点击发送按钮，CoPaw 会实时回复。
新建会话
：点击聊天页面侧边栏顶部的 + New Chat 按钮，开始一段全新的对话。
切换会话
：点击聊天页面侧边栏中的任意会话名称，即可加载该会话的历史消息。
删除会话
：点击任意会话条目右侧的 ··· 按钮，再点击出现的垃圾桶图标即可删除。
频道
路径：控制 → 频道
在这里管理各消息频道（钉钉、飞书、Discord、QQ、iMessage、Console）的开关和凭据。
启用一个频道
：
- 点击你要配置的频道卡片
- 右侧滑出配置面板，打开 Enable 开关
- 填写该频道所需的凭据
| 频道 | 需要填写的字段 |
|------|--------------|
| 钉钉 | Client ID、Client Secret |
| 飞书 | App ID、App Secret、加密密钥、验证令牌、媒体文件目录 |
| Discord | Bot Token、HTTP 代理、代理认证 |
| QQ | App ID、Client Secret |
| iMessage | 数据库路径、轮询间隔 |
| Console | （只需开关） |
- 点保存，几秒内自动生效，无需重启
禁用一个频道
：打开同一个配置面板，关闭 Enable 开关，然后保存。
会话
路径：控制 → 会话
在这里查看、筛选和清理所有频道的聊天会话。
查找会话
：在搜索框中输入用户名过滤，或用下拉菜单按频道筛选，表格会即时更新。
重命名会话
：点击某行的编辑按钮 → 修改名称 → 点保存。
删除单条会话
：点击某行的删除按钮 → 弹窗确认即可。
批量删除
：勾选要删除的行 → 点击出现的批量删除按钮 → 确认。
定时任务
路径：控制 → 定时任务
在这里创建和管理 CoPaw 按时间自动执行的定时任务。
创建新任务
：
最简单的方式是直接与 CoPaw 对话，让他为你创建。例如："帮我创建一个定时任务，每隔 5 分钟提醒我喝水。"
另一种方式是在控制台页面创建：
- 点击 + 创建任务 按钮
- 按区域填写表单：
- 基本信息：给任务一个 ID（如 job-001）、一个名称（如「每日摘要」），并打开启用开关
- 调度：填写 Cron 表达式（如
0 9 *= 每天上午 9 点）并选择时区 - 任务类型及内容：选择文本（发送固定消息）或 Agent（向 CoPaw 提问并转发回复），然后填入具体内容
- 投递：选择目标频道（如 Console、钉钉）、目标用户，以及投递方式（流式 = 实时发送，最终 = 完成后一次性发送）
- 高级选项：按需调整最大并发数、超时时间和宽限时间
3. 点保存
编辑任务
：点击某行的编辑按钮 → 修改任意字段 → 保存。
启用 / 禁用任务
：点击行内的开关即可。
立即执行一次
：点击立即执行 → 确认，任务会马上运行一次。
删除任务
：点击删除 → 确认。
工作区
路径：智能体 → 工作区
在这里编辑定义 CoPaw 人设和行为的文件——SOUL.md、AGENTS.md、HEARTBEAT.md 等——全部在浏览器中完成。
编辑文件
：
- 点击文件列表中的文件名（如 SOUL.md）
- 文件内容出现在编辑器中，关闭预览按钮，修改内容
- 点保存生效，或点重置放弃修改并重新加载
查看每日记忆
：如果存在 MEMORY.md，点击旁边的 ▶ 箭头可展开按日期分组的条目，点击某个日期即可查看或编辑当天的记忆。
下载整个工作区
：点击下载按钮（⬇），工作区会打包为 .zip 文件保存到本地。
上传 / 恢复工作区
：点击上传按钮（⬆）→ 选择 .zip 文件（最大 100 MB），当前工作区文件会被替换。适合在不同机器之间迁移或从备份恢复。
技能
路径：智能体 → 技能
在这里管理扩展 CoPaw 能力的技能（如读取 PDF、创建 Word 文档、获取新闻等）。
启用技能
：点击技能卡片底部的启用链接，立即生效。
查看技能详情
：点击技能卡片可查看完整说明。
禁用技能
：点击禁用链接，同样立即生效。
从 Skill Hub 中导入技能
：
- 点击导入技能
- 输入技能 URL，点击导入技能
- 等待技能导入，成功后可在技能列表中看到已启用
创建自定义技能
：
- 点击创建技能
- 输入技能名称（如 weather_query）和技能内容（Markdown 格式，需包含 name 和 description）
- 点保存，新技能立即出现
删除自定义技能
：先禁用该技能，然后点击卡片上的 🗑 图标 → 确认删除。
MCP
路径：智能体 → MCP
在这里启用/禁用/删除 MCP，或者创建新的客户端。
创建客户端
：点击右上角的创建客户端，填写必要信息，点击创建，可以看到 MCP 客户端列表中新增内容。
运行配置
路径：智能体 → 运行配置
在这里修改最大迭代次数和最大输入长度，修改后点击保存。
模型
路径：设置 → 模型
在这里配置 LLM 提供商并选择 CoPaw 使用的模型。CoPaw 同时支持云提供商（需要 API Key）和本地提供商（无需 API Key）。
云提供商
配置提供商
：
- 点击提供商卡片（ModelScope、DashScope）上的设置按钮
- 输入你的 API Key
- 点保存，卡片状态变为「已授权」
- 如果想添加自定义提供商，点击右侧添加提供商
- 输入提供商 ID、显示名称等必要信息，点击创建
- 找到创建的提供商，点击设置，填写必要信息，选择保存，卡片状态变为「已授权」
撤销授权
：打开提供商的设置对话框，点击撤销授权，API Key 会被清除；如果当前使用的就是该提供商，模型选择也会一并清空。
本地提供商（llama.cpp / MLX）
本地提供商显示紫色的本地标签。使用前需先安装后端依赖：
pip install 'copaw[llamacpp]'
或
pip install 'copaw[mlx]'
下载模型
：
- 点击本地提供商卡片上的模型按钮
- 点击下载模型，填写：
- Repo ID（必填）—— 如 Qwen/Qwen3-4B-GGUF
- 文件名（可选）—— 留空自动选择
- 下载源 —— Hugging Face（默认）或 ModelScope
3. 点击下载，等待下载完成
查看和删除模型
：已下载的模型列在管理面板中，显示文件大小、来源标记（HF/MS）和删除按钮。
Ollama 提供商
Ollama 提供商集成本地 Ollama 守护进程，动态加载其中的模型。
前置条件
：
- 从 ollama.com 安装 Ollama
- 安装 Ollama SDK：
pip install 'copaw[ollama]'（或使用--extras ollama重新运行安装脚本）
下载模型
：
- 点击 Ollama 提供商卡片的设置按钮
- 在 API key 中填写内容，例如可以直接填写为 ollama，点击保存
- 点击 Ollama 卡片中的模型按钮，点击下载模型，输入模型名称（如 mistral:7b、qwen3:8b）
- 点击下载模型，等待下载完成
取消下载
：下载过程中，点击进度指示器旁的 ✕ 按钮即可取消。
查看和删除模型
：已下载的模型列在管理面板中，显示大小和删除按钮。通过 Ollama CLI 或控制台添加/删除模型时，列表会自动更新。
与本地模型的区别
：
- 模型来自 Ollama 守护进程（不由 CoPaw 直接下载）
- 模型列表与 Ollama 自动同步
- 支持热门模型：mistral:7b、qwen3:8b 等
>
⚠️ 运行 CoPaw 前必须将上下文长度设为 32K 以上
>
>
为了正常运行 CoPaw，必须将模型 context length 设置为 32K 或更高。注意，这会消耗较多的计算资源，请确保你的本地机器能够支持。
LM Studio 提供商
LM Studio 提供商连接 LM Studio 桌面应用内置的 OpenAI 兼容本地服务器，自动发现并使用已加载的模型。
前置条件
：
- 从 lmstudio.ai 安装 LM Studio
- 在 LM Studio 中加载模型并启动本地服务器（默认地址：http://localhost:1234）
配置步骤
：
- 点击 LM Studio 提供商卡片的设置按钮
- 默认 Base URL 为 http://localhost:1234/v1，如有需要可修改，点击保存
- 点击模型查看 LM Studio 中当前已加载的模型，也可手动添加模型 ID
- 在提供商下拉菜单中选择 LM Studio，选择模型后点击保存
>
LM Studio 默认不需要 API Key。模型必须在 LM Studio 中加载后才会在 CoPaw 中显示。
>
>
⚠️ 运行 CoPaw 前必须将上下文长度设为 32K 以上
>
>
为了正常运行 CoPaw，必须将模型 context length 设置为 32K 或更高。注意，这会消耗较多的计算资源，请确保你的本地机器能够支持。
选择活跃模型
- 在顶部 LLM 配置的提供商下拉菜单中选择一个提供商（只显示已授权或有已下载模型的本地提供商）
- 在模型下拉菜单中选择一个模型
- 点保存
>
注意：云提供商 API Key 的有效性需要用户自行保证，CoPaw 不会验证。
环境变量
路径：设置 → 环境变量
在这里管理 CoPaw 的工具和技能在运行时需要的环境变量（如 TAVILY_API_KEY）。
添加变量
：
- 点击底部的 + 添加变量
- 输入变量名（如 TAVILY_API_KEY）和对应的值
- 点击保存
编辑变量
：修改已有行的 Value 字段，然后点保存。（变量名保存后为只读，如需改名请先删除再新建。）
删除变量
：点击行右侧的 🗑 图标 → 如有提示则确认。
批量删除
：勾选要删除的行 → 点工具栏的删除 → 确认删除。
>
注意：环境变量值的有效性需要用户自行保证，CoPaw 只负责存储和加载。
Token 消耗
路径：设置 → Token 消耗
在这里查看一段时间内的 LLM Token 消耗，按日期和模型统计。
查看消耗
：
- 选择日期范围（默认最近 30 天）
- 点击刷新获取数据
- 页面展示总 Token 数、总调用次数、按模型和按日期的明细
通过对话查询
：在聊天中直接问 CoPaw「最近用了多少 token？」或「帮我看看 token 消耗」，Agent 会调用 get_token_usage 工具并返回统计结果。
数据存储在 ~/.copaw/token_usage.json
，可通过 COPAW_TOKEN_USAGE_FILE 环境变量自定义文件名。
快速索引
| 页面 | 侧边栏路径 | 你能做什么 |
|------|----------|----------|
| 聊天 | 聊天 → 聊天 | 和 CoPaw 对话、管理会话 |
| 频道 | 控制 → 频道 | 启用/禁用频道、填入凭据 |
| 会话 | 控制 → 会话 | 筛选、重命名、删除会话 |
| 定时任务 | 控制 → 定时任务 | 创建/编辑/删除任务、立即执行 |
| 工作区 | 智能体 → 工作区 | 编辑人设文件、查看记忆、上传/下载 |
| 技能 | 智能体 → 技能 | 启用/禁用/创建/删除技能 |
| MCP | 智能体 → MCP | 启用/禁用/创建/删除 MCP |
| 运行配置 | 智能体 → 运行配置 | 修改运行配置 |
| 模型 | 设置 → 模型 | 配置提供商 API Key、管理本地/Ollama/LM Studio 模型、选择模型 |
| 环境变量 | 设置 → 环境变量 | 添加/编辑/删除环境变量 |
| Token 消耗 | 设置 → Token 消耗 | 查看 LLM Token 消耗统计、按日期和模型筛选 |
