CoPaw 本地部署與使用全指南

一、前置準(zhǔn)備

系統(tǒng)要求：Windows 10+/macOS 12+/Linux（64 位），建議4GB 以上內(nèi)存，至少500MB 可用磁盤(pán)空間

工具要求：Windows 需用 PowerShell（勿用 CMD），macOS/Linux 用終端；Docker 部署需先安裝 Docker

網(wǎng)絡(luò)：穩(wěn)定聯(lián)網(wǎng)（用于下載依賴、獲取 API 密鑰）

Python：pip 安裝方式需 Python 3.10-3.13；一鍵安裝腳本會(huì)自動(dòng)安裝適配版本

二、三種安裝方式（任選其一）

方式 1：一鍵安裝（推薦，自動(dòng)處理所有依賴）

Windows（PowerShell）：以管理員身份打開(kāi) PowerShell，執(zhí)行

powershell

irm https://copaw.agentscope.io/install.ps1 | iex

安裝完成后需重啟 PowerShell使環(huán)境變量生效

macOS/Linux（終端）：執(zhí)行

bash

運(yùn)行

curl -fsSL https://copaw.agentscope.io/install.sh | bash

安裝完成后執(zhí)行source ~/.zshrc（zsh）或source ~/.bashrc（bash）刷新環(huán)境

擴(kuò)展安裝（支持本地模型）：

Windows：irm https://copaw.agentscope.io/install.ps1 | iex -ArgumentList "--extras ollama,llamacpp"

macOS/Linux：curl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama,llamacpp

方式 2：pip 安裝（適合已有 Python 環(huán)境的用戶）

確保 Python 版本符合要求，執(zhí)行

bash

運(yùn)行

pip install copaw

若需指定版本：pip install copaw==0.0.4（最新穩(wěn)定版）

方式 3：Docker 部署（適合追求隔離環(huán)境的用戶）

安裝 Docker 并啟動(dòng)服務(wù)

拉取鏡像：docker pull agentscope/copaw:latest

運(yùn)行容器：

bash

運(yùn)行

docker run -p 8088:8088 -v copaw-data:/app/working agentscope/copaw:latest

（-v參數(shù)用于持久化數(shù)據(jù)，避免容器刪除后配置丟失）

三、初始化配置

基礎(chǔ)初始化（推薦新手，快速生成默認(rèn)配置）

bash

運(yùn)行

copaw init --defaults

閱讀安全說(shuō)明后輸入yes確認(rèn)，默認(rèn)配置文件會(huì)生成在~/.copaw/config.json

交互式初始化（適合高級(jí)用戶，自定義配置）

bash

運(yùn)行

copaw init

按提示設(shè)置工作目錄、日志級(jí)別、默認(rèn)模型等參數(shù)

四、啟動(dòng)與訪問(wèn)服務(wù)

啟動(dòng) CoPaw 服務(wù)

bash

運(yùn)行

copaw app

服務(wù)默認(rèn)運(yùn)行在http://127.0.0.1:8088，日志會(huì)實(shí)時(shí)顯示在終端

訪問(wèn)網(wǎng)頁(yè)控制臺(tái)

打開(kāi)瀏覽器，輸入http://127.0.0.1:8088

首次訪問(wèn)會(huì)顯示歡迎頁(yè)面，包含基礎(chǔ)使用指南

Docker 部署啟動(dòng)：執(zhí)行方式 3 中的docker run命令后，直接訪問(wèn)上述地址即可

五、核心使用流程

1. 基礎(chǔ)聊天交互

在網(wǎng)頁(yè)控制臺(tái)的 “Chat” 頁(yè)面，直接輸入問(wèn)題與 CoPaw 對(duì)話

支持 markdown 格式、代碼塊、文件上傳（PDF/Office 文檔）處理

2. 連接聊天應(yīng)用（釘釘 / 飛書(shū) / QQ 等）

在網(wǎng)頁(yè)控制臺(tái)進(jìn)入 “Connections” 頁(yè)面

選擇要連接的應(yīng)用（如飛書(shū)），按提示獲取并輸入 API 密鑰 / 機(jī)器人令牌

保存配置后，即可通過(guò)該應(yīng)用與 CoPaw 對(duì)話，無(wú)需打開(kāi)瀏覽器

3. 技能管理與定時(shí)任務(wù)

“Skills” 頁(yè)面：?jiǎn)⒂?/ 禁用內(nèi)置技能（如 PDF 處理、新聞?wù)⒍〞r(shí)任務(wù)）

“Schedules” 頁(yè)面：配置定時(shí)任務(wù)（如每日早 8 點(diǎn)推送天氣、每周五整理文件）

4. 本地模型使用（擴(kuò)展安裝后）

下載模型：copaw models download qwen/qwen3-4b-gguf（示例：通義千問(wèn) 3-4B）

在控制臺(tái) “Models” 頁(yè)面切換為本地模型，實(shí)現(xiàn)數(shù)據(jù)本地處理

六、關(guān)鍵命令速查

表格

功能 命令

初始化（默認(rèn)配置） copaw init --defaults

啟動(dòng)服務(wù) copaw app

查看幫助 copaw --help

下載模型 copaw models download [模型名稱]

升級(jí) CoPaw copaw upgrade（一鍵安裝）/ pip install --upgrade copaw（pip 安裝）

查看版本 copaw --version

七、常見(jiàn)問(wèn)題與解決方法

端口占用：若 8088 端口被占用，啟動(dòng)時(shí)指定端口：copaw app --port 8089

初始化失?。簞h除~/.copaw目錄后重新執(zhí)行copaw init --defaults

依賴缺失：一鍵安裝方式重新運(yùn)行安裝腳本；pip 方式執(zhí)行pip install --force-reinstall copaw

本地模型無(wú)法運(yùn)行：確保已安裝 ollama/llamacpp 擴(kuò)展，模型文件完整

聊天應(yīng)用連接失?。簷z查 API 密鑰 / 令牌有效性，確保網(wǎng)絡(luò)可訪問(wèn)對(duì)應(yīng)應(yīng)用服務(wù)器

八、安全與隱私提示

CoPaw 本地部署時(shí)，所有數(shù)據(jù)均存儲(chǔ)在本地，不經(jīng)過(guò)第三方服務(wù)器

配置文件（~/.copaw/config.json）包含 API 密鑰等敏感信息，切勿分享給他人

定期通過(guò)copaw upgrade更新版本，修復(fù)安全漏洞

九、完整流程總結(jié)

選擇安裝方式并執(zhí)行對(duì)應(yīng)命令

運(yùn)行copaw init --defaults初始化

執(zhí)行copaw app啟動(dòng)服務(wù)

瀏覽器訪問(wèn)http://127.0.0.1:8088進(jìn)入控制臺(tái)

配置聊天應(yīng)用連接（可選）

開(kāi)始使用 CoPaw 的各項(xiàng)功能

本資訊來(lái)自互聯(lián)網(wǎng)，如有侵權(quán)強(qiáng)聯(lián)系刪除！