@yyy9527/openclaw-manager 0.1.2 → 0.2.2

package/README.md

@@ -3,7 +3,7 @@
 面向 macOS 的 OpenClaw 多实例部署与协作编排脚手架，支持：
 
 - 一键环境初始化与非交互安装
-- `npm run` 统一管理
+- `clawctl` 命令统一管理
 - TUI 交互
 - 飞书通知适配
 - 多实例隔离与统一命名规范
@@ -20,53 +20,111 @@
 ## 2. 快速开始
 
 ```bash
+npm i -g @yyy9527/openclaw-manager
 cp config/openclaw.env.example config/openclaw.env
 cp .env.example .env
-npm run setup
-npm run deploy
-npm run status
-npm run help
+clawctl setup
+clawctl deploy
+clawctl status
+clawctl --help
 ```
 
-> 首次执行 `npm run deploy` 需要拉取官方镜像，可能耗时较长（取决于网络）。
+> 首次执行 `clawctl deploy` 需要拉取官方镜像，可能耗时较长（取决于网络）。
 > clawhub 在 macOS 安装后，只有把 skills 安装到 `OPENCLAW_HOME_ROOT` 可见目录并挂载到容器，才能持久化并在容器内生效。
 
+### 2.1 在另一台电脑安装
+
+在新机器上只需用 npm 安装包并按下面步骤做一次初始化即可使用。
+
+**前置：**
+
+- macOS，已安装 **Node.js**（建议 18+）和 **Docker Desktop**（并已启动）
+- 准备好 Git 令牌、飞书 webhook 等（见下方配置）
+
+**安装与首次配置：**
+
+```bash
+# 全局安装（推荐指定版本以便复现）
+npm i -g @yyy9527/openclaw-manager
+
+# 进入包所在目录（全局安装时通常在 node 的 lib/node_modules 下），或从本仓库复制配置到任意目录
+# 方式 A：从本仓库 clone 后，在仓库根目录操作
+cd /path/to/docker-claw
+cp config/openclaw.env.example config/openclaw.env
+cp .env.example .env
+# 编辑 .env 和 config/openclaw.env，填入 GIT_TOKEN、FEISHU_WEBHOOK_URL 等
+
+# 方式 B：仅用包内自带默认配置（需先找到包路径）
+# npm root -g 可查看全局 node_modules 路径，包名 @yyy9527/openclaw-manager
+# 复制该包内 config/openclaw.env.example -> config/openclaw.env，.env.example -> .env 并编辑
+
+# 使用默认配置时，clawctl 会读取「当前工作目录」下的 config/openclaw.env 与 .env
+# 因此建议：新建一个目录如 ~/openclaw-workspace，把 .env 和 config/openclaw.env 放进去，之后在该目录下执行 clawctl
+cd ~/openclaw-workspace
+clawctl setup
+clawctl deploy
+clawctl list-claw
+clawctl status-claw master   # 或你的实例名
+```
+
+**常用命令示例（在新电脑上）：**
+
+```bash
+clawctl --help
+clawctl check-env
+clawctl deploy
+clawctl list-claw
+clawctl start-claw master
+clawctl status-claw master
+clawctl chat-claw master
+```
+
+指定配置与敏感变量文件（多环境时）：
+
+```bash
+clawctl --config ./config/openclaw.prod.env --env-file ./.env.prod status
+```
+
+安装指定版本（例如 0.2.2）：
+
+```bash
+npm i -g @yyy9527/openclaw-manager@0.2.2
+```
+
 ## 3. 常用命令
 
-- `npm run help`：查看友好的 CLI 帮助
-- `npm run setup`：初始化环境（幂等）
-- `npm run deploy`：按配置启动全部实例
-- `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`：执行基础自测
+- `clawctl --help`：查看友好的 CLI 帮助
+- `clawctl setup`：初始化环境（幂等）
+- `clawctl deploy`：按配置启动全部实例
+- `clawctl start|stop|restart|status`
+- `clawctl list-claw`：列出当前配置的 claw 名称
+- `clawctl start-claw <name>`：启动指定实例
+- `clawctl stop-claw <name>`：停止指定实例
+- `clawctl status-claw <name>`：查看指定实例状态
+- `clawctl logs-claw <name>`：查看指定实例日志
+- `clawctl logs`：查看日志
+- `clawctl tui`：进入终端交互界面
+- `clawctl chat-claw <name>`：进入指定容器内 OpenClaw 的对话 TUI
+- `clawctl check-env`：检查你是否已补齐关键 `.env` 变量
+- `clawctl sync-skills`：创建共享/专属 skills 目录，并优先通过 clawhub 搜索安装
+- `clawctl sync-model-configs`：将各实例家目录的 `model.env` 同步到各自 `openclaw.json`
+- `clawctl apply-config`：配置变更后统一生效（先同步模型配置，再重启）
+- `clawctl bootstrap-models`：显式覆盖为 Ollama（需先开启覆盖开关）
+- `clawctl set-qwen`：非交互切换到厂商 Qwen（DashScope/OpenAI 兼容）
+- `clawctl health-check`：检查 Docker / Gitee 令牌与仓库 / 飞书配置可用性
+- `clawctl self-test`：执行基础自测
 
 ## 3.1 `--help` 与配置文件切换
 
 脚本入口支持统一全局参数：
 
 ```bash
-openclaw-manager --help
-openclaw-manager --config ./config/openclaw.dev.env status
-openclaw-manager --config ./config/openclaw.prod.env --env-file ./.env.prod apply-config
+clawctl --help
+clawctl --config ./config/openclaw.dev.env status
+clawctl --config ./config/openclaw.prod.env --env-file ./.env.prod apply-config
 ```
 
-如果通过 `npm run` 使用，也可以把参数透传给底层脚本（注意 `--`）：
+如果在仓库开发态通过 `npm run` 使用，也可以把参数透传给底层脚本（注意 `--`）：
 
 ```bash
 npm run ctl -- --config ./config/openclaw.dev.env status
@@ -97,9 +155,9 @@ npm run ctl -- --config ./config/openclaw.prod.env --env-file ./.env.prod apply-
 
 > `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` 后重试。
+> 若出现 `Rate limit exceeded`，请先执行 `clawhub login` 再重试 `clawctl sync-skills`。
+> 如果 TUI 报 `No API key found for provider "anthropic"`，先执行 `clawctl apply-config`。
+> 如果 TUI 报 `not connected to gateway`，通常是网关刚重启尚未就绪；`chat-claw` 内置等待逻辑，超时可执行 `clawctl apply-config` 后重试。
 
 ### 非交互切换到厂商 Qwen
 
@@ -110,11 +168,11 @@ npm run ctl -- --config ./config/openclaw.prod.env --env-file ./.env.prod apply-
 2. 执行：
 
 ```bash
-npm run set-model:qwen
+clawctl set-qwen
 ```
 
 该命令会自动为每个实例写入 `~/openclaws/{instance}/model.env`，再同步到家目录 `openclaw.json`。  
-最终通过 `npm run apply-config` 重启生效，无需交互式 `openclaw configure`。
+最终通过 `clawctl apply-config` 重启生效，无需交互式 `openclaw configure`。
 
 你也可以按实例准备模板（可选）：
 
@@ -192,4 +250,13 @@ npm login
 npm publish --access public
 ```
 
-> 当前建议包名：`@yyy9527/openclaw-manager`。若需组织统一命名，可改为你的团队 scope。
+使用 `.env` 中的 `NPM_TOKEN` 发布时（例如 CI 或本机已配置）：
+
+```bash
+# 在项目根目录
+printf '//registry.npmjs.org/:_authToken=%s\n' "${NPM_TOKEN}" > .npmrc
+export NPM_TOKEN   # 若未导出，先 source .env 或 export NPM_TOKEN=你的令牌
+npm publish --access public
+```
+
+> 当前包名：`@yyy9527/openclaw-manager`。CLI 主命令为 `clawctl`。

package/config/openclaw.test.env

@@ -0,0 +1,20 @@
+# 测试配置：单实例 xiaomo（用于包流程自测）
+OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw
+OPENCLAW_VERSION=latest
+OPENCLAW_INSTANCE_IDS=xiaomo
+OPENCLAW_NAME_PREFIX=openclaw
+OPENCLAW_BASE_HTTP_PORT=3200
+OPENCLAW_CONTAINER_PORT=18789
+OPENCLAW_HOME_ROOT=${HOME}/openclaws
+OPENCLAW_SHARED_SKILLS_DIR=${OPENCLAW_HOME_ROOT}/shared/skills
+OPENCLAW_ENABLE_CLAWHUB_SKILLS=false
+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/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@yyy9527/openclaw-manager",
-  "version": "0.1.2",
+  "version": "0.2.2",
   "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"
+    "clawctl": "scripts/openclaw_ctl.sh"
   },
   "files": [
     "scripts/",
@@ -42,6 +41,7 @@
     "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"
+    "self-test": "bash ./scripts/openclaw_ctl.sh self-test",
+    "test": "bash ./scripts/test_create_claw.sh"
   }
 }

package/scripts/openclaw_ctl.sh

@@ -1,7 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOURCE_PATH="${BASH_SOURCE[0]}"
+while [ -L "${SOURCE_PATH}" ]; do
+  LINK_DIR="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
+  LINK_TARGET="$(readlink "${SOURCE_PATH}")"
+  if [[ "${LINK_TARGET}" != /* ]]; then
+    SOURCE_PATH="${LINK_DIR}/${LINK_TARGET}"
+  else
+    SOURCE_PATH="${LINK_TARGET}"
+  fi
+done
+SCRIPT_DIR="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
 PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 DEFAULT_CONFIG_FILE="${PROJECT_ROOT}/config/openclaw.env"
 DEFAULT_DOTENV_FILE="${PROJECT_ROOT}/.env"
@@ -14,7 +24,7 @@ usage() {
 OpenClaw Manager CLI（多实例运维入口）
 
 用法:
-  openclaw-manager [--config <path>] [--env-file <path>] <command> [args]
+  clawctl [--config <path>] [--env-file <path>] <command> [args]
 
 全局参数:
   -h, --help             显示帮助
@@ -40,8 +50,8 @@ OpenClaw Manager CLI（多实例运维入口）
   self-test
 
 示例:
-  openclaw-manager --config ./config/openclaw.dev.env status
-  openclaw-manager --env-file ./.env.prod start-claw master
+  clawctl --config ./config/openclaw.dev.env status
+  clawctl --env-file ./.env.prod start-claw master
 EOF
 }
 
@@ -122,7 +132,7 @@ chat_with_claw() {
   local running_service
   running_service="$(run_compose_for_instance "${claw_name}" ps --status running --services 2>/dev/null | awk 'NF{print $1; exit}')"
   if [ "${running_service}" != "openclaw" ]; then
-    echo "实例 ${claw_name} 当前未运行，请先执行: npm run start-claw -- ${claw_name}" >&2
+    echo "实例 ${claw_name} 当前未运行，请先执行: clawctl start-claw ${claw_name}" >&2
     exit 1
   fi
 
@@ -131,7 +141,7 @@ chat_with_claw() {
   until run_compose_for_instance "${claw_name}" exec -T openclaw sh -lc 'openclaw health >/dev/null 2>&1'; do
     waited=$((waited + 2))
     if [ "${waited}" -ge "${max_wait}" ]; then
-      echo "实例 ${claw_name} 网关尚未就绪（等待 ${max_wait}s 超时）。可先执行: npm run apply-config" >&2
+      echo "实例 ${claw_name} 网关尚未就绪（等待 ${max_wait}s 超时）。可先执行: clawctl apply-config" >&2
       exit 1
     fi
     sleep 2
@@ -269,7 +279,7 @@ case "${command}" in
     ;;
   chat-claw)
     claw_name="${2:-}"
-    [ -n "${claw_name}" ] || { echo "用法: openclaw-manager chat-claw <name>" >&2; exit 1; }
+    [ -n "${claw_name}" ] || { echo "用法: clawctl chat-claw <name>" >&2; exit 1; }
     chat_with_claw "${claw_name}"
     ;;
   status-claw)

package/scripts/test_create_claw.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# 测试用例：使用 test 配置执行「创建龙虾」流程并做简单断言
+# 用于回归：check-env -> deploy -> list-claw 含 xiaomo -> status-claw xiaomo 成功
+set -euo pipefail
+
+SOURCE_PATH="${BASH_SOURCE[0]}"
+while [ -L "${SOURCE_PATH}" ]; do
+  LINK_DIR="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
+  LINK_TARGET="$(readlink "${SOURCE_PATH}")"
+  if [[ "${LINK_TARGET}" != /* ]]; then
+    SOURCE_PATH="${LINK_DIR}/${LINK_TARGET}"
+  else
+    SOURCE_PATH="${LINK_TARGET}"
+  fi
+done
+SCRIPT_DIR="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+CONFIG="${PROJECT_ROOT}/config/openclaw.test.env"
+ENV_FILE="${PROJECT_ROOT}/.env"
+CTL="${PROJECT_ROOT}/scripts/openclaw_ctl.sh"
+
+if [ ! -f "${ENV_FILE}" ]; then
+  echo "跳过 deploy：未找到 .env，请复制 .env.example 为 .env 并填写后重试。仅执行 list-claw/status-claw 断言（需已有 xiaomo 容器）。"
+  SKIP_DEPLOY=1
+else
+  SKIP_DEPLOY=0
+fi
+
+run_ctl() {
+  OPENCLAW_CONFIG_FILE="${CONFIG}" OPENCLAW_DOTENV_FILE="${ENV_FILE}" bash "${CTL}" "$@"
+}
+
+echo "=== 1. check-env ==="
+run_ctl check-env
+
+if [ "${SKIP_DEPLOY}" = 0 ]; then
+  echo "=== 2. deploy（test 配置单实例 xiaomo）==="
+  run_ctl deploy
+else
+  echo "=== 2. 跳过 deploy ==="
+fi
+
+echo "=== 3. list-claw（断言含 xiaomo）==="
+list_out="$(run_ctl list-claw)"
+echo "${list_out}"
+if ! echo "${list_out}" | grep -q 'xiaomo'; then
+  echo "断言失败：list-claw 输出中未包含 xiaomo" >&2
+  exit 1
+fi
+
+echo "=== 4. status-claw xiaomo ==="
+run_ctl status-claw xiaomo
+
+echo "=== 测试通过 ==="