CoPaw-Deploy 安装手册

本文档面向 AI Agent / CC 执行。阅读后可直接调用以下命令完成一键安装，无需人工干预。

1. 前提条件

依赖	macOS Apple Silicon	macOS Intel	Ubuntu 24.04	Windows 10/11
Python 3.10+	✅ 系统自带或官网安装	✅ 系统自带或官网安装	✅ 系统自带	✅ python.org 安装
git	✅ Xcode CLT	✅ Xcode CLT	✅ apt 自带	✅ git-scm.com
curl	✅ 系统自带	✅ 系统自带	✅ 系统自带	✅ Win10 1803+ 自带
VC++ 2015-2022 Redistributable	❌ 不需要	❌ 不需要	❌ 不需要	⚠️ 必装（ujson DLL 依赖）
Docker	❌ 不需要	❌ 不需要	❌ 不需要	❌ 不需要
Homebrew	❌ 不需要	❌ 不需要	❌ 不需要	❌ 不需要

网络要求：

GitHub（用于 clone 仓库 + 下载 Release 包）
gbrain Release 包 85MB（含 node_modules，下载后无需联网）
如 GitHub 不通，可配置代理：export https_proxy=http://127.0.0.1:7897

1.1 Windows 平台特别说明

首次部署 Win11 必读：实测纯净 Win11 安装 CoPaw 需要 4 个前置依赖，缺一不可。

安装顺序（管理员 PowerShell）：

# 1. Python 3.10+（推荐 3.12.10）
# 国内镜像：https://mirrors.huaweicloud.com/python/3.12.10/python-3.12.10-amd64.exe
# 或 winget：
winget install --id Python.Python.3.12 -e --accept-package-agreements --accept-source-agreements

# 2. Git for Windows
# 国内镜像：https://cdn.npmmirror.com/binaries/git-for-windows/v2.45.2.windows.1/Git-2.45.2-64-bit.exe
# 或 winget：
winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements

# 3. VC++ 2015-2022 Redistributable（关键！否则 ujson 报 DLL 错误）
# 官方下载：https://aka.ms/vs/17/release/vc_redist.x64.exe
# 或 winget：
winget install --id Microsoft.VCRedist.2015+.x64 -e --accept-package-agreements --accept-source-agreements

# 4. pip 国内镜像（可选但强烈推荐，否则 pip install 268 包要 30+ 分钟）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

验证前置条件：

python --version    # 应显示 Python 3.10+
git --version       # 应显示 git 2.x
where msvcp140.dll  # 应显示 C:\Windows\System32\msvcp140.dll
pip config list     # 应显示清华源 URL

常见 Windows 部署问题：

现象	原因	解决
`ImportError: DLL load failed while importing ujson`	缺 VC++ Redistributable	装 `vc_redist.x64.exe`
`bootstrap.ps1` 解析报错 `TerminatorExpectedAtEndOfString`	PowerShell 5.x 读无 BOM UTF-8 ps1 乱码	已修复（仓库所有 ps1 已加 BOM）
`pip install` 极慢或超时	默认 PyPI 在中国大陆访问慢	配置清华镜像
`stdio MCP client requires non-empty command`	Windows 平台 MCP 配置畸形（偶发）	已修复（`copaw-import-seed.ps1` 末尾自动检测+修复）

1.5. ⚠️ 安装前必读：GBrain 参数准备

CC/Agent 执行安装前，必须先向用户收集以下参数，写入 ~/.copaw_PORT/.env 后再执行 bootstrap。 详细参数说明见底部章节 🤖 LLM / Embedding Provider 配置。

GBrain 需要两类模型：

类型	用途	关键点
Chat Model	dream 知识提炼 / synthesize / subagent 调度	推理能力强的模型
Embedding Model	向量化（语义搜索基础）	⚠️ 初始化后不可更换，维度固化

这两类可以用同一套 provider（一个 key）也可以各用一套。支持 openai / anthropic / ollama / google / voyage / dashscope / deepseek / zhipu 等。

典型方案（选一个填入 .env）

方案 A：纯云端，一套 key（openai / ARK 兼容）

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1   # 第三方兼容 API 改这里
GBRAIN_DEFAULT_MODEL=openai:gpt-4o
GBRAIN_THINK_MODEL=openai:gpt-4o
GBRAIN_SUBAGENT_MODEL=openai:gpt-4o-mini
GBRAIN_EMBEDDING_MODEL=openai:text-embedding-3-small
GBRAIN_EMBEDDING_DIMENSIONS=1536

方案 B：Chat + Embedding 各一套（常见组合）

ANTHROPIC_API_KEY=your-key
ANTHROPIC_BASE_URL=https://api.anthropic.com
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1
GBRAIN_DEFAULT_MODEL=anthropic:claude-sonnet-4-5
GBRAIN_THINK_MODEL=anthropic:claude-sonnet-4-5
GBRAIN_SUBAGENT_MODEL=anthropic:claude-haiku-4-5-20251001
GBRAIN_EMBEDDING_MODEL=openai:text-embedding-3-small
GBRAIN_EMBEDDING_DIMENSIONS=1536

方案 C：本地 Ollama（无需 API key，无需独立 GPU）

# 前提：ollama serve 已运行 + 拉好模型
# ollama pull qwen3:8b && ollama pull qwen3-embedding:4b
OLLAMA_BASE_URL=http://localhost:11434/v1
GBRAIN_DEFAULT_MODEL=ollama:qwen3:8b
GBRAIN_THINK_MODEL=ollama:qwen3:8b
GBRAIN_SUBAGENT_MODEL=ollama:qwen3:4b
GBRAIN_EMBEDDING_MODEL=ollama:qwen3-embedding:4b
GBRAIN_EMBEDDING_DIMENSIONS=2560

方案 D：混合（Chat 云端 + Embedding 本地，推荐）

ANTHROPIC_API_KEY=your-key
ANTHROPIC_BASE_URL=https://api.anthropic.com
OLLAMA_BASE_URL=http://localhost:11434/v1
GBRAIN_DEFAULT_MODEL=anthropic:claude-sonnet-4-5
GBRAIN_THINK_MODEL=anthropic:claude-sonnet-4-5
GBRAIN_SUBAGENT_MODEL=anthropic:claude-haiku-4-5-20251001
GBRAIN_EMBEDDING_MODEL=ollama:nomic-embed-text
GBRAIN_EMBEDDING_DIMENSIONS=768

2. 一键安装（推荐）

macOS / Linux

# 方式 A：直接执行（自动 clone 仓库 + 部署）
curl -fsSL https://raw.githubusercontent.com/crazybin5848/CoPaw-Deploy/main/install.sh | bash -s -- --full-stack --port 8083

Windows（PowerShell）

irm https://raw.githubusercontent.com/crazybin5848/CoPaw-Deploy/main/install.ps1 | iex

3. 手动安装（Agent 执行版）

网络不稳定、或需要观察每步日志时，推荐手动逐步执行。

步骤 1：获取部署脚本

# 目标机执行（后台 clone，避免 SSH 超时）
nohup git clone --depth 1 https://github.com/crazybin5848/CoPaw-Deploy.git ~/copaw-deploy > /tmp/clone.log 2>&1 &
echo "PID=$!"
# 30 秒后查看结果
sleep 30 && cat /tmp/clone.log && ls ~/copaw-deploy/

步骤 2：运行 bootstrap

cd ~/copaw-deploy

# 标准全栈部署（PGLite 模式，无需 Docker）
nohup bash bootstrap.sh --full-stack --port 8083 > /tmp/bootstrap.log 2>&1 &
echo "PID=$!"

# 实时监控（另开 SSH 窗口）
tail -f /tmp/bootstrap.log

4. bootstrap.sh 参数说明

bash bootstrap.sh [选项]

选项:
  --full-stack          安装完整技术栈（CoPaw + GBrain + PGLite）
  --port PORT           CoPaw 监听端口（默认 8083）
  --config CONFIG_DIR   指定配置目录（默认按端口自动推导）
  --db pglite|pg        数据库模式（默认 pglite，个人推荐；pg 需要 Docker）
  --dry-run             只打印不执行，用于预检
  --force               强制重装（跳过检查点，从头来）
  --low-memory          内存 < 4GB 时跳过内存警告
  --enable-dream-cron   注册每日 dream cron（默认已开启）

示例:
  bash bootstrap.sh --full-stack --port 8083           # 标准安装
  bash bootstrap.sh --full-stack --port 8083 --force   # 全新重装
  bash bootstrap.sh --full-stack --port 8083 --dry-run # 预检

5. 部署流程说明（10 步 gbrain 链路 + 7 步主流程）

bootstrap 完整流程如下：

[1/7] 检查文件完整性
[2/7] 停止旧实例
[3/7] gbrain 全链路（含以下子步骤）：
      ├── 00-prereq          前置检查（OS、Python、磁盘、内存、端口）
      ├── 01-bun-gbrain      安装 bun + gbrain（从 Release 下载全量包）
      ├── 02-start-pg        PGLite 模式跳过；PG 模式启动 Docker 容器
      ├── 03-init-brain      gbrain init（初始化知识图谱数据库）
      ├── 04-register-source 注册 CoPaw memory source
      ├── 05-register-oauth  启动 gbrain serve + 获取 admin token
      ├── 06-inject-config   注入 gbrain Bearer token 到 CoPaw config.json
      ├── 06.5-apply-patch   应用 gbrain 补丁（gateway/cycle/synthesize 等）
      ├── 06.7-runtime-config 渲染 dream-cron 脚本 + 自动发现所有 CoPaw 实例 + 注册 cron
      ├── 06.8-install-worker 安装 minion worker systemd service（Linux，dream synthesize 阶段必需）
      └── 07-verify          健康检查（HTTP 200 验证）
[4/7] 安装 CoPaw（创建 venv + pip install wheel）
[5/7] 初始化配置（config.json + .env + PROFILE.md + channel 配置清空）
[5.5/7] 导入 agent + skills + pipelines（从 data/seed 内置的 16 个 agent + 11 个 pipeline）
[6/7] 启动 CoPaw（launchd / systemd / 直接后台）
[7/7] 健康检查（/api/agents 200 OK）

检查点机制：每步成功后写入 ~/.copaw_PORT/.checkpoint.json。中断后可直接重跑，已完成步骤自动跳过。

6. 端口与配置目录映射

端口	配置目录	说明
8083	`~/.copaw_8083`	标准部署（推荐）
8084	`~/.copaw_8084`	备用实例
8085	`~/.copaw_dev_fork`	开发实例
8086	`~/.copaw_dev_fork_gray`	灰度实例
其他	`~/.copaw_PORT`	自动推导

7. 安装完成后

验证服务

# CoPaw 健康检查
curl http://localhost:8083/api/agents

# GBrain 健康检查
curl http://localhost:3131/health

# 运行 verify 脚本（8 项完整检查）
bash ~/copaw-deploy/darwin/apple/copaw-verify.sh --port 8083
# Linux:
bash ~/copaw-deploy/linux/ubuntu/copaw-verify.sh --port 8083

访问 Web 控制台

http://localhost:8083

配置 API Key

安装完成后飞书/钉钉等渠道均已禁用（防止继承源机器账号）。

手动填写 API Keys（首次必须）：

# 编辑 .env 文件
nano ~/.copaw_8083/.env

# 填写以下内容：
ARK_API_KEY=ark-YOUR_KEY_HERE
OPENAI_API_KEY=ark-YOUR_KEY_HERE
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
ANTHROPIC_API_KEY=ark-YOUR_KEY_HERE
ANTHROPIC_BASE_URL=https://ark.cn-beijing.volces.com/api/v1

填写后重启 CoPaw：

# macOS
bash ~/copaw-deploy/darwin/apple/copaw-restart.sh --port 8083

# Linux
bash ~/copaw-deploy/linux/ubuntu/copaw-restart.sh --port 8083

8. 服务管理

macOS

DEPLOY=~/copaw-deploy/darwin/apple

bash $DEPLOY/copaw-start.sh   --port 8083   # 启动
bash $DEPLOY/copaw-stop.sh    --port 8083   # 停止
bash $DEPLOY/copaw-restart.sh --port 8083   # 重启
bash $DEPLOY/copaw-status.sh  --port 8083   # 状态
bash $DEPLOY/copaw-logs.sh    --port 8083 -f  # 实时日志

Linux

DEPLOY=~/copaw-deploy/linux/ubuntu

bash $DEPLOY/copaw-start.sh   --port 8083
bash $DEPLOY/copaw-stop.sh    --port 8083
bash $DEPLOY/copaw-status.sh  --port 8083
bash $DEPLOY/copaw-logs.sh    --port 8083 -f

Linux 平台额外有两个 systemd user service（bootstrap 自动安装）：

# gbrain HTTP server（端口 3131 或按 --port 指定）
systemctl --user status gbrain.service
systemctl --user restart gbrain.service
journalctl --user -u gbrain.service -f

# minion worker（消费 dream cycle 的 subagent 任务，写知识页面）
systemctl --user status gbrain-worker.service
systemctl --user restart gbrain-worker.service
tail -f ~/.gbrain_8083/gbrain-worker.log

注意：没有 worker，dream cycle 会卡在 synthesize 阶段（参见下方 FAQ）。

Windows（PowerShell）

$D = "$HOME\copaw-deploy\windows"

& "$D\copaw-start.ps1"   -Port 8083
& "$D\copaw-stop.ps1"    -Port 8083
& "$D\copaw-status.ps1"  -Port 8083
& "$D\copaw-logs.ps1"    -Port 8083 -Follow

9. 清理与重装

cd ~/copaw-deploy

# soft：只停服务，保留配置和数据
bash cleanup.sh --level soft --port 8083

# normal：停服务 + 删配置目录 + 删 venv（保留 PGLite 数据）
bash cleanup.sh --level normal --port 8083

# nuke：全删（含 PGLite 数据）
bash cleanup.sh --level nuke --port 8083

# 重装（nuke 后重新部署）
bash cleanup.sh --level nuke --port 8083 && \
bash bootstrap.sh --full-stack --port 8083

10. Dream Cron（每日知识整理）

安装时已自动配置，每天 12:00 运行。

前置依赖：dream cycle 的 synthesize 阶段将"写知识页面"任务投递到 minion_jobs 表，由 gbrain-worker.service（Linux systemd）异步执行。没有 worker，dream 会永久卡住。 步骤 06.8-install-worker 已自动安装。验证：systemctl --user status gbrain-worker.service。

脚本位置：~/.gbrain_8083/runtime-config/dream-multi-source.sh

功能：

自动发现机器上所有 CoPaw 实例（~/.copaw_NNNN/ 目录）
每个实例执行：git commit → sync → extract → embed
完整 dream cycle（17 个 phase：synthesize/patterns/consolidate 等）
日志：~/.gbrain_8083/dream-multi-source.log

手动触发：

bash ~/.gbrain_8083/runtime-config/dream-multi-source.sh

查看日志：

tail -100 ~/.gbrain_8083/dream-multi-source.log

10.1 Dream Cycle 模型配置（性能/成本优化）

dream cycle 涉及三类 LLM 调用，可独立配置（写到 gbrain DB config 表）：

配置 key	用途	推荐模型	说明
`models.dream.synthesize`	主流程（写知识页面）	sonnet 或 haiku	影响产出质量，多轮 tool loop
`models.dream.synthesize_subagent`	subagent minion job	haiku	写一个个 wiki page，量大但单次任务简单
`models.dream.synthesize_verdict`	判断 transcript 是否值得处理	haiku	二分类轻量任务

⚠️ synthesize_subagent 是 PATCH-synthesize-subagent-model 引入的新 key（gbrain v0.41 原版 subagent 直接复用 synthesize 主模型）。未设置时自动 fallback 到 synthesize 的值（向后兼容）。

设置示例：

docker exec gbrain-pg env PGPASSWORD=$PG_PASS psql -U gbrain -d gbrain -p 5433 \
  -c "INSERT INTO config (key, value) VALUES
        ('models.dream.synthesize',          'anthropic:claude-sonnet-4-6'),
        ('models.dream.synthesize_subagent', 'anthropic:claude-haiku-4-5-20251001'),
        ('models.dream.synthesize_verdict',  'anthropic:claude-haiku-4-5-20251001')
      ON CONFLICT (key) DO UPDATE SET value=EXCLUDED.value;"

成本对比（每月 30 次 cron × 9 个 transcript / 次）：

全 sonnet：约 $24/月
主流程 sonnet + subagent/verdict 都用 haiku：约 $4/月（6 倍便宜）
全 haiku：约 $2/月（12 倍便宜，质量稍降但够用）

worker 并发：06.8-install-worker.sh 默认配置 --concurrency 3，配合 haiku 让 dream cycle 总耗时降低 6-12 倍。

11. 常见问题

Q: gbrain 下载超慢或失败

A：Release 包 85MB，首次下载需要时间。如果 GitHub 网络不通：

# 方式 1：配置代理
export https_proxy=http://127.0.0.1:7897
bash bootstrap.sh --full-stack --port 8083

# 方式 2：用 --resolve 绕过 DNS（适合 Tailscale 网络）
# 脚本内已内置自动检测代理，无需手动设置

Q: "bun: not found" 或 gbrain 安装失败

A：bun 会自动安装到 ~/.bun/bin/，check PATH：

export PATH="$HOME/.bun/bin:$PATH"
bun --version
gbrain --version

Q: 端口冲突

A：

# 查看占用
lsof -iTCP:8083 -sTCP:LISTEN     # macOS
ss -tlnp | grep 8083              # Linux

# 停止旧进程
bash ~/copaw-deploy/cleanup.sh --level soft --port 8083

Q: gbrain dream cycle 被 lock 阻塞

A：kill gbrain 时 lock 会自动清除（cleanup 脚本已处理）。如果手动 kill：

rm -f ~/.gbrain_8083/.gbrain/cycle.lock

Q: dream cycle 一直卡在 "Synthesizing source=xxx" 不出来

A：synthesize 阶段将"写知识页面"任务委托给 minion worker 异步执行。如果 worker 没在跑，dream 会永久阻塞等待。

# 1. 检查 worker 是否运行
systemctl --user status gbrain-worker.service

# 2. 如果没跑，启动它
systemctl --user start gbrain-worker.service

# 3. 检查积压的 subagent job 数量
docker exec gbrain-pg-8083 env PGPASSWORD=xxx psql -U gbrain -d gbrain \
  -c "SELECT status, COUNT(*) FROM minion_jobs GROUP BY status;"

# 4. 如果有 dead/failed 状态的 job，查看失败原因
docker exec gbrain-pg-8083 env PGPASSWORD=xxx psql -U gbrain -d gbrain \
  -c "SELECT id, LEFT(error_text, 200) FROM minion_jobs WHERE status='dead' ORDER BY id DESC LIMIT 5;"

常见原因：

worker 未安装（首次部署时漏了 06.8-install-worker） → 手动执行该步骤
旧 job 用了错误的 model（如 openai:claude-xxx 而非 anthropic:claude-xxx）→ 清理后重跑
worker 进程被 OOM kill → 检查内存，重启 service

Q: 安装中断后如何续跑

A：直接重跑 bootstrap，已完成步骤自动跳过：

bash ~/copaw-deploy/bootstrap.sh --full-stack --port 8083

如需强制从头来：

bash ~/copaw-deploy/bootstrap.sh --full-stack --port 8083 --force

Q: 部署完成后只有 default agent，没有其他智能体和 pipeline

A：bootstrap 步骤 [5.5/7] 会从仓库内置的 data/seed/ 导入 16 个 agent + 11 个 pipeline。如果没导入：

检查仓库完整性：ls ~/copaw-deploy/data/seed/workspaces/ 应有 16 个子目录
手动补跑导入：

cd ~/copaw-deploy
bash darwin/apple/copaw-import-seed.sh \
  --config ~/.copaw_8083 --port 8083 \
  --source data/seed

重启后验证：curl http://localhost:8083/api/agents | python3 -m json.tool | grep '"id"'

如需使用自定义 seed（如从另一台机器导出），设置环境变量 COPAW_SEED_SOURCE=/path/to/export 再跑 bootstrap。

12. 升级已有环境

全量重装会丢失数据（除 cleanup.sh --level soft）。优先用增量升级：根据改动的部分挑选对应脚本。

12.1 CoPaw wheel 包更新（`packages/qwenpaw-x.y.z.whl`）

CoPaw 升级最常见的场景。本仓库 packages/ 下的 wheel 是定制 fork（含 gbrain 集成、飞书、browser 控制等），不是 pypi 官方版。

cd ~/copaw-deploy && git pull                       # 1. 拉最新 wheel + 脚本
bash linux/ubuntu/copaw-stop.sh --port 8083        # 2. 停服务（macOS/Windows 改对应路径）
bash linux/ubuntu/copaw-backup.sh --port 8083      # 3. 备份配置（可选但推荐）

# 4. 强制重装 wheel（保留 venv，只升级 copaw 包）
source ~/.copaw_venv_8083/bin/activate
pip install --force-reinstall ~/copaw-deploy/packages/qwenpaw-*.whl

# 5. 重启
bash linux/ubuntu/copaw-start.sh --port 8083

⚠️ linux/ubuntu/copaw-upgrade.sh 脚本是从 pypi 拉官方上游 copaw（非 fork 版），如果你跑的是 CoPaw-Deploy 定制版，不要用它，按上面的步骤手动重装本地 wheel。

12.2 gbrain 源码补丁更新（`common/patches/gbrain/*.ts`）

今天打的 PATCH-title-toLowerCase / PATCH-strip-provider-prefix 等就是这种场景。改了 *.ts 补丁后：

cd ~/copaw-deploy && git pull                                 # 拉最新补丁
bash linux/ubuntu/gbrain-patch.sh --port 8083                 # 重新应用 7 个 .ts 补丁
systemctl --user restart gbrain.service                       # 重启 gbrain HTTP 让代码生效
systemctl --user restart gbrain-worker.service                # worker 同样要重启（dream subagent 也走同份代码）

12.3 dream cron / runtime-config 更新

common/runtime-config/dream-multi-source.sh.template 或 sessions-to-transcripts.py 改了：

cd ~/copaw-deploy && git pull
bash linux/ubuntu/gbrain/06.7-runtime-config.sh --force        # --force 强制重新渲染

渲染产物在 $GBRAIN_HOME/runtime-config/，不会动 cron 注册。

12.4 minion worker service 更新

common/runtime-config/gbrain-worker.service.template 改了：

cd ~/copaw-deploy && git pull
bash linux/ubuntu/gbrain/06.8-install-worker.sh --force         # 重新渲染 + reload + restart

12.5 gbrain 自身版本升级（v0.41 → v0.42）

复杂度最高，因为补丁可能与新版上游冲突。建议步骤：

cd ~/copaw-deploy && git pull                                  # 拉最新 release tag

# 1. 备份当前 gbrain 数据库
docker exec gbrain-pg-8083 pg_dump -U gbrain gbrain | gzip > ~/gbrain_backup_$(date +%Y%m%d).sql.gz

# 2. 重新下载 gbrain 全量包（覆盖 ~/gbrain）
bash linux/ubuntu/gbrain/01-install-bun-gbrain.sh --force

# 3. 重新应用全部补丁（如果新版 gbrain 与补丁冲突会报错，需手动调整）
bash linux/ubuntu/gbrain-patch.sh --port 8083

# 4. 重启所有 gbrain 服务
systemctl --user restart gbrain.service gbrain-worker.service

升级前务必先在测试机验证补丁兼容性。如果遇到 *.ts patch 应用失败，可能上游已修复同类问题，对比 common/patches/gbrain/*.ts 与 ~/gbrain/src/core/*.ts 决定是否保留补丁。

12.6 GBrain 多用户凭据配置（v1.1.11.post2+ 必读）

如果 CoPaw 服务多个飞书用户，每个用户需要独立的 GBrain OAuth 凭据：

# 1. 复制凭据模板
cp ~/copaw-deploy/data/user_credentials.template.json \
   ~/.copaw/user_credentials.json

# 2. 为每个用户注册 OAuth client
gbrain auth register-client --source "user-<USER_NAME>"
# 或：
curl -X POST http://localhost:3131/api/v1/auth/register-client \
  -H "Content-Type: application/json" \
  -d '{"source_id": "user-<USER_NAME>"}'

# 3. 编辑 ~/.copaw/user_credentials.json，填入 client_id/secret 和 飞书 open_id

# 4. 重启 CoPaw（无需重启 gbrain）
copaw-dev --port 8083 restart

详见 docs/GBRAIN_USER_CREDENTIALS.md

⚠️ 重要: user_credentials.json 含敏感凭据，绝对不要提交到 git！只有模板文件 user_credentials.template.json 可以提交。

12.7 bootstrap.sh / 子脚本本身更新

cd ~/copaw-deploy && git pull
# 下次跑 bootstrap.sh 自动用新版（已部署机器一般不需要重跑 bootstrap）

12.7 升级决策速查

改了什么	用什么命令
`packages/*.whl`	§12.1 重装 wheel
`common/patches/gbrain/*.ts`	§12.2 `gbrain-patch.sh`
`common/runtime-config/.template` 或 `.py`	§12.3 `06.7-runtime-config.sh --force`
`common/runtime-config/gbrain-worker.service.template`	§12.4 `06.8-install-worker.sh --force`
`common/scripts/gbrain/*.py`（dream cron 调的辅助脚本）	无需重跑（cron 直接读最新文件）
gbrain 大版本号变了	§12.5 全流程
新增/修改飞书用户	§12.6 配置 user_credentials.json + 重启 CoPaw
`bootstrap.sh` 或子脚本	§12.7 仅 git pull

12.8 升级失败回退

# CoPaw wheel 回退（用上一次备份）
ls ~/.copaw_8083_backups/                                 # 找最近备份
pip install --force-reinstall <旧版 wheel 路径>
bash linux/ubuntu/copaw-restart.sh --port 8083

# gbrain 补丁回退（自动备份在 .patch_backups/）
ls ~/gbrain/.patch_backups/                                # 找最近一次备份目录
cp -r ~/gbrain/.patch_backups/<时间戳>/src/* ~/gbrain/src/
systemctl --user restart gbrain.service gbrain-worker.service

# gbrain 数据库回退
docker exec -i gbrain-pg-8083 psql -U gbrain -d gbrain < ~/gbrain_backup_<日期>.sql

13. Release 包说明

所有大文件通过 GitHub Releases 分发，安装时自动下载。

Release	包名	大小	说明
`v1.1.11.post2-fullstack`	`qwenpaw-1.1.11.post2-py3-none-any.whl`	11MB	CoPaw wheel（含前端 dist）
`v0.41.14.0-gbrain`	`gbrain-v0.41.14.0-full.tar.gz`	85MB	gbrain 全量包（含 node_modules）
`v0.41.14.0-gbrain`	`bun-darwin-aarch64.zip`	22MB	bun macOS ARM64 离线包

wheel 包含本地增强代码（gbrain 集成、飞书频道、browser 控制等），非官方 qwenpaw。

14. 目录结构

CoPaw-Deploy/
├── bootstrap.sh          # 主入口（macOS/Linux）
├── bootstrap.ps1         # 主入口（Windows）
├── cleanup.sh            # 清理脚本（soft/normal/nuke）
├── install.sh            # 一行安装入口（curl | bash）
├── install.ps1           # 一行安装入口（Windows）
├── packages/
│   └── qwenpaw-1.1.11.post2-py3-none-any.whl  # CoPaw wheel（11MB）
├── common/
│   ├── patches/gbrain/   # gbrain 源码补丁（7 个 .ts + PATCH 文档）
│   ├── scripts/gbrain/   # dream cycle 辅助 Python 脚本（compensate/inbox/probe）
│   └── runtime-config/   # dream cron 脚本模板
│       ├── dream-multi-source.sh.template
│       ├── gbrain-worker.service.template  # minion worker systemd unit 模板（Linux）
│       ├── sessions-to-transcripts.py
│       └── README.md
├── darwin/
│   ├── apple/            # macOS Apple Silicon 脚本
│   │   ├── gbrain/       # gbrain 10 步链路
│   │   │   ├── 00-prereq.sh
│   │   │   ├── 01-install-bun-gbrain.sh
│   │   │   ├── 02-start-pg.sh
│   │   │   ├── 03-init-brain.sh
│   │   │   ├── 04-register-source.sh
│   │   │   ├── 05-register-oauth.sh
│   │   │   ├── 06-inject-config.sh
│   │   │   ├── 06.5-apply-patch.sh
│   │   │   ├── 06.7-runtime-config.sh
│   │   │   ├── 06.8-install-worker.sh   # 安装 minion worker（Linux only，macOS 跳过）
│   │   │   ├── 07-verify.sh
│   │   │   └── cleanup-gbrain.sh
│   │   ├── copaw-install.sh
│   │   ├── copaw-configure.sh
│   │   ├── copaw-verify.sh
│   │   ├── copaw-start.sh / copaw-stop.sh / copaw-restart.sh
│   │   ├── copaw-status.sh / copaw-logs.sh
│   │   └── copaw-cleanup.sh
│   └── intel/            # macOS Intel（结构同 apple）
├── linux/
│   └── ubuntu/           # Ubuntu 24.04（结构同 darwin/apple）
└── windows/              # Windows 10/11（PowerShell）
    ├── gbrain/           # gbrain 7步链路（ps1）
    ├── copaw-install.ps1
    ├── copaw-configure.ps1
    ├── copaw-verify.ps1
    ├── copaw-start.ps1 / copaw-stop.ps1 / copaw-restart.ps1
    └── cleanup.ps1

🔧 开发者工作流

1. 修改源码后重新打包

# 从源码构建 wheel 并更新 deploy/packages/
bash deploy/build-wheel.sh

脚本做的事：

清理旧构建产物（dist/, build/, *.egg-info/）
用 python3 -m build --wheel 构建 wheel
删除 deploy/packages/ 下旧 wheel
复制新 wheel 到 deploy/packages/

前置条件：

Python 3.10+
pip install build（脚本会自动检查并安装）

2. 测试新 wheel

# 清理旧环境
bash deploy/copaw-dev.sh --port 8087 stop
rm -rf ~/.qwenpaw ~/.copaw_venv_8087

# 重新部署（使用新 wheel）
bash deploy/bootstrap.sh --port 8087

3. 导出 Agent 配置

# 使用 utils/copaw-export-agents.py 导出
python deploy/utils/copaw-export-agents.py

# 生成的 export 包放到 deploy/ 目录
mv /tmp/copaw_8086_export_*.tar.gz deploy/

🌍 多实例部署

同一台机器运行多个 CoPaw 实例（不同端口、不同配置）：

# 生产环境（8085）
bash bootstrap.sh --port 8085 --config ~/.copaw_prod

# 灰度环境（8086）
bash bootstrap.sh --port 8086 --config ~/.copaw_gray

# 测试环境（8084）
bash bootstrap.sh --port 8084 --config ~/.copaw_test

管理多实例：

# 查看所有实例状态
bash deploy/copaw-dev.sh --port 8085 status
bash deploy/copaw-dev.sh --port 8086 status
bash deploy/copaw-dev.sh --port 8084 status

# 停止所有实例
bash deploy/copaw-dev.sh --port 8085 stop
bash deploy/copaw-dev.sh --port 8086 stop
bash deploy/copaw-dev.sh --port 8084 stop

🔍 故障排查

问题 1：启动失败

症状：bootstrap.sh 显示"启动失败"

排查步骤：

# 1. 查看日志
bash deploy/copaw-dev.sh --port 8085 logs 100

# 2. 检查端口占用
lsof -i :8085

# 3. 检查 venv 是否正常
ls ~/.copaw_venv_8085/bin/copaw

# 4. 手动启动测试
source ~/.copaw_venv_8085/bin/activate
COPAW_WORKING_DIR=~/.copaw_dev_fork copaw app --port 8085

问题 2：Agent 未导入

症状：控制台只有 2 个 agent（default + 自动生成）

原因：bootstrap.sh 未找到 export 包

解决：

# 确认 export 包存在
ls deploy/copaw_8086_export_*.tar.gz

# 手动导入
bash deploy/darwin/apple/copaw-import.sh --config ~/.copaw_dev_fork deploy/copaw_8086_export_*.tar.gz

问题 3：wheel 版本不匹配

症状：安装时提示"本地 wheel 未找到，尝试 PyPI..."

原因：deploy/packages/ 下的 wheel 版本与脚本期望的版本不一致

解决：

# 检查 wheel 版本
ls deploy/packages/*.whl

# 检查脚本期望的版本
grep COPAW_VERSION deploy/darwin/apple/copaw-install.sh

# 重新构建 wheel
bash deploy/build-wheel.sh

问题 4：权限错误

症状：Permission denied

解决：

# 给脚本添加执行权限
chmod +x deploy/bootstrap.sh
chmod +x deploy/copaw-dev.sh
chmod +x deploy/build-wheel.sh
chmod +x deploy/darwin/apple/*.sh

问题 5：Agent 调用 gbrain MCP 报 401

症状：agent 日志显示 MCP gbrain: 401 Unauthorized 或 agent 说"找不到 gbrain MCP 工具"

原因：agent.json 里的 Bearer token 与 gbrain serve 实际生效的 token 不一致。可能由于：

seed-agent.json 历史上硬编码了开发环境的 token，新部署后 token 不匹配
重新部署 gbrain 时生成了新 token，但 agent.json 没同步更新
16 个 agent.json 中 token 占位符 (__GBRAIN_ACCESS_TOKEN__ / gbrain_PLACEHOLDER_TOKEN) 未被替换

修复：

# 1. 跑 token 修复脚本（从 config.json 读真实 token，批量替换 agent.json）
bash ~/copaw-deploy/darwin/apple/gbrain/06.9-fix-agent-gbrain-tokens.sh --force

# 2. 重启 copaw 加载新 agent.json
launchctl kickstart -k gui/$(id -u)/com.copaw.app.8083

# 3. 跑验证脚本（5 项检查）
bash ~/copaw-deploy/verify-gbrain-token-fix.sh

验证脚本检查项：

config.json 含真实 Bearer token（非占位符）
所有 agent.json 不含占位符
agent.json token 与 config.json 一致
gbrain /health 端点 200
用 token 调 MCP tools/list 200

问题 6：cleanup 后端口仍被占用

症状：cleanup nuke 后再次 bootstrap 报"端口已占用"

原因：旧脚本只 launchctl unload 没 launchctl remove，service 定义残留在 launchd 注册表，KeepAlive 配置反复拉起僵尸进程

已修复：从 96225a6 起，cleanup/uninstall 4 个脚本都增加了 launchctl remove 调用

手动清理残留（如果遇到旧版残留）：

# 查看 launchd 注册表中所有 copaw service
launchctl list | grep copaw

# 强制移除
launchctl remove com.copaw.app.8083
launchctl remove com.copaw.gbrain-8083
launchctl remove com.copaw.dream-8083

问题 7：ollama qwen3-embedding 维度错配

症状：gbrain serve 启动时报 Embedding dim mismatch: model returned 2560 but schema expects 768

原因：早期 ollama recipe 写死 default_dims=768（适配 nomic-embed-text），qwen3-embedding:4b 实际返回 2560 维

已修复：从 4e8b7eb 起，ollama.ts patch 把 default_dims 改为 2560，并加入 model_dims 映射支持多种 ollama embedding 模型

手动重新初始化（如果是旧 brain 库）：

# 备份
mv ~/.gbrain_8083 ~/.gbrain_8083.bak-$(date +%Y%m%d)

# .env 设置正确维度
echo "GBRAIN_EMBEDDING_DIMENSIONS=2560" >> ~/copaw-deploy/data/.env

# 重新跑 init（仅 gbrain 部分）
bash ~/copaw-deploy/darwin/apple/gbrain/03-init-brain.sh

📝 配置文件说明

配置目录结构

~/.copaw_dev_fork/  (或其他配置目录)
├── workspaces/
│   └── default/
│       ├── agent.json          # Agent 配置
│       ├── skill.json          # 技能配置
│       ├── skills/             # 技能文件
│       ├── pipelines/          # 编排配置
│       └── active_skills/      # 激活的技能
├── config.yaml                 # 全局配置
├── .env                        # 环境变量
├── copaw.log                   # 运行日志
└── copaw.pid                   # 进程 PID

环境变量

变量	说明	示例
`COPAW_WORKING_DIR`	配置目录路径	`~/.copaw_dev_fork`
`QWENPAW_WORKING_DIR`	旧版配置目录（向后兼容）	`~/.copaw_dev_fork`

🧠 GBrain + 记忆系统配置

部署完成后，默认使用 remelight（轻量本地记忆）。如需开启 GBrain 知识图谱检索 + 自动记忆：

快速开启（推荐配置）

编辑 ~/.copaw_<PORT>/workspaces/default/agent.json，修改 running 字段：

{
  "running": {
    "memory_manager_backend": "composite",
    "auto_memory_interval": 20,
    "composite_memory_config": {
      "enabled_providers": ["agent_file", "gbrain"]
    },
    "reme_light_memory_config": {
      "summarize_when_compact": true,
      "auto_memory_search_config": {
        "enabled": true,
        "max_results": 5,
        "min_score": 0.3
      }
    }
  }
}

配置说明

字段	值	说明
`memory_manager_backend`	`"composite"`	多源记忆管理器（替代默认的 `remelight`）
`composite_memory_config.enabled_providers`	`["agent_file", "gbrain"]`	启用本地文件 + GBrain 双源
`auto_memory_search_config.enabled`	`true`	每次对话自动召回相关记忆
`auto_memory_interval`	`20`	每 20 轮对话自动提取记忆
`reme_light_memory_config.summarize_when_compact`	`true`	上下文压缩时自动写入 memory

GBrain MCP 连接

bootstrap --full-stack 已自动配置 mcp.clients.gbrain（streamable HTTP + Bearer token）。如需手动确认：

// agent.json → mcp.clients.gbrain
{
  "name": "gbrain",
  "enabled": true,
  "transport": "streamable_http",
  "url": "http://127.0.0.1:3131/mcp",
  "headers": {
    "Authorization": "Bearer <自动生成的 token>"
  }
}

Dream 定时任务（可选）

⚠️ 重要：dream cycle 依赖 minion worker 异步写知识页面。bootstrap 部署时步骤 06.8-install-worker 已自动安装 gbrain-worker.service（Linux）。若未安装，dream 会卡在 synthesize 阶段。

如需每天自动执行 dream（记忆优化 + 知识提取）：

bash bootstrap.sh --full-stack --port 8083 --enable-dream-cron

详见 common/runtime-config/README.md。

🤖 LLM / Embedding Provider 配置

CoPaw 通过 data/.env 配置所有 LLM 和 embedding provider。完整模板见 data/env.template，配置场景速查：

场景 A：国内生产（推荐）

ARK 火山方舟一个 key 路由 OpenAI + Anthropic 协议 + Ollama 本地 embedding：

# data/.env
ARK_API_KEY=ark-xxxxx
OPENAI_API_KEY=ark-xxxxx
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/coding/v3
ANTHROPIC_API_KEY=ark-xxxxx
ANTHROPIC_BASE_URL=https://ark.cn-beijing.volces.com/api/coding/v1

# Ollama 本地 embedding（先 ollama pull qwen3-embedding:4b）
OLLAMA_BASE_URL=http://localhost:11434/v1

# GBrain 模型路由
GBRAIN_DEFAULT_MODEL=Doubao-Seed-2.0-pro
GBRAIN_THINK_MODEL=anthropic:claude-sonnet-4-5
GBRAIN_SUBAGENT_MODEL=anthropic:claude-haiku-4-5-20251001
GBRAIN_EMBEDDING_MODEL=ollama:qwen3-embedding:4b
GBRAIN_EMBEDDING_DIMENSIONS=2560

场景 B：海外生产

OpenAI / Anthropic 真身 + Voyage embedding：

OPENAI_API_KEY=sk-xxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
ANTHROPIC_API_KEY=sk-ant-xxxxx
ANTHROPIC_BASE_URL=https://api.anthropic.com
VOYAGE_API_KEY=pa-xxxxx

GBRAIN_DEFAULT_MODEL=gpt-4o
GBRAIN_THINK_MODEL=anthropic:claude-sonnet-4-5
GBRAIN_SUBAGENT_MODEL=anthropic:claude-haiku-4-5
GBRAIN_EMBEDDING_MODEL=voyage:voyage-3
GBRAIN_EMBEDDING_DIMENSIONS=1024

场景 C：全本地（断网友好）

Ollama 全栈：

OLLAMA_BASE_URL=http://localhost:11434/v1

# 先 ollama pull 这些模型
GBRAIN_DEFAULT_MODEL=ollama:qwen2.5:14b
GBRAIN_THINK_MODEL=ollama:qwen2.5:32b
GBRAIN_SUBAGENT_MODEL=ollama:qwen2.5:7b
GBRAIN_EMBEDDING_MODEL=ollama:qwen3-embedding:4b
GBRAIN_EMBEDDING_DIMENSIONS=2560

场景 D：阿里云百炼全栈

DASHSCOPE_API_KEY=sk-xxxxx
OPENAI_API_KEY=sk-xxxxx                              # DashScope 走 openai-compat
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

GBRAIN_DEFAULT_MODEL=qwen-max
GBRAIN_THINK_MODEL=qwen-max
GBRAIN_EMBEDDING_MODEL=dashscope:text-embedding-v3
GBRAIN_EMBEDDING_DIMENSIONS=1024

Provider 速查表

Provider	Chat	Embedding	base_url 默认
OpenAI	gpt-4o, gpt-4.1	text-embedding-3-small/large	`api.openai.com/v1`
Anthropic	claude-sonnet-4-5, claude-haiku-4-5	❌	`api.anthropic.com`
ARK 火山	Doubao 系列, anthropic:claude-*	text-embedding-v3	`ark.cn-beijing.volces.com/api/coding/v3`
DashScope	qwen-max, qwen-plus	text-embedding-v3/v4	`dashscope.aliyuncs.com/compatible-mode/v1`
DeepSeek	deepseek-chat, deepseek-reasoner	❌	`api.deepseek.com/v1`
Google	gemini-2.5-pro	❌	(SDK 内置)
Zhipu	glm-4-plus	embedding-3	`open.bigmodel.cn/api/paas/v4`
MiniMax	abab6.5	embo-01	`api.minimaxi.com/v1`
Voyage	❌	voyage-3, voyage-multilingual-2	`api.voyageai.com/v1`
Ollama	qwen2.5, llama3.2	qwen3-embedding, nomic-embed-text, bge-m3	`localhost:11434/v1`
Groq	llama-3.3-70b-versatile	❌	`api.groq.com/openai/v1`
OpenRouter	聚合多家	❌	`openrouter.ai/api/v1`
Together	多家开源	❌	`api.together.xyz/v1`
Azure OpenAI	(深度覆盖)	text-embedding-3-*	(需自建 deployment)

Embedding 维度对照（必须填对）

Embedding Model	维度
`ollama:qwen3-embedding:4b`	2560
`ollama:nomic-embed-text`	768
`ollama:bge-m3`	1024
`ollama:mxbai-embed-large`	1024
`openai:text-embedding-3-small`	1536
`openai:text-embedding-3-large`	3072
`dashscope:text-embedding-v3`	1024
`dashscope:text-embedding-v4`	2048
`voyage:voyage-3`	1024
`voyage:voyage-multilingual-2`	1024
`zhipu:embedding-3`	2048
`minimax:embo-01`	1536

⚠️ 维度不匹配会导致 gbrain init 失败或检索结果错位。ollama 的维度由模型本身决定，建议先 ollama pull <model> 后用 ollama show <model> 验证。

切换 provider 的步骤

编辑 data/.env（或运行中的实例的 ~/.copaw_<port>/.env）
取消对应段的注释，填上 API Key

重新跑 init 或重启服务：

# 全新部署
bash bootstrap.sh --full-stack --port 8083 --force

# 或仅重启已部署实例（embedding 改了需要 re-embed）
copaw-dev --port 8083 restart

🆘 获取帮助

查看脚本帮助：
```
bash deploy/copaw-dev.sh --help
```

查看日志：

# 最近 50 行
bash deploy/copaw-dev.sh --port 8085 logs

# 最近 200 行
bash deploy/copaw-dev.sh --port 8085 logs 200

# 实时跟踪
bash deploy/copaw-dev.sh --port 8085 follow

检查服务状态：

bash deploy/copaw-dev.sh --port 8085 status

📌 注意事项

macOS 平台：
- 仅支持 Apple Silicon（M1/M2/M3/M4）
- Intel 芯片暂不支持（darwin/intel/ 为占位）
- 需要 Homebrew 安装在 /opt/homebrew
端口冲突：
- 确保端口未被占用：lsof -i :8085
- 多实例部署时使用不同端口
配置隔离：
- 不同端口使用不同配置目录
- 不同端口使用不同 venv（~/.copaw_venv_8085）
wheel 更新：
- 修改源码后必须运行 bash deploy/build-wheel.sh
- 否则 bootstrap 安装的是旧版本
Agent 导入：
- export 包必须放在 deploy/ 目录
- 文件名格式：copaw_8086_export_*.tar.gz

🔗 相关文档

CoPaw 官方仓库：https://github.com/agentscope-ai/CoPaw
部署脚本源码：deploy/
开发环境管理：cmd/copaw-dev（源码模式，与 deploy 不同）

最后更新：2026-06-10

Name		Name	Last commit message	Last commit date
Latest commit History 119 Commits
common		common
config		config
darwin		darwin
data		data
docs		docs
linux/ubuntu		linux/ubuntu
packages		packages
tools		tools
utils		utils
windows		windows
.gitignore		.gitignore
BUG-agent-json-gbrain-token-placeholder.md		BUG-agent-json-gbrain-token-placeholder.md
BUG-cleanup-launchd-service-leak.md		BUG-cleanup-launchd-service-leak.md
Dockerfile		Dockerfile
README.md		README.md
bootstrap.ps1		bootstrap.ps1
bootstrap.sh		bootstrap.sh
build-wheel.sh		build-wheel.sh
cleanup.sh		cleanup.sh
configure-llm.sh		configure-llm.sh
copaw-dev.sh		copaw-dev.sh
entrypoint.sh		entrypoint.sh
install.ps1		install.ps1
install.sh		install.sh
setup-on-mac.sh		setup-on-mac.sh
update-copaw.sh		update-copaw.sh
verify-gbrain-token-fix.sh		verify-gbrain-token-fix.sh

Folders and files

Latest commit

History

Repository files navigation

CoPaw-Deploy 安装手册

1. 前提条件

1.1 Windows 平台特别说明

1.5. ⚠️ 安装前必读：GBrain 参数准备

典型方案（选一个填入 .env）

2. 一键安装（推荐）

macOS / Linux

Windows（PowerShell）

3. 手动安装（Agent 执行版）

步骤 1：获取部署脚本

步骤 2：运行 bootstrap

4. bootstrap.sh 参数说明

5. 部署流程说明（10 步 gbrain 链路 + 7 步主流程）

6. 端口与配置目录映射

7. 安装完成后

验证服务

访问 Web 控制台

配置 API Key

8. 服务管理

macOS

Linux

Windows（PowerShell）

9. 清理与重装

10. Dream Cron（每日知识整理）

10.1 Dream Cycle 模型配置（性能/成本优化）

11. 常见问题

Q: gbrain 下载超慢或失败

Q: "bun: not found" 或 gbrain 安装失败

Q: 端口冲突

Q: gbrain dream cycle 被 lock 阻塞

Q: dream cycle 一直卡在 "Synthesizing source=xxx" 不出来

Q: 安装中断后如何续跑

Q: 部署完成后只有 default agent，没有其他智能体和 pipeline

12. 升级已有环境

12.1 CoPaw wheel 包更新（packages/qwenpaw-x.y.z.whl）

12.2 gbrain 源码补丁更新（common/patches/gbrain/*.ts）

12.3 dream cron / runtime-config 更新

12.4 minion worker service 更新

12.5 gbrain 自身版本升级（v0.41 → v0.42）

12.6 GBrain 多用户凭据配置（v1.1.11.post2+ 必读）

12.7 bootstrap.sh / 子脚本本身更新

12.7 升级决策速查

12.8 升级失败回退

13. Release 包说明

14. 目录结构

🔧 开发者工作流

1. 修改源码后重新打包

2. 测试新 wheel

3. 导出 Agent 配置

🌍 多实例部署

🔍 故障排查

问题 1：启动失败

问题 2：Agent 未导入

问题 3：wheel 版本不匹配

问题 4：权限错误

问题 5：Agent 调用 gbrain MCP 报 401

问题 6：cleanup 后端口仍被占用

问题 7：ollama qwen3-embedding 维度错配

📝 配置文件说明

配置目录结构

环境变量

🧠 GBrain + 记忆系统配置

快速开启（推荐配置）

配置说明

GBrain MCP 连接

Dream 定时任务（可选）

🤖 LLM / Embedding Provider 配置

场景 A：国内生产（推荐）

场景 B：海外生产

场景 C：全本地（断网友好）

场景 D：阿里云百炼全栈

Provider 速查表

Embedding 维度对照（必须填对）

切换 provider 的步骤

🆘 获取帮助

📌 注意事项

12.1 CoPaw wheel 包更新（`packages/qwenpaw-x.y.z.whl`）

12.2 gbrain 源码补丁更新（`common/patches/gbrain/*.ts`）

Packages