New:Microsoft Teams Notifications Are Now Available in Socket.Learn more →

Get Started

moticlaw

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

Package was removed

Sorry, it seems this package was removed from the registry

moticlaw

Thin package-manager launcher for MotiClaw

latest

npm

Version: 0.1.0

Version published: 6 months ago

Maintainers: 1

Created: 6 months ago

Source

MotiClaw

一个以本地部署为主、面向 OpenClaw 的后台骨架（当前仅支持本地接入），提供：

/agents 智能体工作区卡片网格
/tasks 任务看板（创建/派发/提交/审核）
/training 培训闭环（onboarding confirm / run / gate）
/leaderboard 积分榜

架构（ASCII）

Browser (Next.js UI)
        |
        v
  Next.js (web:3000)
  - shadcn/ui 风格组件
  - phosphor icons
  - /api/* rewrite
        |
        v
FastAPI (api:8088)
        |
        v
   SQLite DB

Runtime Action Infrastructure（项目级基础设施）

MotiClaw 已开始把“网页点一下 -> 本地处理”统一收敛到 Runtime Action Infrastructure。

核心链路：

Browser UI
  -> Runtime Action API
    -> Job Broker
      -> Local Executor / ActionSpec
        -> Event Stream back to Browser

这套机制用于统一承接：

Hermes / OpenClaw 安装与更新
本地修复动作
后续 Git / Docker / FFmpeg / Agent 本地操作

详细说明见：docs/reference/runtime-action-infrastructure.md

技术栈说明

后端：FastAPI + SQLite
前端：Next.js App Router + Tailwind CSS v4
UI 组件：shadcn/ui 风格（Button/Card/Badge 等基础组件）
图标：Phosphor Icons（@phosphor-icons/react）

宝塔式安装漏斗（推荐）

首选入口不是手工 docker compose up，而是统一走 moticlaw 安装漏斗：

git clone / 进入仓库
  -> ./moticlaw bootstrap
    -> 自动安装全局命令 moticlaw
      -> 本地健康检查
      -> 后续直接使用 moticlaw
        -> moticlaw status / doctor / url / onboard
          -> 如需外部访问，再执行 moticlaw expose quick

最小命令：

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
./moticlaw bootstrap

说明：

bootstrap 会自动检查 Docker / Compose、补 .env、执行 docker compose up -d --build
bootstrap 成功后会尝试安装全局 moticlaw 命令；后续可直接输入 moticlaw 打开命令面板
moticlaw onboard 会自动打开默认浏览器进入本地首页
bootstrap 首次成功时，终端会直接展示默认管理员 openclaw 的首次登录临时密码一次
只有本地 API /healthz、关键后端路由契约（含 rescue-center）和 Web /agents 都通过，才算本地安装成功
默认不依赖任何第三方 tunnel，先保证控制面本地可用
如果只是临时把站点分享给外部，再显式执行 ./moticlaw expose quick
后续统一用 ./moticlaw status、./moticlaw doctor、./moticlaw repair local、./moticlaw expose quick、./moticlaw repair tunnel、./moticlaw url

公开一键安装入口

如果你要给用户或 Agent 一个直接可复制的安装入口，可以用这两条：

curl -fsSL https://moticlaw.com/install.sh | bash

Invoke-WebRequest https://moticlaw.com/install.ps1 -OutFile $env:TEMP\moticlaw-install.ps1
powershell -ExecutionPolicy Bypass -File $env:TEMP\moticlaw-install.ps1

仓库里的 install.sh / install.ps1 现在按 Native Release 方式工作：会读取 release manifest，下载对应平台安装包，校验 checksum，解压到本地目录并启动本地服务。

如果你习惯用包管理器安装，也可以直接：

npm i -g moticlaw

pnpm add -g moticlaw

安装后执行：

moticlaw status

如果 Docker Hub 在你的网络里不稳定，可以先在安装目录 .env 里覆盖基础镜像：

MOTICLAW_PYTHON_BASE_IMAGE=你可访问的 python:3.11-slim 镜像
MOTICLAW_DOCKER_CLI_BASE_IMAGE=你可访问的 docker:27-cli 镜像

遇到 failed to resolve source metadata 时，bootstrap 和 repair local 也会提示这两个变量。

如果你想手工安装或修复全局命令，也可以执行：

./moticlaw install-cli

安装完成后，推荐入口会变成：

moticlaw

开源一键部署（给 Agent）

如果你希望用小龙虾 / Codex / Claude Code 自动部署，请直接发送下面提示词。部署完成后会通过安装漏斗尝试生成公网访问地址并回传给用户。

GitHub -> Docker 部署 -> 本地验证 -> 隧道服务 -> 外部访问地址 -> 回传用户

你是部署代理，请按以下步骤完成 MotiClaw 部署并返回公网访问地址：
1. git clone 仓库并进入目录。
2. 执行统一安装命令：
   ./moticlaw bootstrap
3. 如果 bootstrap 失败，继续执行：
   ./moticlaw doctor
   ./moticlaw repair local
4. 如果需要给用户一个临时公网入口，再执行：
   ./moticlaw expose quick
5. 用以下命令读取入口地址：
   ./moticlaw url
6. 将公网访问地址发送给用户；若当前没有公网地址，也要说明本地 Web 入口与失败原因。
7. 回到 http://127.0.0.1:3000/agents 读取页面“Agent 提示词”，按提示继续完成本地接入。

手工启动（高级模式）

0) 配置环境变量（含生图密钥）

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
cp .env.example .env

至少需要填写以下字段之一：

AGENT_SCENE_APIMART_API_TOKEN（推荐）
AGENT_SCENE_OPENROUTER_API_KEY（备用）

如果要启用“飞书用户凭证私聊 / OAuth 回调”，还需要配置：

OPENCLAW_PUBLIC_BASE_URL

例如：

OPENCLAW_PUBLIC_BASE_URL=https://ops.example.com

系统会自动拼出回调地址：

https://ops.example.com/api/agents/hr/user-auth/callback

1) 启动 API

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8088 --reload

1.5) 一键启动本地开发栈（推荐）

./scripts/local_dev.sh up

这个命令会同时在后台启动：

后端：uvicorn app.main:app --reload（127.0.0.1:8088）
前端：next dev --webpack（127.0.0.1:3000）

特点：

适合本地开发与热更新
进程会脱离当前终端，关闭终端后仍可继续运行
日志固定写到 tmp/dev-logs/

常用命令：

./scripts/local_dev.sh status
./scripts/local_dev.sh logs
./scripts/local_dev.sh down
./scripts/local_dev.sh restart

2) 启动 Web

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw/web
npm install
npm run dev

说明：

npm run dev 会启动 next dev --webpack，适合日常本地开发和热更新。
如果你想做一次生产态构建验证，请执行 npm run build && npm run start。这条默认构建不会开启浏览器混淆。
如果你是在做正式发布或镜像打包，请显式执行 npm run build:release，或在 Docker 构建时传入 --build-arg ENABLE_BROWSER_OBFUSCATION=1。
如果你要显式测试 Turbopack，再执行 npm run dev:turbopack。
默认 .next 构建产物在运行中的 Web 进程之间不能热替换；项目现在会阻止你在已有本地 Web 进程运行时直接覆盖默认 .next。

访问：

Web: http://127.0.0.1:3000/agents
API Docs: http://127.0.0.1:8088/docs

说明：

前端会通过 /api/* rewrite 到后端 API。
npm run dev 是开发态链路，代码改动后会热更新；npm run build && npm run start 是本地稳定验证链路，需要手动重建。
开发态与正式本地入口统一使用 3000；不要再额外起 3003 之类临时端口，否则 repair/doctor 与你实际访问的入口会不一致。

Docker 开发态实时预览（推荐给需要容器隔离的开发者）

如果你不想把 Python / Node 依赖直接装在宿主机，可以单独使用开发态 compose：

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
cp .env.example .env
docker compose -f docker-compose.dev.yml up --build

后续日常启动可直接执行：

docker compose -f docker-compose.dev.yml up

架构如下：

宿主机源码
  ├─ 挂载到 moticlaw-dev-api
  │   └─ uvicorn --reload
  └─ 挂载到 moticlaw-dev-web
      └─ next dev --webpack
           └─ HMR / 增量编译

适用场景：

需要实时预览，但不想每次改代码就重新 build 镜像
需要容器隔离依赖环境

注意：

第一次 up --build 会构建开发镜像，用于装依赖；后续改业务代码不需要重新构建。
如果你改了 requirements.txt 或 web/package*.json，再重新执行一次 up --build 即可。
开发态 compose 使用独立的 project name，与生产 docker-compose.yml 隔离，避免网络和卷互相影响。
开发态 Web 入口同样固定为 http://127.0.0.1:3000，与正式本地入口保持一致。
开发态默认不安装 LibreOffice / CJK 字体、Playwright，也不安装场景生图图像处理依赖；这样首启更快。
如果你需要在开发态里验证 office 转 PDF，可执行： INSTALL_OFFICE_TOOLS=1 docker compose -f docker-compose.dev.yml up --build
如果你需要在开发态容器内跑 Playwright，可执行： INSTALL_PLAYWRIGHT=1 docker compose -f docker-compose.dev.yml up --build
如果你需要在开发态里真正执行场景生图，可执行： INSTALL_SCENE_TOOLS=1 docker compose -f docker-compose.dev.yml up --build

Docker 本地启动（高级模式，可跳过）

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
cp .env.example .env
# 编辑 .env，写入生图密钥
docker compose up -d --build

服务端口（均仅绑定 127.0.0.1）：

8088：FastAPI API
3000：Next.js Web

说明：Docker 运行时会只读挂载 /root/.openclaw，用于自动同步真实 agent 列表（避免只显示种子 6 个）。另外，场景生图逻辑已经内置在后端：默认按 task_id 续轮询 APIMart，提交前失败才会走 OpenRouter 兜底，避免重复扣费。

这条链路是发布态验证路径，适合安装、验收和部署，不适合日常开发时追求实时预览。代码改动后需要重新构建。

companion daemon（受控恢复入口）

当主后端不可达时，恢复动作由本机 companion daemon 接管，而不是让前端拼接任意 bash。它只开放固定 allowlist：

start_backend
restart_backend
status
logs

默认监听：

http://127.0.0.1:18089

前端通过同源的 /api/local-control/* 代理到 OPENCLAW_COMPANION_BASE_URL，这样浏览器不用直连 companion。

状态快照默认会落到 /data/companion/state.json，里面保留最近一次安全状态、失败原因和 job 摘要。

在 Docker 本地模式下，docker compose up -d --build 会同时拉起主后端和 companion。只想单独验证 companion 时，可只起这一项：

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
docker compose up -d --build moticlaw-companion

如果你在开发态 compose 里运行：

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
docker compose -f docker-compose.dev.yml up -d --build moticlaw-dev-companion

固定命令 contract 如下：

start_backend -> docker compose -f docker-compose.yml up -d --build moticlaw
restart_backend -> docker compose -f docker-compose.yml restart moticlaw
status -> docker compose -f docker-compose.yml ps moticlaw
logs -> docker compose -f docker-compose.yml logs --no-color --tail 120 moticlaw

开发态对应目标是 moticlaw-dev-api，compose 文件切换到 docker-compose.dev.yml。

Linux 宿主机常驻模式可以直接安装 systemd 服务：

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
sudo cp deploy/systemd/moticlaw-companion.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now moticlaw-companion.service

停止 companion 并回到纯手工 fallback：

sudo systemctl disable --now moticlaw-companion.service
docker compose stop moticlaw-companion
docker compose -f docker-compose.dev.yml stop moticlaw-dev-companion

如果你想彻底回退到没有 companion 的状态，除了停掉服务，还可以把 OPENCLAW_COMPANION_BASE_URL 清空，然后重启 Web。

前端发布脚本（可选）

以后前端发布推荐固定使用脚本，而不是手工 build + up：

cd /root/moticlaw
git pull origin main
./scripts/deploy_web.sh

这个脚本会做 4 件事：

git 当前提交
  -> docker compose build --no-cache moticlaw-web
    -> force recreate web 容器
      -> 校验 http://127.0.0.1:3000/build-info 返回的 SHA 和 build time

页面侧边栏底部也会显示当前运行中的 Build SHA，方便确认线上是否已经切到最新版本。

飞书用户凭证私聊回调域名（可选）

如果你要启用“以人类身份给 Agent 私聊发消息”，必须提供一个公网 HTTPS 域名，并在 .env 中配置：

OPENCLAW_PUBLIC_BASE_URL=https://ops.example.com

要求：

域名必须解析到当前部署机器

VPS / ECS 公网访问（正式方案）

推荐区分两种模式：

模式 A: 已有反向代理（当前 racknerd 推荐）
公网/域名
  -> 宝塔 / Nginx Proxy Manager / Nginx
    -> 127.0.0.1:3000
      -> moticlaw-web
        -> /api/*
          -> moticlaw:8088

模式 B: 干净 VPS / ECS
公网/域名
  -> Caddy (80/443)
    -> moticlaw-web:3000
      -> moticlaw:8088

模式 C: 公网 IP + 高位端口
公网用户
  -> http://<公网IP>:13000
    -> moticlaw-web:3000
      -> moticlaw:8088

模式 A：已有反代（宝塔 / NPM / Nginx）

适合：

当前服务器 80/443 已被其他反代占用
想像宝塔一样在面板里加一个站点或反代规则

做法：

docker compose up -d --build
在 .env 里设置：

OPENCLAW_PUBLIC_BASE_URL=https://ops.example.com

在你的反代面板里把域名流量转发到：

http://127.0.0.1:3000

说明：

这种模式下，MotiClaw 自己不占用 80/443
适合当前 racknerd，因为这台机器上已有其他反代服务

模式 B：干净 VPS / ECS 内置公网网关

适合：

新机器，没有现成宝塔 / NPM / Nginx
希望项目自己承接 80/443

配置示例：

OPENCLAW_PUBLIC_BASE_URL=https://ops.example.com
OPENCLAW_PUBLIC_SITE_ADDRESS=ops.example.com

如果暂时没有域名，只想用公网 IP 访问：

OPENCLAW_PUBLIC_BASE_URL=http://<公网IP>
OPENCLAW_PUBLIC_SITE_ADDRESS=http://<公网IP>

启动命令：

docker compose -f docker-compose.yml -f docker-compose.public.yml up -d --build

模式 C：像宝塔一样先用公网 IP + 端口访问

适合：

还没有域名
想先验证“部署完成后外部能不能打开”
不想占用当前机器的 80/443

配置示例：

OPENCLAW_PUBLIC_MODE=public-port
OPENCLAW_PUBLIC_HOST_IP=<公网IP>
OPENCLAW_PUBLIC_WEB_PORT=13000
OPENCLAW_PUBLIC_BASE_URL=http://<公网IP>:13000

启动命令：

docker compose -f docker-compose.yml -f docker-compose.public-port.yml up -d --build

访问示例：

http://<公网IP>:13000/login
http://<公网IP>:13000/start

注意：

需要在云安全组 / 防火墙中放行 13000
这种模式适合“先公网可达”，不是长期 HTTPS 最佳方案
后续如果有域名，可升级到 existing-proxy 或 caddy 模式

GitHub -> 远端部署

新增脚本：

scripts/deploy_remote_from_github.sh

默认推荐直接使用：

PUBLIC_MODE=auto

auto 会按以下顺序自动判断：

已有 Nginx Proxy Manager / 宝塔式反代
  -> existing-proxy

否则如果 80/443 空闲
  -> caddy

否则
  -> public-port

最简示例：

DEPLOY_HOST=racknerd \
DEPLOY_DIR=/root/moticlaw \
DEPLOY_REPO_URL=git@moticlaw:Mileson/moticlaw.git \
PUBLIC_MODE=auto \
PUBLIC_HOST_IP=<公网IP> \
./scripts/deploy_remote_from_github.sh

已有反代模式示例：

DEPLOY_HOST=racknerd \
DEPLOY_DIR=/root/moticlaw \
DEPLOY_REPO_URL=git@moticlaw:Mileson/moticlaw.git \
PUBLIC_MODE=existing-proxy \
PUBLIC_BASE_URL=https://ops.example.com \
./scripts/deploy_remote_from_github.sh

干净 VPS / ECS + Caddy 模式示例：

DEPLOY_HOST=my-vps \
DEPLOY_DIR=/root/moticlaw \
DEPLOY_REPO_URL=git@github.com:your-org/moticlaw.git \
PUBLIC_MODE=caddy \
PUBLIC_BASE_URL=https://ops.example.com \
PUBLIC_SITE_ADDRESS=ops.example.com \
./scripts/deploy_remote_from_github.sh

公网 IP + 端口模式示例：

DEPLOY_HOST=my-vps \
DEPLOY_DIR=/root/moticlaw \
DEPLOY_REPO_URL=git@github.com:your-org/moticlaw.git \
PUBLIC_MODE=public-port \
PUBLIC_HOST_IP=<公网IP> \
PUBLIC_WEB_PORT=13000 \
./scripts/deploy_remote_from_github.sh

这条链路的意义是：

本地开发
  -> git push 到私有 GitHub
    -> 远端 clone / fetch / reset
      -> docker compose up -d --build
        -> 通过公网 IP / 域名访问

反向代理必须把 https://ops.example.com 转发到当前项目
飞书开放平台里必须把以下地址加入重定向 URL 白名单：

https://ops.example.com/api/agents/hr/user-auth/callback

推荐做法：

DNS
  -> ops.example.com 指向公网 IP
  -> Nginx Proxy Manager / Caddy / Nginx 反代到 moticlaw-web / moticlaw
  -> .env 配置 OPENCLAW_PUBLIC_BASE_URL
  -> 飞书应用加入 redirect_uri 白名单

这样后续开源给其他人时，只需要替换自己的域名和 DNS，不需要改代码。

远程访问（高级模式，可跳过）

默认 ./moticlaw bootstrap 不会主动创建公网入口。如果你需要一个临时外部访问地址，可先执行：

./moticlaw expose quick

如果你不想走 quick tunnel，或者需要自己维护 SSH/内网穿透，再看这一节。

默认 docker-compose.yml 已绑定本机回环地址，不直接暴露公网端口。

如需远程访问，可使用项目级隧道配置文件：

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
cp scripts/tunnel.env.example scripts/tunnel.env

配置 scripts/tunnel.env 中的云主机信息后，可选两种方式：

一次性隧道（前台运行，适合临时访问）

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
./scripts/open_secure_tunnel.sh
LOCAL_PORT=13000 REMOTE_PORT=3000 ./scripts/open_secure_tunnel.sh

持久连接器（推荐，launchd + autossh 自动重连；单个 SSH 会话同时转发 Web + API）

cd /Users/mileson/Workspace/AI\ 元宇宙/moticlaw
brew install autossh
./scripts/install_launchd_tunnels.sh

安装后，本地浏览器访问：

API: http://127.0.0.1:18088/docs
Web: http://127.0.0.1:13000/agents

M1 API 覆盖

GET /healthz
GET /api/agents
POST /api/agents/sync
GET /api/tasks
POST /api/tasks
GET /api/tasks/{task_id}
POST /api/tasks/{task_id}/dispatch
POST /api/tasks/{task_id}/submit
POST /api/tasks/{task_id}/review
POST /api/onboarding/confirm
GET /api/training/runs
POST /api/training/runs
POST /api/training/runs/{run_id}/gate
GET /api/leaderboard

强约束说明

任务创建必须有 creator_type + creator_id
任务必须单一 assignee_agent_id
审核 approved 时必须提供 receipt
creator_type=agent 时，receipt.include_creator_agent_id=true

FAQs

What is moticlaw?

Is moticlaw well maintained?

Package last updated on 19 Apr 2026

moticlaw

MotiClaw

架构（ASCII）

Runtime Action Infrastructure（项目级基础设施）

技术栈说明

宝塔式安装漏斗（推荐）

公开一键安装入口

开源一键部署（给 Agent）

手工启动（高级模式）

0) 配置环境变量（含生图密钥）

1) 启动 API

1.5) 一键启动本地开发栈（推荐）

2) 启动 Web

Docker 开发态实时预览（推荐给需要容器隔离的开发者）

Docker 本地启动（高级模式，可跳过）

companion daemon（受控恢复入口）

前端发布脚本（可选）

飞书用户凭证私聊回调域名（可选）

VPS / ECS 公网访问（正式方案）

模式 A：已有反代（宝塔 / NPM / Nginx）

模式 B：干净 VPS / ECS 内置公网网关

模式 C：像宝塔一样先用公网 IP + 端口访问

GitHub -> 远端部署

远程访问（高级模式，可跳过）

M1 API 覆盖

强约束说明

Related posts

Securing the Financial Frontier: How Capital One Uses Socket for Open Source Security

Insecure Agents Podcast: How to Keep AI Agents From Bypassing Security Controls