CoPaw Docker 部署方案

CoPaw 的 Docker 部署方案，支持一键构建和运行，相比官方镜像更小。

关于 CoPaw

CoPaw 是一款个人助理型产品，部署在你自己的环境中。

更多信息请看官方仓库：https://github.com/agentscope-ai/CoPaw

⚠️ 安全警告 ⚠️

CoPaw 没有任何权限控制和登录功能，切勿将服务端口暴露到公网！

WebUI 管理界面没有登录验证机制，任何能访问该端口的人都可以完全控制你的 CoPaw 实例。点击展开安全建议。

默认端口 8088 仅应在受信任的内网环境或通过反向代理 + 认证等方式访问
如果必须远程访问，请使用以下安全措施之一：
- 通过 SSH 隧道访问：ssh -L 8088:localhost:8088 your-server
- 配置 Nginx/Caddy 等反向代理并添加 Basic Auth 或 OAuth 认证
- 使用防火墙限制访问来源 IP

快速开始

前置要求

Docker >= 20.10
Docker Compose >= 2.0

使用方式选择

方式一：快速体验

最简单的方式，直接使用 docker run 命令启动，适合快速体验。

docker run -d --name copaw \
  -p 127.0.0.1:8088:8088 \
  -v copaw-data:/data/copaw \
  --restart unless-stopped \
  ghcr.io/log-z/copaw-docker:latest

访问控制台：http://localhost:8088

方式二：使用 Docker Compose（推荐✨）

使用 Docker Compose 方便管理和配置。

1. （可选）配置环境变量

如需提前配置 API Keys，可复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件填入你的配置。也可以在应用启动后通过 Web UI 进行配置。

2. 拉取并启动服务

docker compose pull      # 拉取或更新镜像
docker compose up -d     # 后台启动服务

3. 查看日志

docker compose logs -f copaw

4. 访问控制台

浏览器打开：http://localhost:8088

方式三：自行构建镜像

如果需要自定义镜像或预构建镜像不可用，可以自行构建。

1. （可选）配置环境变量

同方式二。

2. 修改 docker-compose.yml

编辑 docker-compose.yml，注释掉预构建镜像配置，取消注释构建配置：

copaw:
  # image: ghcr.io/log-z/copaw-docker:latest  # 注释预构建镜像
  build:                                     # 取消注释构建配置
    context: .
    dockerfile: Dockerfile
  image: copaw:latest

3. 构建镜像

docker compose build

4. 启动服务、查看日志、访问控制台

同方式二。

项目结构

copaw/
├── .github/
│   └── workflows/
│       ├── dev-test.yml       # 开发环境测试工作流
│       ├── prod-test.yml      # 生产环境测试工作流
│       └── release-image.yml  # 发布镜像工作流
├── docs/
│   └── copaw-info.md          # CoPaw 官方文档信息汇总
├── scripts/
│   ├── entrypoint.sh          # 容器启动脚本（自动初始化检查）
│   ├── healthcheck.sh         # 健康检查脚本（Docker HEALTHCHECK）
│   ├── test-startup.sh        # 启动流程测试脚本
│   └── validate-config.sh     # 配置文件验证脚本（启动前检查环境）
├── .dockerignore              # Docker 构建忽略文件
├── .env.example               # 环境变量配置示例
├── .gitignore                 # Git 忽略文件配置
├── CLAUDE.md                  # Claude Code 工作指引
├── Dockerfile                 # 多阶段构建的 Docker 镜像定义
├── README.md                  # 本文件
└── docker-compose.yml         # Docker Compose 编排配置

数据卷结构（运行时生成）

copaw-data:/
├── copaw.secret -> copaw/.runtime    # 软链接指向 .runtime（兼容 SECRET_DIR）
└── copaw/
    ├── .runtime/              # 敏感配置目录（providers.json、envs.json）
    ├── config.json            # 主配置文件（通道、心跳、语言等）
    ├── SOUL.md                # Agent 核心身份与行为原则（必填）
    ├── AGENTS.md              # 详细工作流程与指南（必填）
    ├── MEMORY.md              # 长期记忆存储
    ├── PROFILE.md             # 身份和用户画像
    ├── HEARTBEAT.md           # 心跳任务配置
    ├── jobs.json              # 定时任务列表
    ├── chats.json             # 会话列表
    ├── active_skills/         # 当前激活的技能
    ├── customized_skills/     # 用户自定义技能
    ├── custom_channels/       # 用户自定义频道模块
    ├── mcp_clients/           # MCP 客户端配置
    └── memory/                # Agent 记忆文件存储（含每日日志）

常用命令

容器管理

# 启动服务
docker compose up -d

# 停止服务
docker compose stop

# 重启服务
docker compose restart

# 查看日志
docker compose logs -f copaw

# 进入容器
docker compose exec copaw bash

# 停止并删除容器
docker compose down

数据管理

# 查看数据卷
docker volume inspect copaw-data

# 备份数据
docker run --rm -v copaw-data:/data -v $(pwd):/backup \
    alpine tar czf /backup/copaw-backup-$(date +%Y%m%d).tar.gz -C /data .

# 恢复数据
docker run --rm -v copaw-data:/data -v $(pwd):/backup \
    alpine tar xzf /backup/copaw-backup-YYYYMMDD.tar.gz -C /data

CoPaw 命令（在容器内执行）

# 初始化
docker compose exec copaw copaw init --defaults   # 默认配置（不交互）
docker compose exec copaw copaw init              # 交互式初始化

# 模型管理（云端提供商）
docker compose exec copaw copaw models list                    # 查看所有提供商
docker compose exec copaw copaw models config                  # 交互式配置
docker compose exec copaw copaw models config-key modelscope   # 配置 ModelScope API Key
docker compose exec copaw copaw models config-key dashscope    # 配置 DashScope API Key
docker compose exec copaw copaw models config-key custom       # 配置自定义提供商
docker compose exec copaw copaw models set-llm                 # 切换活跃模型

# 模型管理（本地模型 - 需额外依赖）
docker compose exec copaw copaw models download <repo_id>      # 下载本地模型 (llama.cpp/MLX)
docker compose exec copaw copaw models local                   # 查看已下载模型
docker compose exec copaw copaw models remove-local <model_id> # 删除已下载模型
docker compose exec copaw copaw models ollama-pull <model>     # 拉取 Ollama 模型
docker compose exec copaw copaw models ollama-list             # 列出 Ollama 模型

# 频道管理
docker compose exec copaw copaw channels list       # 查看所有频道
docker compose exec copaw copaw channels config     # 交互式配置
docker compose exec copaw copaw channels install <key>    # 安装自定义频道
docker compose exec copaw copaw channels add <key>        # 添加频道到配置
docker compose exec copaw copaw channels remove <key>     # 删除自定义频道

# 技能管理
docker compose exec copaw copaw skills list         # 查看所有技能
docker compose exec copaw copaw skills config       # 交互式启用/禁用

# 定时任务
docker compose exec copaw copaw cron list           # 列出所有任务
docker compose exec copaw copaw cron create ...     # 创建任务
docker compose exec copaw copaw cron state <job_id> # 查看任务状态
docker compose exec copaw copaw cron pause <job_id> # 暂停任务
docker compose exec copaw copaw cron resume <job_id># 恢复任务
docker compose exec copaw copaw cron run <job_id>   # 立即执行一次

# 环境变量
docker compose exec copaw copaw env list            # 列出所有变量
docker compose exec copaw copaw env set KEY VALUE   # 设置变量
docker compose exec copaw copaw env delete KEY      # 删除变量

# 会话管理
docker compose exec copaw copaw chats list          # 列出所有会话
docker compose exec copaw copaw chats get <id>      # 查看会话详情
docker compose exec copaw copaw chats create ...    # 创建新会话
docker compose exec copaw copaw chats update <id> --name "新名称"  # 重命名会话
docker compose exec copaw copaw chats delete <id>   # 删除会话

# 维护
docker compose exec copaw copaw clean               # 清空工作目录（交互确认）
docker compose exec copaw copaw clean --yes         # 不确认直接清空

# 配置重载（无需重启容器，v0.0.5+）
docker compose exec copaw copaw daemon reload-config # 重新加载配置
docker compose exec copaw copaw daemon version      # 查看 CoPaw 版本

环境变量说明

CoPaw 基础配置

变量	默认值	说明
`COPAW_WORKING_DIR`	`/data/copaw`	工作目录（固定不可修改）
`COPAW_CONFIG_FILE`	`config.json`	配置文件名
`COPAW_HEARTBEAT_FILE`	`HEARTBEAT.md`	心跳问题文件名
`COPAW_JOBS_FILE`	`jobs.json`	定时任务文件名
`COPAW_CHATS_FILE`	`chats.json`	会话列表文件名
`COPAW_LOG_LEVEL`	`info`	日志级别（debug/info/warning/error/critical）
`COPAW_MEMORY_COMPACT_THRESHOLD`	`100000`	触发记忆压缩的字符阈值
`COPAW_MEMORY_COMPACT_KEEP_RECENT`	`3`	压缩后保留的最近消息数
`COPAW_MEMORY_COMPACT_RATIO`	`0.7`	触发压缩的阈值比例（相对于上下文窗口大小）
`COPAW_AUTO_INIT`	`true`	是否自动初始化

Embedding 服务配置

变量	默认值	说明
`EMBEDDING_API_KEY`	（必填）	Embedding 服务的 API Key
`EMBEDDING_BASE_URL`	`https://dashscope.aliyuncs.com/compatible-mode/v1`	Embedding 服务地址
`EMBEDDING_MODEL_NAME`	`text-embedding-v4`	Embedding 模型名称
`EMBEDDING_DIMENSIONS`	`1024`	向量维度
`EMBEDDING_CACHE_ENABLED`	`true`	是否启用 Embedding 缓存
`FTS_ENABLED`	`true`	是否启用 BM25 全文检索
`MEMORY_STORE_BACKEND`	`auto`	记忆存储后端（auto/local/chroma/sqlite）

模型提供商配置

选择一个或多个提供商配置 API Key：

变量	说明
`MODELSCOPE_API_KEY`	ModelScope（魔搭）API Key
`DASHSCOPE_API_KEY`	DashScope（灵积）API Key
`OPENAI_API_KEY`	OpenAI 兼容接口 API Key
`OPENAI_BASE_URL`	OpenAI 兼容接口地址
`OPENAI_MODEL_NAME`	OpenAI 兼容模型名称
`ANTHROPIC_API_KEY`	Anthropic API Key（v0.0.5+ 新增）

Web 服务配置

变量	默认值	说明
`COPAW_CORS_ORIGINS`	`*`	CORS 允许的来源（v0.0.4+ 新增）
`COPAW_RUNNING_IN_CONTAINER`	`true`	是否在容器内运行（自动检测，通常无需手动设置）

数据持久化

⚠️ 重要提示：本项目的 copaw-data 存储卷与 CoPaw 官方镜像的存储卷不能通用，原因是文件权限设置不一致。官方镜像可能使用不同的用户权限运行，直接挂载可能导致权限问题。

本项目使用 Docker 数据卷 copaw-data 持久化以下内容：

.runtime/ - 敏感配置目录（providers.json、envs.json）
config.json - 主配置文件
SOUL.md - 核心身份与行为原则
AGENTS.md - 详细的工作流程、规则和指南
MEMORY.md - 长期记忆
PROFILE.md - 身份和用户画像
HEARTBEAT.md - 心跳配置
jobs.json - 定时任务列表
chats.json - 会话列表
active_skills/ - 当前激活的技能
customized_skills/ - 用户自定义技能
memory/ - Agent 记忆文件

容器重启后，所有数据都会保留。

多模态消息支持

各频道对不同消息类型的支持情况：

频道	接收文本	接收图片	接收视频	接收音频	接收文件	发送文本	发送图片	发送视频	发送音频	发送文件
钉钉	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
飞书	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Discord	✓	✓	✓	✓	✓	✓	🚧	🚧	🚧	🚧
iMessage	✓	✓ (v0.0.5+)	✓ (v0.0.5+)	✓ (v0.0.5+)	✗	✓	✓ (v0.0.5+)	✓ (v0.0.5+)	✓ (v0.0.5+)	✗
QQ	✓	🚧	🚧	🚧	🚧	✓	🚧	🚧	🚧	🚧
Telegram	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Twilio Voice	✓	✗	✗	✓	✗	✓	✗	✗	✓	✗

✓ = 已支持；🚧 = 施工中；✗ = 不支持

端口说明

⚠️ 再次提醒：请勿将端口暴露到公网！CoPaw WebUI 没有任何身份验证机制。

容器端口	主机端口	说明
`8088`	`127.0.0.1:8088`	CoPaw Web 服务端口（v0.0.5+ 默认绑定 127.0.0.1）

如需修改主机端口，编辑 docker-compose.yml：

ports:
  - "9000:8088"  # 使用 9000 端口访问
  # 或 v0.0.5+ 允许外部访问（不推荐）
  # - "0.0.0.0:8088:8088"

安全更新：v0.0.5 起，默认端口绑定改为 127.0.0.1 以提高安全性，仅允许本地访问。

网络配置

默认使用 copaw-network 桥接网络。如需连接其他容器，可以：

# 在 docker-compose.yml 中添加外部网络
networks:
  copaw-network:
    name: your-existing-network
    external: true

故障排除

1. 容器无法启动

检查日志：

docker compose logs copaw

2. 健康检查失败

检查服务是否正常运行：

docker compose ps
curl http://localhost:8088/

3. 数据丢失

数据存储在 Docker 卷中，除非手动删除卷，否则不会丢失。

检查卷状态：

docker volume ls | grep copaw

4. API Key 无效

确保 .env 文件中的 API Key 正确，并重启服务：

docker compose restart

镜像信息

预构建镜像

镜像地址: ghcr.io/log-z/copaw-docker:latest
拉取命令: docker pull ghcr.io/log-z/copaw-docker:latest
更新频率: 随 CoPaw 官方版本更新

自行构建

基础镜像: python:3.12-slim
Python 版本: 3.12
Node.js 版本: 20.x LTS（用于 MCP 功能）
工作目录: /data/copaw
运行用户: copaw（非 root）

新功能支持

v0.0.5 新增功能

Twilio Voice 频道 - 语音频道集成，支持 Cloudflare tunnel
Telegram CLI 配置 - 交互式命令行工具配置 Telegram 频道
Anthropic 提供商 - 新增内置模型提供商
DeepSeek Reasoner 支持 - 保留 reasoning_content 用于推理模式
版本更新通知 - 自动版本检测与更新提示
Daemon 模式 - copaw daemon CLI 管理后台服务
Agent 中断 API - interrupt() 方法取消活跃回复任务
MCP 客户端自动恢复 - 自动重连关闭的 MCP 会话
iMessage 附件支持 - 支持发送图片、音频、视频文件
消息过滤配置 - 每频道可隐藏工具执行步骤 (filter_tool_messages) 和思考内容 (filter_thinking)
Docker 配置持久化 - providers.json 和 envs.json 自动迁移到 SECRET_DIR
频道文档链接 - 每个频道卡片上的快速 "Doc" 按钮
Skills Hub 导入 - 支持从社区平台导入技能

MCP (模型上下文协议)

CoPaw 0.0.3+ 支持 MCP（Model Context Protocol），可以连接外部 MCP 服务器扩展能力。

前置要求: 无额外要求（镜像已包含 Node.js 20.x LTS）

配置示例（通过控制台添加）:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

管理方式:

控制台 → 智能体 → MCP → 创建客户端
支持启用/禁用/编辑/删除 MCP 客户端

本地模型支持

CoPaw 支持本地运行模型（无需 API Key），但需要额外依赖：

后端	说明	额外依赖
llama.cpp	跨平台	`pip install 'copaw[llamacpp]'`
MLX	Apple Silicon 优化	`pip install 'copaw[mlx]'`
Ollama	Ollama 守护进程	`pip install 'copaw[ollama]'` + Ollama 服务

注意: Docker 镜像默认不包含这些依赖。如需使用，需要自定义构建镜像或在容器中手动安装。

控制台新功能

技能管理增强:

从 Skill Hub 导入技能（通过 URL）
直接在控制台创建自定义技能

工作区功能:

上传/下载工作区（.zip 格式）
支持工作区备份和迁移

运行配置:

可修改最大迭代次数 (max_iters)
可修改最大输入长度 (max_input_length)

控制台功能

服务启动后访问 http://localhost:8088/ 进入控制台，包含以下功能模块：

组	功能	说明
聊天	聊天	和 CoPaw 对话、管理会话
控制	频道	启用/禁用频道、填入凭据、快速文档链接（v0.0.5+）
控制	会话	筛选、重命名、删除会话
控制	定时任务	创建/编辑/删除任务、立即执行
智能体	工作区	编辑人设文件、查看记忆、上传/下载
智能体	技能	启用/禁用/创建/导入/删除技能
智能体	MCP	启用/禁用/创建/删除 MCP 客户端
智能体	运行配置	修改最大迭代次数和最大输入长度
设置	模型	配置提供商（含自定义提供商）、管理本地/Ollama 模型、选择模型
设置	环境变量	添加/编辑/删除环境变量

Skills Hub 导入（v0.0.5+）：支持从社区平台导入技能

https://skills.sh/...
https://clawhub.ai/...
https://skillsmp.com/...
https://github.com/...

License

本项目基于 CoPaw 的官方部署方案构建。CoPaw 由 AgentScope 团队开发，采用 Apache License 2.0 开源许可。

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Dockerfile-root		Dockerfile-root
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

CoPaw Docker 部署方案

关于 CoPaw

⚠️ 安全警告 ⚠️

快速开始

前置要求

使用方式选择

方式一：快速体验

方式二：使用 Docker Compose（推荐✨）

1. （可选）配置环境变量

2. 拉取并启动服务

3. 查看日志

4. 访问控制台

方式三：自行构建镜像

1. （可选）配置环境变量

2. 修改 docker-compose.yml

3. 构建镜像

4. 启动服务、查看日志、访问控制台

项目结构

数据卷结构（运行时生成）

常用命令

容器管理

数据管理

CoPaw 命令（在容器内执行）

环境变量说明

CoPaw 基础配置

Embedding 服务配置

模型提供商配置

Web 服务配置

数据持久化

多模态消息支持

端口说明

网络配置

故障排除

1. 容器无法启动

2. 健康检查失败

3. 数据丢失

4. API Key 无效

镜像信息

预构建镜像

自行构建

新功能支持

v0.0.5 新增功能

MCP (模型上下文协议)

本地模型支持

控制台新功能

控制台功能

相关链接

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages