CoPaw安装配置

CMOS 2026.3.2

一、部署 CoPaw

步骤 1：安装基础环境

# 更新包管理器，安装Python最小依赖
sudo apt update && sudo apt install -y python3 python3-pip python3-venv --no-install-recommends

# 检查Python版本（需3.9+）
python3 --version

# 创建虚拟环境（避免依赖冲突）
python3 -m venv copaw-env
source copaw-env/bin/activate  # 激活环境，退出用deactivate

# 升级pip
pip install --upgrade pip --no-cache-dir

步骤 2：安装并初始化 CoPaw

# 安装CoPaw（无缓存，节省空间）
pip install copaw --no-cache-dir

# 初始化CoPaw（默认配置）
copaw init --defaults

---

二、配置 CoPaw 调用外部大模型

1、配置参数

/root/copaw-env/lib/python3.12/site-packages/copaw/providers/providers.json(具体文件内容见本文最下面)

2、修改copaw app常驻运行

systemd 已配置完成并启动成功。

当前状态：

• 服务已启用并在运行
• 单元文件：/etc/systemd/system/copaw.service

你可以用这些命令管理：

  1. systemctl status copaw.service
     查看服务状态（是否在运行、启动是否成功、PID、最近日志）。
  2. systemctl restart copaw.service
     重启服务（修改配置、更新代码后常用）。
  3. journalctl -u copaw.service -f
     实时查看服务日志（用于排错或观察运行情况）。

三、问题处理FAQ

1、 问题现象

浏览器访问http://127.0.0.1:8088/，在模型页面配置模型之后，通过chat聊天对话提示失败。

通过管理页面配置LLM成功，但是依然无法对话提示错误。

2、定位过程

• 已分析并执行了检查命令，结论如下（可以“精确定位”到当时的配置状态）：

1. 当时的请求里 model 是空的，当时的错误文件 /tmp/copaw_query_error_n51p9dyg.json 里读取到：

• request.model: None
• request 中也没有 base_url

2. 这说明当时运行时没有解析到有效的 active LLM 配置，所以不会走期望的 codez / gpt-5.3-codex。这类情况会触发内部回退逻辑（默认 qwen3-max）。 copaw 读取 LLM 配置的位置是：

/root/copaw-env/lib/python3.12/site-packages/copaw/providers/providers.json

而不是 /root/.copaw/config.json。

3. 当前配置已是正确的 我已确认现在的 active slot 正常解析为：

provider_id: codez

model: gpt-5.3-codex

base_url: api.zwenooo.link/v1

———

4. 精确定位“前期哪里配置错” 结合上面的证据，问题只可能出在当时的 providers.json 里：

• active_llm 为空
• 或 active_llm.provider_id/model 不完整
• 或 codez provider 没配置 base_url/api_key
• 或你改的是另一个文件（比如 ~/.copaw/config.json）

结论：当时错的是 providers.json 里的 active slot 未被正确设置。

2、附件

/root/copaw-env/lib/python3.12/site-packages/copaw/providers/providers.json

root@CMOS:~# more /root/copaw-env/lib/python3.12/site-packages/copaw/providers/providers.json
{
  "providers": {
    "modelscope": {
      "base_url": "https://api-inference.modelscope.cn/v1",
      "api_key": "",
      "extra_models": [
        {
          "id": "codez",
          "name": "codez"
        }
      ],
      "chat_model": ""
    },
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "相关KEY",
      "extra_models": [
        {
          "id": "gpt-5.3-codex",
          "name": "gpt-5.3-codex"
        }
      ],
      "chat_model": ""
    },
    "ollama": {
      "base_url": "http://localhost:11434/v1",
      "api_key": "",
      "extra_models": [],
      "chat_model": ""
    }
  },
  "custom_providers": {
    "codez": {
      "id": "codez",
      "name": "codez",
      "default_base_url": "https://api.zwenooo.link/v1",
      "api_key_prefix": "相关KEY",
      "models": [
        {
          "id": "gpt-5.3-codex",
          "name": "gpt-5.3-codex"
        },
        {
          "id": "gpt-5.2-codex",
          "name": "gpt-5.2-codex"
        }
      ],
      "base_url": "https://api.zwenooo.link/v1",
      "api_key": "相关KEY",
      "chat_model": "OpenAIChatModel"
    }
  },
  "active_llm": {
    "provider_id": "codez",
    "model": "gpt-5.3-codex"
  }
}