@yyy9527/openclaw-manager

v0.2.3

Published

10 days ago

OpenClaw multi-instance manager for macOS with docker, TUI, and collaboration workflow.

0High
0Medium
0Low

yyy9527

OpenClaw Manager

面向 macOS 的 OpenClaw 多实例部署与协作编排脚手架，支持：

一键环境初始化与非交互安装
clawctl 命令统一管理
TUI 交互
飞书通知适配
多实例隔离与统一命名规范
里程碑提交、自测记录、问题闭环沉淀

职责边界：脚本只负责安装、启停、重启、健康检查、日志和配置校验；任务拆分/认领/PR 协作/积分结算由 OpenClaw Skills 执行。

1. 前置准备

macOS（Apple Silicon / Intel）
安装并启动 Docker Desktop
准备 .env 中的敏感变量（Git Token、飞书 webhook 等）

2. 快速开始

npm i -g @yyy9527/openclaw-manager
cp config/openclaw.env.example config/openclaw.env
cp .env.example .env
clawctl setup
clawctl deploy
clawctl status
clawctl --help

首次执行 clawctl deploy 需要拉取官方镜像，可能耗时较长（取决于网络）。 clawhub 在 macOS 安装后，只有把 skills 安装到 OPENCLAW_HOME_ROOT 可见目录并挂载到容器，才能持久化并在容器内生效。

2.1 在另一台电脑安装

在新机器上只需用 npm 安装包并按下面步骤做一次初始化即可使用。

前置：

macOS，已安装 Node.js（建议 18+）和 Docker Desktop（并已启动）
准备好 Git 令牌、飞书 webhook 等（见下方配置）

安装与首次配置：

# 全局安装（推荐指定版本以便复现）
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 等
# 如希望首次 deploy 自动切到 Qwen，设置：
# OPENCLAW_AUTO_SET_QWEN_ON_DEPLOY=true

# 方式 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   # 或你的实例名

常用命令示例（在新电脑上）：

clawctl --help
clawctl check-env
clawctl deploy
clawctl list-claw
clawctl start-claw master
clawctl status-claw master
clawctl chat-claw master

指定配置与敏感变量文件（多环境时）：

clawctl --config ./config/openclaw.prod.env --env-file ./.env.prod status

安装指定版本（例如 0.2.2）：

npm i -g @yyy9527/[email protected]

3. 常用命令

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` 与配置文件切换

脚本入口支持统一全局参数：

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 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，请先执行 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 后重试。若希望首次部署自动避免 anthropic 缺 key 问题，可在配置中开启 OPENCLAW_AUTO_SET_QWEN_ON_DEPLOY=true。

非交互切换到厂商 Qwen

在 .env 配置：
- DASHSCOPE_API_KEY（或 QWEN_API_KEY）
- 可选：QWEN_MODEL（默认 qwen-max）
- 可选：QWEN_BASE_URL（默认 DashScope OpenAI 兼容地址）
执行：

clawctl set-qwen

该命令会自动为每个实例写入 ~/openclaws/{instance}/model.env，再同步到家目录 openclaw.json。
最终通过 clawctl 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 提交，提交信息使用中文并包含：

目的（为什么）
变更（做了什么）
验证（如何确认）

示例提交：

feat(里程碑01): 完成多实例安装脚本与端口冲突校验，补充自测记录

7. 作为 npm 包使用与发布

本项目已具备 CLI 包基础结构（bin 指向 scripts/openclaw_ctl.sh）。

本地验证：

npm pack
npx @yyy9527/openclaw-manager --help
npx @yyy9527/openclaw-manager status

发布前建议：

npm login
npm publish --access public

使用 .env 中的 NPM_TOKEN 发布时（例如 CI 或本机已配置）：

# 在项目根目录
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。