血衫非弧の一存

QwenPaw 在 Mac Studio 上 KV Cache 命中率归零的排查与根因

Fri, 08 May 2026 00:00:00 +0800

最近给 QwenPaw 配置 LM Studio 时，发现一个现象：LLM 请求的 KV Cache 命中率始终为 0。

排查了一圈配置和代理链路，最终发现这不是 bug，而是 Apple Silicon (MLX) 与 NVIDIA CUDA 在 KV Cache 实现上的根本性差异。记录一下排查过程和实验数据。

架构与现象

我们的请求链路如下：

QwenPaw (Linux) → Docker(cli-proxyapi:8317) → LM Studio (Mac M2 Max, 100.100.100.11:1234)

在 LM Studio 的 Web UI 中，我已经开启了 KV缓存量化 (Experimental)，上下文长度设为 262144。但 QwenPaw 的 token 用量日志显示，每次请求都是全新的 prompt，缓存从未命中。

排查过程

Step 1: 排除代理层干扰

首先怀疑是 cli-proxyapi 在转发时注入了动态 header（如 X-Request-Id、时间戳等），导致每次请求的 HTTP 头不一致。

curl -sv ... http://cli-proxyapi.sh4.local:8317/v1/chat/completions 2>&1 | grep -E "^[<>]"

结果：两次请求的 header 完全一致，代理层干净。

Step 2: 排除多实例负载均衡

如果 LM Studio 背后有多台机器轮询，缓存自然无法复用。我是单实例运行，无负载均衡。

Step 3: KV Cache 压力测试

我构造了两组对比实验：

实验 A：完全相同的 prompt 重复发送

{"model":"qwen3.6-35b-a3b@8bit","messages":[{"role":"system","content":"You are a test bot."},{"role":"user","content":"What is 1+1?"},{"role":"assistant","content":"2"},{"role":"user","content":"And 2+2?"}],"max_tokens":5,"temperature":0}

Req1: 1011ms
Req2: 444ms (↓ 56% 加速)

实验 B：相同前缀(100K chars) + 不同后缀（模拟 Agent 多轮对话）

PREFIX=$(python3 -c "print('A'*100000)") # 约 25K tokens
# Req1: system="$PREFIX", user="Say ONE word: test"
# Req2: system="$PREFIX", user="Say ONE word: test" (完全相同)

Req1: 632ms
Req2: 753ms (反而更慢，缓存未生效)

核心结论：MLX vs CUDA 的 KV Cache 差异

实验数据说明了原因：

场景	CUDA (vLLM/TGI)	Apple Silicon (MLX/LM Studio)
完全相同的 prompt	✅ 命中，复用 KV Cache	✅ 命中，复用 KV Cache
相同前缀 + 不同后缀	✅ 自动前缀缓存 (Prefix Caching)	❌ 不支持，必须逐字节完全匹配

QwenPaw 的 Agent 场景每轮发送的 prompt 结构如下：

[固定 System Prompt (~15K tokens)] + [变化的对话历史] + [新的 User Message]
         ↑ 前缀固定                          ↑ 每轮变化

在 CUDA 推理框架中，vLLM/TGI 会自动提取相同的前缀进行 KV Cache 复用，Agent 场景的缓存命中率通常能达到 30%~50%。

但在 Apple Silicon 上，LM Studio 底层使用 MLX 框架。MLX 的 KV Cache 实现较为朴素，仅支持精确匹配（Exact Match），不支持前缀缓存 (Prefix Caching)。Apple Silicon 的 KV Cache 优化目前仍处于实验阶段，前缀复用功能尚未稳定。

踩坑记录

Apple Silicon 的 MLX 框架限制：MLX 在推理速度上已经非常优秀，但在企业级特性（如 Prefix Caching、Continuous Batching）上仍落后于 CUDA 生态。选型时需明确场景需求。
实验设计：用 date +%s%N 记录毫秒级耗时，配合完全相同的 prompt vs 前缀相同后缀不同的对比，能最快定位缓存生效边界。

Mac Studio 接入 Prometheus + Grafana 监控实践

Fri, 08 May 2026 00:00:00 +0800

最近给 Mac Studio 配了一套监控方案，通过 macmon-prometheus-exporter 采集硬件指标，接入 Prometheus + Grafana。整个过程比想象中简单，记录一下细节。

安装 macmon

参考macmon - Apple Silicon Mac 的性能监控利器

安装 Exporter

macmon-exporter 通过 Homebrew 一键安装：

brew install macmon-prometheus-exporter

安装后会自动注册为 launchd 服务，监听 9101 端口。验证一下：

curl http://localhost:9101/metrics | head -20

关键指标一览

macmon-exporter 暴露的指标都在 mac_ 命名空间下，都是 Gauge 类型（瞬时值）：

指标	含义	示例值
`mac_cpu_usage_percent`	CPU 总使用率（%）	27.69
`mac_gpu_usage_percent`	GPU 使用率（%）	100.0
`mac_cpu_power_watts`	CPU 功耗（瓦特）	4.88
`mac_gpu_power_watts`	GPU 功耗（瓦特）	50.86
`mac_cpu_temperature_celsius`	CPU 温度（摄氏度）	52.69
`mac_gpu_temperature_celsius`	GPU 温度（摄氏度）	48.97
`mac_memory_usage_percent`	内存使用率（%）	62.00
`mac_memory_total_bytes`	内存总量（字节）	103079215104

注意：macmon-exporter 提供的是瞬时百分比值，不是累积计数器。这意味着在 Grafana 中不需要使用 irate() 或 rate()。

Prometheus 配置

prometheus.yml

- job_name: 'node-studio'
    static_configs:
      - targets: ['studio.local:9101']
        labels:
          exported_instance: "studio"
          node: "studio"

Grafana 面板配置

CPU / GPU 使用率

Linux 节点通常用 irate(node_cpu_seconds_total{mode="idle"}) 计算 CPU 使用率，但 Mac Studio 的 macmon-exporter 直接提供百分比值：

# CPU 使用率（除以100因为Grafana自带百分号）
avg(mac_cpu_usage_percent{node="studio"}) by (node) / 100

# GPU 使用率
avg(mac_gpu_usage_percent{node="studio"}) by (node) / 100

CPU 核心数对比

Linux 节点用 count(node_cpu_seconds_total{mode="system"}) 统计核心数，Mac Studio 需要分别查询 P-Core 和 E-Core：

# Mac Studio: 8P + 4E = 12 核心
sum(mac_pcpu_cores{node="studio"}) + sum(mac_ecpu_cores{node="studio"})

内存使用率

同样，macmon-exporter 直接提供百分比：

# 内存使用率（除以100）
avg(mac_memory_usage_percent{node="studio"}) by (node) / 100

# 内存总量（注意单位）
mac_memory_total_bytes{node="studio"} / 1024^3

踩坑：Grafana 默认使用十进制单位（1 GB = 10^9 bytes），所以 mac_memory_total_bytes 直接除以 1024^3 后显示为 96 GiB（二进制），而不是 103 GB（十进制）。在 Grafana 面板中将 Unit 设为 gibibytes (GiB) 即可正确显示。

CPU / GPU 温度

# CPU 温度
mac_cpu_temperature_celsius{node="studio"}

# GPU 温度
mac_gpu_temperature_celsius{node="studio"}

功耗监控

Apple Silicon 的功耗数据很有参考价值：

# CPU 功耗（瓦特）
mac_cpu_power_watts{node="studio"}

# GPU 功耗（瓦特）
mac_gpu_power_watts{node="studio"}

# 系统总功耗
mac_system_power_watts{node="studio"}

# 过去1小时的平均系统功耗
avg_over_time(mac_system_power_watts{node="studio"}[1h])

# 过去24小时的平均系统功耗
avg_over_time(mac_system_power_watts{node="studio"}[24h])

# 过去7天的平均系统功耗
avg_over_time(mac_system_power_watts{node="studio"}[7d])

注意事项

瞬时值 vs 计数器：macmon-exporter 的百分比指标是 Gauge，不需要 irate()。只有累积计数器才需要 rate/irate。
单位转换：Grafana 的 Unit 设置会影响显示值，注意区分 GB（十进制）和 GiB（二进制）。
温度监控：macmon-exporter 只暴露 CPU/GPU 温度，没有硬盘 SMART 信息。如果需要磁盘温度，需要额外安装 smartmontools。

部署 CLIProxyAPI 和 CPA Usage Keeper

Sun, 03 May 2026 00:00:00 +0800

最近在折腾本地 AI 代理服务，把 CLIProxyAPI 和 CPA Usage Keeper 部署到了 Docker 里，记录一下过程。

背景

CLIProxyAPI

CLIProxyAPI 是一个开源的 AI API 代理服务，主要用来：

转发 OpenAI/Gemini/Claude/Codex 等模型的 API 请求
支持 OAuth 登录，获取官方模型的配额
可以对接 OpenRouter 等第三方 API 聚合平台
提供 Web 管理界面和 API

对于我这种无法直接访问 OpenAI/Gemini 官方 API 的人来说，它是个不错的解决方案。可以把请求转发到 OpenRouter，由 OpenRouter 帮我调用意愿的模型。

CPA Usage Keeper

CPA Usage Keeper（简称 CPA）是 CLIProxyAPI 的配套管理工具，主要功能：

同步 CLIProxyAPI 的使用数据（请求数、Token 消耗等）
管理 API Keys 和凭证
提供使用量统计和可视化界面
支持多用户/多项目统计

简单说就是给 CLIProxyAPI 做一个”后台”，方便查看花了多少钱、用了多少 Token。

部署步骤

1. 准备目录和配置文件

创建工作目录：

mkdir -p /root/docker/cliproxyapi
cd /root/docker/cliproxyapi

配置文件 config.yaml：

host: "0.0.0.0"
port: 8317

remote-management:
  allow-remote: true
  secret-key: "my-simple-key"

api-keys:
  - "cliproxy-default-key"

openai-compatibility:
  - name: "openrouter"
    prefix: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    headers:
      Content-Type: "application/json"
    api-key-entries:
      - api-key: "你的 OpenRouter API Key"
    models:
      - name: "minimax/minimax-m2.5:free"
        alias: "minimax-m2.5-free"

2. config.yaml 完整配置

记得开启 usage-statistics-enabled，否则不会记录使用量：

host: "0.0.0.0"
port: 8317

remote-management:
  allow-remote: true
  secret-key: "my-key"

api-keys:
  - "cliproxy-key"

openai-compatibility:
  - name: "openrouter"
    prefix: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    headers:
      Content-Type: "application/json"
    api-key-entries:
      - api-key: "你的 OpenRouter API Key"
    models:
      - name: "minimax/minimax-m2.5:free"
        alias: "minimax-m2.5-free"
  - name: DeepSeek
    base-url: https://api.deepseek.com
    models:
      - name: deepseek-v4-pro
      - name: deepseek-v4-flash
    headers:
      Authorization: Bearer 你的DeepSeek-API-Key
      Content-Type: application/json
    prefix: ds
  - name: lmstudio
    prefix: studio
    base-url: http://本地IP:1234/v1
    models:
      - name: qwen3.6-35b-a3b@8bit

usage-statistics-enabled: true

3. docker-compose.yml

version: '3'
services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxyapi
    network_mode: bridge
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
    restart: unless-stopped

  cpa-usage-keeper:
    image: ghcr.io/willxup/cpa-usage-keeper:latest
    container_name: cli-cpa
    restart: unless-stopped
    network_mode: bridge
    environment:
      - TZ=Asia/Shanghai
      - CPA_BASE_URL=http://cliproxyapi.local:8317
      - REDIS_QUEUE_ADDR=cliproxyapi.local:8317
      - CPA_MANAGEMENT_KEY=my-key
      - AUTH_ENABLED=true
      - LOGIN_PASSWORD=password
    volumes:
      - ./keeper:/data

4. 启动服务

docker-compose up -d

5. 验证

检查容器状态：

docker ps | grep cli-

CLIProxyAPI 默认监听在 8317，CPA 默认监听在 8080。

调用示例

配置好模型后，就可以像调用普通 OpenAI API 一样调用 CLIProxyAPI：

curl http://cliproxyapi:8317/v1/chat/completions \
  -H "Authorization: Bearer cliproxy-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m2.5-free",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

参数说明：

参数	值
地址	`http://cliproxyapi:8317`
API Key	`cliproxy-key` (config.yaml 中配置的 api-keys)
Model	`minimax-m2.5-free` (config.yaml 中定义的 alias)

如果需要添加更多模型，只需要在 config.yaml 的 openai-compatibility.models 中添加即可。

其他模型示例：

curl http://cliproxyapi:8317/v1/chat/completions \
  -H "Authorization: Bearer cliproxy-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b@8bit",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

一些坑

1. 密钥配置

CLIProxyAPI 的 secret-key 支持明文配置，启动时会自动 bcrypt 哈希。所以直接写明文就行，别像我一开始那样直接贴个 bcrypt 哈希上去，结果两边密钥对不上。

2. 免密登录

试了下把 secret-key 设为空想免密，结果管理 API 直接返回 404 不可用了。CPA 还需要管理 API 来同步数据，所以没法完全免密。好在明文密钥两边会自动哈希匹配，保持一致很简单。

. 使用量统计默认关闭

一开始 CPA 怎么都拉不到数据，后来发现 CLIProxyAPI 默认关闭了使用量统计。需要在 config.yaml 里加上：

usage-statistics-enabled: true

4. CPA 登录保护

CPA 默认不带密码，如果暴露在公网很危险。启用登录保护：

environment:
  - AUTH_ENABLED=true
  - LOGIN_PASSWORD=password

访问

CLIProxyAPI API: http://CLIProxyAPI:8317
CLIProxyAPI Dashboard: http://CLIProxyAPI:8317/v0/management
CPA 管理界面: http://CPA:8080

小结

这两个工具配合起来挺香的，CLIProxyAPI 做代理转发，CPA 做使用量统计和密钥管理。内部网络环境下，通过 OpenRouter 访问各种模型还是很方便的。

macmon - Apple Silicon Mac 的性能监控利器

Thu, 30 Apr 2026 00:00:00 +0800

跑本地 LLM 模型的时候，一直想看 GPU 和 ANE 的实时功耗和温度。macOS 自带的 Activity Monitor 只有 CPU 使用率，看不到功耗数据。之前有 powermetrics 可以看，但要 sudo 权限，输出也是纯文本。后来发现了 macmon，Rust 写的 TUI 工具，不需要 sudo 就能看到芯片级的实时数据，果断装上。

安装

通过 Homebrew 安装：

/opt/homebrew/bin/brew install macmon

⚠️ 仅支持 Apple Silicon（M1-M5），x86 的 Homebrew 会报架构不兼容。

功能

macmon 通过 macOS 私有 API 采集数据，和 powermetrics 用同一个底层接口，但不需要 root 权限。主要功能包括：

⚡ 实时功耗：CPU / GPU / ANE 的实时功耗（瓦特）
📊 CPU 集群利用率：E-Core 和 P-Core 分开显示
💾 内存 / Swap 使用量
🌡️ CPU / GPU 温度
📈 历史曲线：带平均值和最大值
🎨 6 种配色主题，按 c 切换
🪟 紧凑模式可以塞进小窗口

使用

基本 TUI

macmon

运行后界面分几个区域：

顶部：芯片型号、E/P 核心数、GPU 核心数、内存大小
CPU 使用率曲线：E-Core 和 P-Core 分开显示，macOS 日常用 E-Core，重负载才切 P-Core
GPU 使用率：图形处理负载
功耗和温度：系统总功耗、CPU/GPU/ANE 分项功耗，以及 CPU/GPU 平均温度

键盘操作：

快捷键	功能
`q`	退出
`v`	切换 Sparkline / Gauge 视图
`c`	切换配色主题

控制采样间隔

macmon -i 500

默认 1000ms 刷新，可以改成 500ms 更频繁。

输出 JSON 给其他工具

macmon pipe -s 10

会输出 10 条 JSON 格式的指标数据，适合管道到 jq 或者其他脚本处理。

macmon -i 500 pipe -s 10 | jq

HTTP Server 模式

macmon 还支持把指标暴露为 HTTP 服务，方便接入 Prometheus / Grafana：

macmon serve          # 默认 9090 端口
macmon serve -p 8080  # 自定义端口
macmon serve -i 500   # 采样间隔 500ms

两个端点：

端点	格式	说明
`GET /json`	JSON	当前指标快照
`GET /metrics`	Prometheus	Prometheus 格式指标

接入 Prometheus 的配置示例：

scrape_configs:
  - job_name: macmon
    static_configs:
      - targets: ["localhost:9090"]

小结

macmon 是目前 Apple Silicon Mac 上最方便的终端监控工具，Rust 实现，单二进制文件，无需 sudo 就能看到芯片级功耗和温度。对于跑本地模型、监控系统负载来说非常实用。

参考

macmon GitHub：https://github.com/vladkens/macmon

修复 opencode 命令运行时报错 TypeError fn3 is not a function

Mon, 27 Apr 2026 00:00:00 +0800

最近在使用 opencode 时遇到了一个奇怪的报错：

$ opencode
TypeError: fn3 is not a function. (In 'fn3(input)', 'fn3' is an instance of Object) at <anonymous> (src/plugin/index.ts:87:28)

但 opencode --help 和 opencode debug 却能正常运行。排查下来发现是版本过旧 + Homebrew upgrade 失效导致的问题，后续又牵连出一系列插件配置问题。记录一下完整的排查过程。

问题排查

确认环境

$ node --version
v18.20.8

$ npm --version
10.8.2

$ which opencode
/opt/homebrew/bin/opencode

$ opencode --version
1.1.50

发现版本不匹配

怀疑是版本问题，尝试 brew upgrade opencode，但升级后版本仍然是 1.1.50。进一步查看：

$ brew info opencode
==> opencode: stable 1.4.10 (bottled)
AI coding agent, built for the terminal
https://opencode.ai

Installed:
/opt/homebrew/Cellar/opencode/1.1.50 (4 files, 101.5MB)

Tap 源已经有 1.4.10，但本地还停留在 1.1.50——brew upgrade 没有生效。

原因分析

我最初安装 opencode 时，它还未被收录进 Homebrew 官方核心库（homebrew-core），而是通过第三方 tap anomalyco/tap 安装的。后来 opencode 被官方收录，但本地环境依然优先读取旧的第三方 tap，导致版本停滞在旧版本。

可以通过 brew info 的 “From” 行来确认来源：

# 旧的第三方 tap 来源
From: https://github.com/anomalyco/homebrew-tap/blob/HEAD/opencode.rb

# 新的官方来源
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/o/opencode.rb

解决方案

1. 卸载旧版本

brew uninstall opencode

2. 移除旧的 Tap 源

这一步是关键，将 anomalyco/tap 从本地库中移除：

brew untap anomalyco/tap

3. 更新并重新安装

brew update
brew install opencode

这一次系统会从 homebrew-core 拉取最新版本：

🍺  /opt/homebrew/Cellar/opencode/1.4.10: 12 files, 101.3MB

4. 验证修复

$ opencode --version
1.4.10

$ opencode --help
# 正常显示所有命令

$ brew postinstall opencode
# 确保 post-install 步骤执行完成

重新安装后，CLI 模式正常工作，TypeError 报错消失。

后续：插件配置问题

升级版本后，CLI 模式已经正常，但使用 Web 界面时又遇到新错误：

unknown certificate verification error

实际排查后发现，真正的原因是 API 验证错误：

{
  "error": {
    "code": 34,
    "message": "request validation errors",
    "errors": [{
      "type": "Extra inputs are not permitted",
      "loc": ["body", "tools[0]", "eager_input_streaming"],
      "msg": "Extra inputs are not permitted",
      "input": true
    }]
  }
}

定位配置

opencode 的配置文件不在 ~/.opencode/，而是在：

$ ls ~/.config/opencode/
opencode.json  oh-my-opencode.json.bak

发现问题插件

查看 opencode.json 后发现：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-openagent@latest"]
}

这里配置的 oh-my-openagent 插件向 Minimax API 发送了不支持的 eager_input_streaming 参数，导致验证失败。

临时解决

将插件列表清空：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": []
}

禁用插件后，opencode run "你好" 可以正常收到 AI 回复。

关于 oh-my-opencode 插件

opencode 本身只是一个框架，真正的能力来自插件。oh-my-opencode（后改名为 oh-my-openagent）是 opencode 的插件集合，提供多种专业 agent。

安装

bunx oh-my-opencode install --no-tui --skip-auth

--no-tui 参数可以跳过图形界面交互，适合非交互式环境。

模型配置

安装后可能会遇到模型验证问题：

Agent atlas's configured model opencode/glm-4.7-free is not valid

解决方法是更换为有效的模型，例如 opencode/big-pickle 或 opencode/gpt-5-nano。

包名变更

2026 年 3 月发生了一个重要变化：

项目	旧名称	新名称
npm 包	oh-my-opencode	oh-my-openagent（v3.11.0, 2026-03-07）
配置文件	oh-my-opencode.json	保留不变
Schema 文件	oh-my-opencode.schema.json	保留不变

配置文件名称有意保留旧名以保持向后兼容：

# 两种配置名都能工作
~/.config/opencode/oh-my-opencode.json    # 传统（推荐）
~/.config/opencode/oh-my-openagent.json    # 新式

Agent 体系

oh-my-opencode 中包含一套完整的 agent 协作体系：

Agent	角色	说明
Sisyphus	执行者	负责任务分解、代码实现
Prometheus	规划代理	通过 `/start-work` 激活，负责生成执行计划
Metis	预规划咨询	在规划阶段识别歧义和隐藏意图
Momus	计划评审	对执行计划进行清晰度和完整性审查

opencode vs openclaw

之前也有人问 opencode 和 openclaw 的区别：

特性	opencode	openclaw
类型	AI 编程助手	AI 控制器
核心	终端 IDE	远程控制
通道	本地为主	WhatsApp/Telegram
定位	编码工作流	远程任务管理

两者定位不同，没有必要互相替换。

总结

问题	解决方法
`TypeError: fn3 is not a function`	卸载旧 tap 源，从 homebrew-core 重新安装最新版
`eager_input_streaming` 验证错误	清空 `plugin` 配置或更换兼容插件
配置目录找不到	记住在 `~/.config/opencode/` 而非 `~/.opencode/`

几点经验教训：

遇到奇怪错误，先检查版本：很多问题就是版本太旧导致的
brew upgrade 不一定可靠：如果升级后版本没变，可能需要先 untap 再重装
第三方 tap 要注意迁移：当项目被 Homebrew 官方收录后，旧的第三方 tap 可能不会自动更新
错误信息要看完整：unknown certificate verification error 是误报，真正的错误在 API 响应体里
插件配置要核对：确保插件名称与实际安装的包一致

Mac 下 QwenPaw 安装记录 - 从零配置 OpenRouter MiniMax 模型

Wed, 22 Apr 2026 00:00:00 +0800

把 QwenPaw（原 CoPaw）装好了，记录一下安装和配置过程。

背景

QwenPaw 是 AgentScope 团队开源的个人 AI 助手，支持钉钉、飞书、微信、Discord 等多渠道，还能本地运行、扩展 Skills。GitHub 星标 15K+。

问题卡点

官方推荐三种安装方式：

pip install qwenpaw — 需要 Python 3.10+
安装脚本 curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash — 自动下载 uv
Docker

我的系统自带 Python 是 3.9.6，pip 版本也老（21.2.4），而 qwenpaw 要求 Python 3.10-3.14。我平时用 conda 管理 Python 环境，所以直接走 conda 路线。

用 conda 创建环境

# 1. 创建 Python 3.11 虚拟环境
conda create -n qwenpaw python=3.11 -y

# 2. 激活环境
conda activate qwenpaw

# 3. 安装 qwenpaw
pip install qwenpaw

这样就搞定了，不需要额外引入 uv。环境激活后 python 和 pip 都指向 conda 环境内的版本，不会产生污染。

配置 OpenRouter MiniMax 模型

qwenpaw 内置支持 OpenRouter provider，配置很简单。编辑 ~/.copaw/config.json：

{
  "$schema": "https://qwenpaw.agentscope.io/schema.json",
  "model": {
    "models": {
      "minimax-free": {
        "provider": "openrouter",
        "model": "minimax/minimax-m2.5:free",
        "base_url": "https://openrouter.ai/api/v1",
        "api_key": "你的OPENROUTER_KEY",
        "enabled": true
      }
    },
    "default_model": "minimax-free"
  }
}

注意：OpenRouter 的 MiniMax 模型 ID 格式是 minimax/minimax-m2.5:free，用冒号而不是连字符。

启动与验证

# 激活 conda 环境后，qwenpaw 命令可直接使用
conda activate qwenpaw

# 初始化（需要交互式终端）
qwenpaw init

# 或者启动 Web UI
qwenpaw app

启动后打开浏览器访问 http://127.0.0.1:8088/ 进行配置和聊天。

验证安装：

qwenpaw --version
# QwenPaw, version 1.1.3

Agent 配置：让 Agent 理解你是谁

安装完成只是第一步，真正的关键在于记忆文件配置。

核心记忆文件

QwenPaw 的工作区位于 ~/.copaw/workspaces/default/，包含以下文件：

文件	作用	优先级
`PROFILE.md`	Agent 身份 + 用户资料	🔴 必须配置
`SOUL.md`	Agent 灵魂宣言（行为准则）	🔴 必须配置
`MEMORY.md`	长期记忆（工具设置/经验教训）	🟡 建议配置
`AGENTS.md`	Agent 行为准则模板	🟢 可选定制
`HEARTBEAT.md`	定时任务清单	🟢 可选配置

配置流程

首次启动 — Agent 自动读取所有记忆文件，为空则使用默认模板。
手动配置 — 编辑 PROFILE.md 定义身份和偏好，编辑 SOUL.md 定义行为边界。
持续迭代 — Agent 会在每次会话中主动记录重要信息到 memory/YYYY-MM-DD.md，定期提炼到 MEMORY.md。

关键：QwenPaw 不会每次重启都重新初始化。记忆通过文件持久化，会话中断后自动恢复上下文。

依赖规模

qwenpaw 的依赖比较多（约 244 个包），包括：

agentscope 1.0.19
playwright 1.58.0（39MB）
transformers 5.5.4（9.8MB）
onnxruntime 1.23.2（16MB）
chromadb 1.5.8（20MB）
grpcio 1.80.0（11MB）
pandas 3.0.2（9.5MB）
阿里系 SDK（alibabacloud-dingtalk 等）
消息渠道 SDK（discord-py、twilio 等）

首次安装需要下载不少内容，耐心等待即可。conda 环境下这些依赖会被隔离在环境目录中，不会影响系统。

工具	语言	特点
QwenPaw	Python	多渠道、本地优先、Skills 扩展
OpenCode	TypeScript	IDE 集成、MCP 生态
Claude Code	TypeScript	Anthropic 官方

参考资料

QwenPaw 官网：https://qwenpaw.agentscope.io/
GitHub：https://github.com/agentscope-ai/QwenPaw
OpenRouter MiniMax M2.5 Free：https://openrouter.ai/minimax/minimax-m2.5:free

OpenCode 配置 MiniMax 免费模型指南

Tue, 21 Apr 2026 00:00:00 +0800

今天把 OpenCode 的默认模型配置成了 MiniMax M2.5 Free，教程记录一下。

背景

我想把自己的 OpenCode 配置成使用 MiniMax 的免费模型，于是研究了一下。最新版本是 M2.7（2026年3月发布），但是在 OpenRouter 上免费只有 M2.5，且 oh-my-openagent 插件内部也硬编码了 M2.7，需要一并修改。

MiniMax M2.5 Free 配置教程

1. 申请 OpenRouter API Key

OpenRouter 是一个聚合多家 AI 模型 API 的平台，其中提供了免费的 MiniMax 模型。

访问 https://openrouter.ai/keys
点击 “Create a new key” 创建免费 API Key
复制生成的 Key

2. 配置 OpenCode

编辑配置文件 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-openagent@latest"
  ],
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "bun",
        "x",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  },
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MiniMax M2.5 Free",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "你的 OpenRouter API Key"
      },
      "models": {
        "minimax-m2.5-free": {
          "name": "minimax/minimax-m2.5:free"
        }
      }
    }
  },
  "model": "openrouter/minimax/minimax-m2.5:free"
}

3. 配置 oh-my-openagent（如有安装）

如果安装了 oh-my-openagent 插件，它内部默认配置了 minimax-m2.7-free 模型，但 OpenRouter 上免费只有 M2.5。需要修改插件配置。

编辑 ~/.config/opencode/oh-my-openagent.json，将所有 openrouter/minimax/minimax-m2.5:free 替换为 openrouter/minimax/minimax-m2.5:free：

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "hephaestus": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "oracle": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "librarian": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "explore": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "multimodal-looker": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "prometheus": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "metis": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "momus": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "sisyphus": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "sisyphus-junior": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "atlas": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "ollama/qwen3-coder-next:q4_K_M"
    },
    "ultrabrain": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "deep": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "artistry": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "quick": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "unspecified-low": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "unspecified-high": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    },
    "writing": {
      "model": "openrouter/minimax/minimax-m2.5:free"
    }
  }
}

4. 重启 OpenCode

配置完成后重启 OpenCode 即可使用免费的 MiniMax 模型。

模型信息

模型	价格	Context
MiniMax M2.5 Free	$0/M tokens	196K tokens

完全免费！香！

参考资料

MiniMax 官方文档：https://platform.minimax.io/docs/
OpenRouter：https://openrouter.ai/

为什么 cAdvisor 在部分节点采集不到容器的内存数据？

Wed, 08 Apr 2026 00:00:00 +0800

最近在搞跨云节点的容器监控，遇到一个非常诡异的问题：在 Grafana 面板上，有很多容器拉不到内存信息。

具体表现是，看 container_memory_max_usage_bytes{image!=""} 这个指标时，老节点的数据一切正常，能读到具体的字节数；但新节点的数据全都是 0。

仔细对比了一下指标的 id 标签：

有数据的节点：/docker/5282f5...
没数据的节点：/system.slice/docker-153d1e...scope

路径明显不一致。为了解决这个”断流”问题，踩了几个坑，在这里记录一下排查和修复的全过程。

坑一：盲改 cAdvisor 启动参数

一开始我以为是 cAdvisor 的 cgroup 挂载路径偏移导致的。因为在新节点里，Docker 使用了 systemd 作为 Cgroup Driver。

于是我尝试修改 cadvisor.service 文件，加入了 --runtime_full_cgroup_path=true 参数。结果改完重启，Systemd 直接报错 Failed with result 'exit-code'。

查看 journalctl -u cadvisor -f 发现两个致命错误：

参数语法错误：我把 KillMode=process 写在了 ExecStart 后面，导致解析失败。
版本弃用：我用的是 v0.46.0 版本的 cAdvisor，这个版本已经完全弃用了 -runtime_full_cgroup_path 参数！强行加进去只会触发 flag provided but not defined 报错。

坑二：寻找消失的物理路径

既然参数没法调，我决定直接去宿主机上看看 cgroup 的实际目录层级。按照以往的经验，我执行了：

ls /sys/fs/cgroup/memory/system.slice/docker-*.scope

结果提示：文件不存在。

为了精准定位，采用反向溯源的方法，先拿到容器内主进程的 PID，然后直接看它挂载在哪里：

# 拿到容器的 PID
docker inspect -f '{{.State.Pid}}' iperf-server

# 查看对应 PID 的 cgroup (假设 PID 是 12345)
cat /proc/12345/cgroup

输出结果： 0::/system.slice/docker-153d1e883aa123826...scope

真相大白：Cgroup v1 与 v2 的代沟

看到开头的 0::，懂了。这是 Cgroup v2（统一层级）的特征签名。

根本不是 cAdvisor 挂载错了，也不是参数配错了，而是底层操作系统架构变了：

老节点跑的是 Cgroup v1，有单独的 /memory/ 目录，内核提供了最大内存使用量的统计接口，所以 cAdvisor 能读到数据。
新节点跑的是 Cgroup v2，底层去掉了 memory 目录。在 Cgroup v2 环境下，cAdvisor 获取不到历史极值，于是强行给 container_memory_max_usage_bytes 这个指标塞了一个 0。

最终方案：在 PromQL 层面无缝缝合

既然底层都不提供这个数据了，死磕 cAdvisor 配置毫无意义。解决办法是直接在查询层更换跨版本兼容的”真实内存”指标：container_memory_working_set_bytes。

但我希望能保留老节点上 max_usage 的历史数据。

利用 PromQL 的 or 逻辑，实现新老数据的缝合替换。修改 Grafana 的查询语句如下：

(container_memory_max_usage_bytes{image!=""} > 0)
or
(container_memory_working_set_bytes{image!=""})

执行逻辑：

首先尝试获取老指标。因为新节点这个值全是 0，所以 > 0 的条件会把新节点直接过滤掉。
对老节点来说，左侧条件成立，画出老指标的线。
对新节点来说，左侧为空，触发 or 逻辑，自动替补使用右侧的新指标 working_set 并在图表上画线。

保存查询，刷新面板。

总结：排查监控数据缺失问题，不要一上来就去猜参数。顺藤摸瓜，从 PID 反查 cgroup 挂载点，直接看操作系统的底层到底给了什么，从根本上解决问题。

Mac 上安装 OrbStack 替代 Docker Desktop

Wed, 01 Apr 2026 00:00:00 +0800

什么是 OrbStack

OrbStack 是一个轻量级的 Docker 替代工具，相比 Docker Desktop：

启动更快
资源占用更低
有原生 macOS GUI
免费（基本功能）

安装过程

1. 下载安装

https://orbstack.dev/download

下载完成后，双击打开 .dmg 文件，将 OrbStack 拖入 Applications 文件夹即可。

2. 启动 Docker

打开 OrbStack 应用，点击 “Start” 按钮启动 Docker 环境。

验证安装：

$ orbctl status
Running

$ docker version --format '{{.Server.Version}}'
28.5.2

配置国内镜像源

配置 Docker 的镜像源来加速拉取。

1. 创建配置文件

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "https://mirror.ccs.tencentyun.com",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}
EOF

2. 重启 Docker

在 OrbStack 菜单中：

Stop Docker
Start Docker

测试运行

$ docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

完美！🎉

参考

Mac Studio 安装 OpenClaw 多实例共存实录

Mon, 30 Mar 2026 00:00:00 +0800

最近在研究多 Agent 编排，本机已经跑着 copaw。今天心血来潮，决定把底层的 openclaw 单独拎出来跑个 UI 界面看看。

做个记录，备忘。

1. Opencode 辅助安装：一场优雅的权限绕过

为了省事，我直接唤醒了终端里的 AI 助手（Opencode，挂的 MiniMax 模型）帮我装。AI 的排错逻辑挺有意思：

它首先尝试了官方的无脑脚本：curl -fsSL https://openclaw.ai/install.sh | bash。
发现走不通，立刻切成了全局 NPM 安装：npm install -g openclaw@latest。
随后触发了经典报错：/usr/local/bin/openclaw 文件已存在，引发软链接冲突。
它的第一反应是 sudo rm 强删，但被系统的交互式密码输入卡住了（终端里的 AI 无法直接帮你输密码）。
接着它立刻放弃提权，直接用普通权限 rm -f /usr/local/bin/openclaw && npm install -g openclaw@latest。因为我当前账户对该目录有写权限，直接物理抹除并重新接管成功。

最终拿到了 OpenClaw 2026.3.28 版本。AI 时代，连写环境配置都变成了一种结对编程。

2. 端口冲突

装完后，按常规流程初始化：

openclaw setup
openclaw gateway

结果直接吃了个闭门羹：日志提示 pid 539 kelu: openclaw-gateway (*:18789)。18789 端口已经被占用了。

因为我本机还在跑着 copaw，copaw 也是将 OpenClaw 作为底层通信引擎，早就已经在后台静默拉起了一个 Gateway 守护进程，用了 18789 端口和默认的 ~/.openclaw 工作区。

3. 开启 Dev 沙盒模式

我想同时保留 copaw 的运行状态，又想自己独立玩 OpenClaw 的 Dashboard。既然不能同归于尽，那就只能物理隔离。

OpenClaw 官方提供了一个 --dev 参数，可以解决了多实例共存的问题。

启动独立网关：

openclaw --dev gateway

这行命令直接开辟了一个平行宇宙：

配置文件被隔离到了 ~/.openclaw-dev/openclaw.json
数据工作区被重定向到了 ~/.openclaw/workspace-dev
网关端口自动偏移到了 19001
甚至连局域网的 Bonjour 广播名字，都聪明地加上了后缀 kelu的Mac Studio (OpenClaw) (2) 以防冲突

4. 唤醒 UI 控制台

后台引擎在 19001 端口平稳怠速后，新开一个终端页，带上 dev 参数直连：

openclaw --dev dashboard

浏览器瞬间弹出。虽然目前版本的 Web UI 纯英文，没有任何 zh-CN 的汉化选项，但这并不妨碍。