@yyy9527/openclaw-manager 0.1.0

package/.env.example

@@ -0,0 +1,37 @@
+# 敏感变量模板（复制为 .env 后填入真实值）
+
+# Git 访问令牌（必填）
+# 用途：Issue/PR 创建、认领、状态更新、PR 审查
+# 获取路径（Gitee）：个人设置 -> 私人令牌（Personal Access Tokens）
+# 如使用 GitHub：Settings -> Developer settings -> Personal access tokens
+GIT_TOKEN=
+
+# 飞书机器人 Webhook（可选，启用通知时必填）
+# 用途：任务状态、PR 结果、积分变更通知
+# 获取路径：飞书群 -> 机器人 -> 自定义机器人 -> Webhook URL
+FEISHU_WEBHOOK_URL=
+
+# 飞书签名密钥（可选）
+# 用途：Webhook 签名校验
+# 获取路径：与 Webhook 同页面查看签名密钥
+FEISHU_SIGNING_SECRET=
+
+# npm 发布令牌（最后发布阶段使用）
+# 用途：npm publish 鉴权
+# 获取路径：npm 官网 -> Access Tokens
+NPM_TOKEN=
+
+# Ollama provider 注册占位键（非敏感）
+# 用途：让 OpenClaw 将 Ollama 识别为已注册 provider
+# 建议值：ollama-local
+OLLAMA_API_KEY=ollama-local
+
+# 厂商 Qwen（DashScope）非交互切换参数（可选）
+# 用途：`npm run set-model:qwen` 自动写入每个实例模型配置
+# 二选一即可（建议填 DASHSCOPE_API_KEY）
+DASHSCOPE_API_KEY=
+QWEN_API_KEY=
+# 默认值：qwen-max
+QWEN_MODEL=qwen-max
+# 默认值：https://dashscope.aliyuncs.com/compatible-mode/v1
+QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

package/README.md

@@ -0,0 +1,195 @@
+# OpenClaw Manager
+
+面向 macOS 的 OpenClaw 多实例部署与协作编排脚手架，支持：
+
+- 一键环境初始化与非交互安装
+- `npm run` 统一管理
+- TUI 交互
+- 飞书通知适配
+- 多实例隔离与统一命名规范
+- 里程碑提交、自测记录、问题闭环沉淀
+
+> 职责边界：脚本只负责安装、启停、重启、健康检查、日志和配置校验；任务拆分/认领/PR 协作/积分结算由 OpenClaw Skills 执行。
+
+## 1. 前置准备
+
+1. macOS（Apple Silicon / Intel）
+2. 安装并启动 Docker Desktop
+3. 准备 `.env` 中的敏感变量（Git Token、飞书 webhook 等）
+
+## 2. 快速开始
+
+```bash
+cp config/openclaw.env.example config/openclaw.env
+cp .env.example .env
+npm run setup
+npm run install
+npm run status
+npm run help
+```
+
+> 首次执行 `npm run install` 需要拉取官方镜像，可能耗时较长（取决于网络）。
+> clawhub 在 macOS 安装后，只有把 skills 安装到 `OPENCLAW_HOME_ROOT` 可见目录并挂载到容器，才能持久化并在容器内生效。
+
+## 3. 常用命令
+
+- `npm run help`：查看友好的 CLI 帮助
+- `npm run setup`：初始化环境（幂等）
+- `npm run install`：按配置启动全部实例
+- `npm run start` / `npm run stop` / `npm run restart`
+- `npm run status`：查看实例状态
+- `npm run list:claw`：列出当前配置的 claw 名称
+- `npm run start:claw -- <name>`：启动指定实例
+- `npm run stop:claw -- <name>`：停止指定实例
+- `npm run status:claw -- <name>`：查看指定实例状态
+- `npm run logs:claw -- <name>`：查看指定实例日志
+- `npm run logs`：查看日志
+- `npm run tui`：进入终端交互界面
+- `npm run tui:claw -- <name>`：进入指定容器内 OpenClaw 的对话 TUI
+- `npm run clawhub:login`：登录 clawhub，避免匿名限流影响 skills 安装
+- `npm run check-env`：检查你是否已补齐关键 `.env` 变量
+- `npm run sync-skills`：创建共享/专属 skills 目录，并优先通过 clawhub 搜索安装
+- `npm run sync-model-configs`：将各实例家目录的 `model.env` 同步到各自 `openclaw.json`
+- `npm run apply-config`：配置变更后统一生效（先同步模型配置，再重启）
+- `npm run bootstrap-models`：显式覆盖为 Ollama（需先开启覆盖开关）
+- `npm run set-model:qwen`：非交互切换到厂商 Qwen（DashScope/OpenAI 兼容）
+- `npm run health-check`：检查 Docker / Gitee 令牌与仓库 / 飞书配置可用性
+- `npm run self-test`：执行基础自测
+
+## 3.1 `--help` 与配置文件切换
+
+脚本入口支持统一全局参数：
+
+```bash
+bash ./scripts/openclaw_ctl.sh --help
+bash ./scripts/openclaw_ctl.sh --config ./config/openclaw.dev.env status
+bash ./scripts/openclaw_ctl.sh --config ./config/openclaw.prod.env --env-file ./.env.prod apply-config
+```
+
+如果通过 `npm run` 使用，也可以把参数透传给底层脚本（注意 `--`）：
+
+```bash
+npm run ctl -- --config ./config/openclaw.dev.env status
+npm run ctl -- --config ./config/openclaw.prod.env --env-file ./.env.prod apply-config
+```
+
+> 这个体验与你提到的 `webpack --config` 思路一致，适合 dev/staging/prod 多套配置并行维护。
+
+## 3.2 Git 平台切换（当前默认 Gitee）
+
+- 默认配置位于 `config/openclaw.env`（可通过 `--config` 指向其他文件）：
+  - `GIT_PLATFORM=gitee`
+  - `GIT_API_BASE=https://gitee.com/api/v5`
+  - `GIT_REPO=你的命名空间/仓库名`
+- 访问令牌放到 `.env`（或 `--env-file` 指定文件）的 `GIT_TOKEN`
+
+## 3.3 Skills 协作入口
+
+- 共享 skills 目录：`${OPENCLAW_HOME_ROOT}/shared/skills`
+- 实例专属 skills 目录：`${OPENCLAW_HOME_ROOT}/{instance}/skills`
+- clawhub 清单：`config/clawhub-skills.txt`
+- 容器挂载路径：
+  - `${OPENCLAW_HOME_ROOT}/{instance}` -> `/home/node/.openclaw`
+  - `${OPENCLAW_HOME_ROOT}/shared/skills` -> `/home/node/.openclaw/shared/skills`
+- 协作边界：
+  - 运维动作由脚本执行
+  - 需求拆分、任务认领、PR 审查、积分结算由 OpenClaw Skills 执行
+
+> `clawhub` 通过 `pnpm` 安装（`pnpm add -g clawhub`）。  
+> `sync-skills` 会先尝试安装 `find-skills`，再按检索词搜索最佳匹配并安装；遇到超时会自动重试。
+> 若出现 `Rate limit exceeded`，请先执行 `npm run clawhub:login` 再重试 `npm run sync-skills`。
+> 如果 TUI 报 `No API key found for provider "anthropic"`，先执行 `npm run apply-config`。该命令会重启容器并引导默认模型到 `ollama/qwen3.5:27b`。
+> 如果 TUI 报 `not connected to gateway`，通常是网关刚重启尚未就绪；`tui:claw` 现已内置等待逻辑，超时可执行 `npm run apply-config` 后重试。
+
+### 非交互切换到厂商 Qwen
+
+1. 在 `.env` 配置：
+   - `DASHSCOPE_API_KEY`（或 `QWEN_API_KEY`）
+   - 可选：`QWEN_MODEL`（默认 `qwen-max`）
+   - 可选：`QWEN_BASE_URL`（默认 DashScope OpenAI 兼容地址）
+2. 执行：
+
+```bash
+npm run set-model:qwen
+```
+
+该命令会自动为每个实例写入 `~/openclaws/{instance}/model.env`，再同步到家目录 `openclaw.json`。  
+最终通过 `npm run apply-config` 重启生效，无需交互式 `openclaw configure`。
+
+你也可以按实例准备模板（可选）：
+
+- `config/model-env-templates/master.env(.example)`
+- `config/model-env-templates/dev.env(.example)`
+- `config/model-env-templates/test.env(.example)`
+
+`set-model:qwen` 与 `sync-model-configs` 只会更新受控键，不会整文件覆盖你在 `model.env` 中新增的自定义键。
+
+> `apply-config` 默认不会强制回写 Ollama 模型，避免覆盖实例家目录中的厂商模型配置。  
+> 如需在 `apply-config` 后强制回写 Ollama，需同时设置：
+> - `OPENCLAW_FORCE_OLLAMA_AFTER_APPLY=true`
+> - `OPENCLAW_ALLOW_OLLAMA_OVERRIDE=true`
+>
+> `bootstrap-models` 会覆盖当前模型主配置，默认关闭，必须显式开启才会执行。
+
+## 4. 多实例统一命名规范
+
+当前架构是 **单镜像多容器**（你的判断是正确的）：每个 OpenClaw 一个独立容器，统一复用同一镜像版本。  
+
+- `agent_id`: `master|dev|test|...`
+- `container_name`: `${OPENCLAW_NAME_PREFIX}-${agent_id}`
+- `instance_name`: 来自 `OPENCLAW_INSTANCE_IDS`（例如 `master`、`dev`）
+- `data_dir`: `${OPENCLAW_HOME_ROOT}/${instance_name}`（每个实例独立“家目录”）
+- `log_dir`: `./logs/${OPENCLAW_NAME_PREFIX}-${agent_id}`
+- `port_http`: `OPENCLAW_BASE_HTTP_PORT + ordinal`
+- `container_port`: `OPENCLAW_CONTAINER_PORT`（默认 `18789`）
+- `issue_label`: `agent:${agent_id}` / `task:*` / `status:*`
+
+示例：
+
+- 实例 `master` -> `openclaw-master` / `~/openclaws/master` / `3100`
+- 实例 `dev` -> `openclaw-dev` / `~/openclaws/dev` / `3101`
+
+## 5. 固定版本策略
+
+- 当前固定版本记录在 `config/versions.lock`
+- 更新版本时需同步修改：
+  - `config/versions.lock`
+  - `config/openclaw.env`（`OPENCLAW_VERSION`）
+  - 变更说明与里程碑记录
+
+## 6. 里程碑与验收记录规范
+
+- 里程碑记录：`docs/milestones/`
+- 每步自测记录：`docs/validation/`
+- 问题与解决路径：`docs/incidents/`
+
+每个里程碑必须至少一个 Git 提交，提交信息使用中文并包含：
+
+1. 目的（为什么）
+2. 变更（做了什么）
+3. 验证（如何确认）
+
+示例提交：
+
+`feat(里程碑01): 完成多实例安装脚本与端口冲突校验，补充自测记录`
+
+## 7. 作为 npm 包使用与发布
+
+本项目已具备 CLI 包基础结构（`bin` 指向 `scripts/openclaw_ctl.sh`）。
+
+本地验证：
+
+```bash
+npm pack
+npx openclaw-manager --help
+npx clawctl --help
+```
+
+发布前建议：
+
+```bash
+npm login
+npm publish --access public
+```
+
+> 当前建议包名：`@yyy9527/openclaw-manager`。若需组织统一命名，可改为你的团队 scope。

package/config/agents.yaml

@@ -0,0 +1,22 @@
+agents:
+  - id: master
+    role: "主 OpenClaw"
+    duty: "需求理解、任务拆分、Issue 下发、PR 审查、积分结算"
+    score_rules:
+      issue_created: 5
+      review_completed: 10
+
+  - id: dev
+    role: "开发 OpenClaw"
+    duty: "认领任务、实现需求、提交 PR"
+    score_rules:
+      issue_claimed: 3
+      pr_merged: 20
+      pr_rejected: -5
+
+  - id: test
+    role: "测试 OpenClaw"
+    duty: "执行验证、提交测试结论、反馈风险"
+    score_rules:
+      validation_completed: 8
+      defect_found: 5

package/config/channels.yaml

@@ -0,0 +1,14 @@
+channels:
+  feishu:
+    enabled: true
+    event_filters:
+      - task_created
+      - task_claimed
+      - pr_opened
+      - pr_merged
+      - task_failed
+      - score_changed
+    rate_limit:
+      max_per_minute: 20
+    template:
+      title_prefix: "[OpenClaw]"

package/config/clawhub-skills.txt

@@ -0,0 +1,6 @@
+# clawhub 技能检索词清单（按需修改）
+# 每行一个“检索词”而非必须是精准 slug。
+# 脚本会优先安装 find-skills，再按检索词搜索最佳匹配进行安装。
+
+gitea
+feishu-doc-manager

package/config/model-env-templates/README.md

@@ -0,0 +1,25 @@
+# 实例模型模板（可选）
+
+用于为不同实例提供不同的模型默认值。脚本会按实例名读取：
+
+- `config/model-env-templates/<instance>.env`
+- 若不存在，再尝试 `config/model-env-templates/<instance>.env.example`
+
+## 使用方式
+
+1. 复制示例模板并改名为 `.env`（可选）：
+   - `master.env.example -> master.env`
+   - `dev.env.example -> dev.env`
+   - `test.env.example -> test.env`
+2. 修改你希望按实例区分的键值。
+3. 执行：
+
+```bash
+npm run set-model:qwen
+npm run apply-config
+```
+
+## 安全更新说明
+
+- `set-model:qwen` 与 `sync-model-configs` 只更新受控键（`MODEL_*` 核心字段）。
+- `~/openclaws/<instance>/model.env` 中的其他自定义键会被保留，不会整文件覆盖。

package/config/model-env-templates/dev.env.example

@@ -0,0 +1,10 @@
+# dev：成本优先，可用于日常迭代
+MODEL_PROVIDER_ID="openai"
+MODEL_PRIMARY="openai/qwen-plus"
+MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
+MODEL_API_KEY_ENV="DASHSCOPE_API_KEY"
+MODEL_API="openai-completions"
+MODEL_ID="qwen-plus"
+MODEL_NAME="Qwen Dev"
+MODEL_CONTEXT_WINDOW=131072
+MODEL_MAX_TOKENS=8192

package/config/model-env-templates/master.env.example

@@ -0,0 +1,10 @@
+# master：稳定主模型
+MODEL_PROVIDER_ID="openai"
+MODEL_PRIMARY="openai/qwen-max"
+MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
+MODEL_API_KEY_ENV="DASHSCOPE_API_KEY"
+MODEL_API="openai-completions"
+MODEL_ID="qwen-max"
+MODEL_NAME="Qwen Master"
+MODEL_CONTEXT_WINDOW=131072
+MODEL_MAX_TOKENS=8192

package/config/model-env-templates/test.env.example

@@ -0,0 +1,10 @@
+# test：快速反馈，可用于回归验证
+MODEL_PROVIDER_ID="openai"
+MODEL_PRIMARY="openai/qwen-turbo"
+MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
+MODEL_API_KEY_ENV="DASHSCOPE_API_KEY"
+MODEL_API="openai-completions"
+MODEL_ID="qwen-turbo"
+MODEL_NAME="Qwen Test"
+MODEL_CONTEXT_WINDOW=131072
+MODEL_MAX_TOKENS=8192

package/config/openclaw.env

@@ -0,0 +1,20 @@
+# 从 openclaw.env.example 复制而来，可按需修改。
+OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw
+OPENCLAW_VERSION=latest
+OPENCLAW_INSTANCE_IDS=master,dev,test
+OPENCLAW_NAME_PREFIX=openclaw
+OPENCLAW_BASE_HTTP_PORT=3100
+OPENCLAW_CONTAINER_PORT=18789
+OPENCLAW_HOME_ROOT=${HOME}/openclaws
+OPENCLAW_SHARED_SKILLS_DIR=${OPENCLAW_HOME_ROOT}/shared/skills
+OPENCLAW_ENABLE_CLAWHUB_SKILLS=true
+OPENCLAW_CLAWHUB_INSTALL_RETRIES=8
+OPENCLAW_FORCE_OLLAMA_AFTER_APPLY=false
+OPENCLAW_ALLOW_OLLAMA_OVERRIDE=false
+OLLAMA_BASE_URL=http://host.docker.internal:11434
+OLLAMA_MODEL=qwen3.5:27b
+OLLAMA_API_KEY=ollama-local
+GIT_PLATFORM=gitee
+GIT_REPO=yangyiyuan0825/openclaws
+GIT_API_BASE=https://gitee.com/api/v5
+FEISHU_ENABLED=true

package/config/openclaw.env.example

@@ -0,0 +1,49 @@
+# OpenClaw 运行配置（非敏感）
+
+# 镜像仓库名称（当前使用官方 GHCR）
+OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw
+
+# 固定版本（当前固定 latest，可按需锁定具体 tag）
+OPENCLAW_VERSION=latest
+
+# 多实例名称（逗号分隔）。每个名称都会成为一个独立实例名。
+OPENCLAW_INSTANCE_IDS=master,dev,test
+
+# 命名规范前缀
+OPENCLAW_NAME_PREFIX=openclaw
+
+# 端口策略：按实例序号递增，避免冲突
+# master: 3100, dev: 3101, test: 3102
+OPENCLAW_BASE_HTTP_PORT=3100
+OPENCLAW_CONTAINER_PORT=18789
+
+# 本地家目录根路径（每个实例会自动创建 `${OPENCLAW_HOME_ROOT}/${实例名}`）
+OPENCLAW_HOME_ROOT=${HOME}/openclaws
+
+# 共享技能目录（所有实例共用）
+OPENCLAW_SHARED_SKILLS_DIR=${OPENCLAW_HOME_ROOT}/shared/skills
+
+# 是否优先通过 clawhub 搜索并安装技能
+OPENCLAW_ENABLE_CLAWHUB_SKILLS=true
+# clawhub 安装重试次数（网络超时时自动重试）
+OPENCLAW_CLAWHUB_INSTALL_RETRIES=8
+# 是否在 apply-config 后强制回写 Ollama 模型（默认 false）
+OPENCLAW_FORCE_OLLAMA_AFTER_APPLY=false
+# 是否允许执行 bootstrap-models 覆盖当前主模型（默认 false）
+OPENCLAW_ALLOW_OLLAMA_OVERRIDE=false
+
+# 默认 Ollama 连接
+OLLAMA_BASE_URL=http://host.docker.internal:11434
+OLLAMA_MODEL=qwen3.5:27b
+OLLAMA_API_KEY=ollama-local
+
+# 协作平台基础信息（非敏感）
+# 当前默认使用 Gitee。若切换 GitHub，请改为:
+# GIT_PLATFORM=github
+# GIT_API_BASE=https://api.github.com
+GIT_PLATFORM=gitee
+GIT_REPO=owner/repo
+GIT_API_BASE=https://gitee.com/api/v5
+
+# 飞书通知功能开关
+FEISHU_ENABLED=true

package/config/versions.lock

@@ -0,0 +1,9 @@
+{
+  "openclaw": {
+    "image": "ghcr.io/openclaw/openclaw",
+    "version": "latest",
+    "source": "https://ghcr.io/openclaw/openclaw",
+    "locked_at": "2026-03-06",
+    "notes": "切换为可用官方GHCR镜像，后续升级需同步更新此文件和 config/openclaw.env。"
+  }
+}

package/docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  openclaw:
+    image: "${OPENCLAW_IMAGE}:${OPENCLAW_VERSION}"
+    container_name: "${OPENCLAW_NAME_PREFIX}-${OPENCLAW_INSTANCE_ID}"
+    restart: unless-stopped
+    ports:
+      - "${OPENCLAW_HTTP_PORT}:${OPENCLAW_CONTAINER_PORT}"
+    environment:
+      OLLAMA_BASE_URL: "${OLLAMA_BASE_URL}"
+      OLLAMA_MODEL: "${OLLAMA_MODEL}"
+      OLLAMA_API_KEY: "${OLLAMA_API_KEY}"
+      DASHSCOPE_API_KEY: "${DASHSCOPE_API_KEY}"
+      QWEN_API_KEY: "${QWEN_API_KEY}"
+      OPENCLAW_ROLE: "${OPENCLAW_INSTANCE_ID}"
+      GIT_PLATFORM: "${GIT_PLATFORM}"
+      GIT_REPO: "${GIT_REPO}"
+      FEISHU_ENABLED: "${FEISHU_ENABLED}"
+    volumes:
+      - "${OPENCLAW_INSTANCE_HOME_DIR}:/home/node/.openclaw"
+      - "${OPENCLAW_SHARED_SKILLS_DIR}:/home/node/.openclaw/shared/skills"
+      - "${OPENCLAW_INSTANCE_DATA_DIR}:/app/data"
+      - "${OPENCLAW_INSTANCE_LOG_DIR}:/app/logs"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@yyy9527/openclaw-manager",
+  "version": "0.1.0",
+  "description": "OpenClaw multi-instance manager for macOS with docker, TUI, and collaboration workflow.",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "openclaw-manager": "./scripts/openclaw_ctl.sh",
+    "clawctl": "./scripts/openclaw_ctl.sh"
+  },
+  "files": [
+    "scripts/",
+    "src/",
+    "config/",
+    "docker-compose.yml",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "ctl": "bash ./scripts/openclaw_ctl.sh",
+    "help": "bash ./scripts/openclaw_ctl.sh --help",
+    "setup": "bash ./scripts/setup_env.sh",
+    "install": "bash ./scripts/install_openclaw.sh",
+    "start": "bash ./scripts/openclaw_ctl.sh start",
+    "stop": "bash ./scripts/openclaw_ctl.sh stop",
+    "restart": "bash ./scripts/openclaw_ctl.sh restart",
+    "status": "bash ./scripts/openclaw_ctl.sh status",
+    "list:claw": "bash ./scripts/openclaw_ctl.sh list-claw",
+    "start:claw": "bash ./scripts/openclaw_ctl.sh start-claw",
+    "stop:claw": "bash ./scripts/openclaw_ctl.sh stop-claw",
+    "status:claw": "bash ./scripts/openclaw_ctl.sh status-claw",
+    "logs:claw": "bash ./scripts/openclaw_ctl.sh logs-claw",
+    "logs": "bash ./scripts/openclaw_ctl.sh logs",
+    "tui": "node ./src/tui/index.js",
+    "tui:claw": "bash ./scripts/openclaw_ctl.sh chat-claw",
+    "clawhub:login": "clawhub login",
+    "check-env": "bash ./scripts/openclaw_ctl.sh check-env",
+    "sync-skills": "bash ./scripts/openclaw_ctl.sh sync-skills",
+    "sync-model-configs": "bash ./scripts/openclaw_ctl.sh sync-model-configs",
+    "apply-config": "bash ./scripts/openclaw_ctl.sh apply-config",
+    "bootstrap-models": "bash ./scripts/openclaw_ctl.sh bootstrap-models",
+    "set-model:qwen": "bash ./scripts/openclaw_ctl.sh set-qwen",
+    "health-check": "bash ./scripts/openclaw_ctl.sh health-check",
+    "self-test": "bash ./scripts/openclaw_ctl.sh self-test"
+  }
+}

package/scripts/apply_config.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+CONFIG_FILE="${OPENCLAW_CONFIG_FILE:-${PROJECT_ROOT}/config/openclaw.env}"
+
+log() {
+  printf '[apply-config] %s\n' "$*"
+}
+
+load_env() {
+  [ -f "${CONFIG_FILE}" ] || {
+    printf '[apply-config][ERROR] 缺少配置文件：%s\n' "${CONFIG_FILE}" >&2
+    exit 1
+  }
+  set -a
+  # shellcheck source=/dev/null
+  source "${CONFIG_FILE}"
+  set +a
+}
+
+load_env
+log "应用配置：先同步家目录模型配置，再重建容器并引导模型"
+bash "${PROJECT_ROOT}/scripts/sync_model_configs.sh"
+bash "${PROJECT_ROOT}/scripts/openclaw_ctl.sh" stop
+bash "${PROJECT_ROOT}/scripts/openclaw_ctl.sh" start
+if [ "${OPENCLAW_FORCE_OLLAMA_AFTER_APPLY:-false}" = "true" ]; then
+  bash "${PROJECT_ROOT}/scripts/openclaw_ctl.sh" bootstrap-models
+else
+  log "已跳过强制 Ollama 模型引导（保留各实例家目录模型配置）"
+fi
+log "配置应用完成"

package/scripts/bootstrap_models.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+CONFIG_FILE="${OPENCLAW_CONFIG_FILE:-${PROJECT_ROOT}/config/openclaw.env}"
+
+log() {
+  printf '[bootstrap-models] %s\n' "$*"
+}
+
+warn() {
+  printf '[bootstrap-models][WARN] %s\n' "$*" >&2
+}
+
+project_name_for_instance() {
+  local instance_id="$1"
+  printf '%s-%s' "${OPENCLAW_NAME_PREFIX}" "${instance_id}" | tr '[:upper:]' '[:lower:]'
+}
+
+load_env() {
+  [ -f "${CONFIG_FILE}" ] || {
+    warn "缺少配置文件：${CONFIG_FILE}"
+    exit 1
+  }
+  set -a
+  # shellcheck source=/dev/null
+  source "${CONFIG_FILE}"
+  set +a
+}
+
+guard_ollama_override() {
+  if [ "${OPENCLAW_ALLOW_OLLAMA_OVERRIDE:-false}" != "true" ]; then
+    warn "已拒绝执行：bootstrap-models 会覆盖当前模型主配置。"
+    warn "如需继续，请在配置文件中显式设置 OPENCLAW_ALLOW_OLLAMA_OVERRIDE=true。"
+    exit 1
+  fi
+  log "已确认允许覆盖当前模型主配置（OPENCLAW_ALLOW_OLLAMA_OVERRIDE=true）"
+}
+
+target_model() {
+  if printf '%s' "${OLLAMA_MODEL}" | awk '/\//{found=1} END{exit found?0:1}'; then
+    printf '%s\n' "${OLLAMA_MODEL}"
+  else
+    printf 'ollama/%s\n' "${OLLAMA_MODEL}"
+  fi
+}
+
+write_models_file() {
+  local id="$1"
+  local models_file="${OPENCLAW_HOME_ROOT}/${id}/agents/main/agent/models.json"
+  mkdir -p "$(dirname "${models_file}")"
+  cat > "${models_file}" <<EOF
+{
+  "providers": {
+    "ollama": {
+      "baseUrl": "${OLLAMA_BASE_URL}",
+      "api": "ollama",
+      "models": [],
+      "apiKey": "OLLAMA_API_KEY"
+    }
+  }
+}
+EOF
+}
+
+is_instance_running() {
+  local id="$1"
+  OPENCLAW_INSTANCE_ID="${id}" \
+  OPENCLAW_INSTANCE_ORDINAL="0" \
+  OPENCLAW_HTTP_PORT="${OPENCLAW_BASE_HTTP_PORT}" \
+  OPENCLAW_CONTAINER_PORT="${OPENCLAW_CONTAINER_PORT:-18789}" \
+  OPENCLAW_INSTANCE_HOME_DIR="${OPENCLAW_HOME_ROOT}/${id}" \
+  OPENCLAW_SHARED_SKILLS_DIR="${OPENCLAW_SHARED_SKILLS_DIR:-${OPENCLAW_HOME_ROOT}/shared/skills}" \
+  OPENCLAW_INSTANCE_DATA_DIR="${OPENCLAW_HOME_ROOT}/${id}" \
+  OPENCLAW_INSTANCE_LOG_DIR="${PROJECT_ROOT}/logs/${OPENCLAW_NAME_PREFIX}-${id}" \
+  docker compose -p "$(project_name_for_instance "${id}")" -f "${PROJECT_ROOT}/docker-compose.yml" ps --status running --services | awk 'NF{found=1} END{exit found?0:1}'
+}
+
+set_model_for_instance() {
+  local id="$1"
+  local model="$2"
+  local retries=3
+  local attempt=1
+  while [ "${attempt}" -le "${retries}" ]; do
+    if OPENCLAW_INSTANCE_ID="${id}" \
+      OPENCLAW_INSTANCE_ORDINAL="0" \
+      OPENCLAW_HTTP_PORT="${OPENCLAW_BASE_HTTP_PORT}" \
+      OPENCLAW_CONTAINER_PORT="${OPENCLAW_CONTAINER_PORT:-18789}" \
+      OPENCLAW_INSTANCE_HOME_DIR="${OPENCLAW_HOME_ROOT}/${id}" \
+      OPENCLAW_SHARED_SKILLS_DIR="${OPENCLAW_SHARED_SKILLS_DIR:-${OPENCLAW_HOME_ROOT}/shared/skills}" \
+      OPENCLAW_INSTANCE_DATA_DIR="${OPENCLAW_HOME_ROOT}/${id}" \
+      OPENCLAW_INSTANCE_LOG_DIR="${PROJECT_ROOT}/logs/${OPENCLAW_NAME_PREFIX}-${id}" \
+      docker compose -p "$(project_name_for_instance "${id}")" -f "${PROJECT_ROOT}/docker-compose.yml" exec -T openclaw sh -lc "openclaw models set '${model}' >/dev/null && openclaw models status --plain" | awk -v m="${model}" 'index($0,m){ok=1} END{exit ok?0:1}'; then
+      log "实例 ${id} 模型已设置为 ${model}"
+      return 0
+    fi
+    warn "实例 ${id} 设置模型失败（${attempt}/${retries}），准备重试。"
+    sleep 2
+    attempt=$((attempt + 1))
+  done
+  return 1
+}
+
+main() {
+  load_env
+  guard_ollama_override
+  local model
+  model="$(target_model)"
+  log "目标模型：${model}"
+
+  IFS=',' read -r -a instance_list <<<"${OPENCLAW_INSTANCE_IDS}"
+  local failed=0
+  for id in "${instance_list[@]}"; do
+    write_models_file "${id}"
+    if ! is_instance_running "${id}"; then
+      warn "实例 ${id} 未运行，跳过模型引导。"
+      continue
+    fi
+    if ! set_model_for_instance "${id}" "${model}"; then
+      warn "实例 ${id} 模型引导失败。"
+      failed=1
+    fi
+  done
+
+  if [ "${failed}" -ne 0 ]; then
+    warn "存在实例模型引导失败，请重试 npm run bootstrap-models。"
+    exit 1
+  fi
+  log "模型引导完成"
+}
+
+main "$@"