# 现有用户想要最小改动：JAW_SAFE=1 npm install -g cli-jaw
npm install -g cli-jaw
jaw dashboard

每个 agent 都在一处

在管理面板里启动、停止并预览每个正在运行的实例。

为工作准备的看板

看板泳道、优先级矩阵和提醒，跟踪每个会话正在做什么。

agent 能读的笔记

内置的 Markdown 工作区，支持所见即所得编辑、数学公式和 Mermaid 图表。

CLI-JAW 是什么？

CLI-JAW 把你已经在用的 AI 编码 CLI 统一成一个助手、一份记忆、一个仪表盘。你的主 CLI（“Boss”）把其他 CLI 当作“员工”调用，于是你不用再在多个应用之间复制粘贴，在一个地方就能下达指令。

• 无需 API 密钥 — 通过你已经在付费的订阅路由
• 无按 token 计费 — 月费固定，和你现有的订阅一样
• 本地运行 — 你的代码不会离开本机
• 随处可用 — Web、桌面应用、终端、Telegram、Discord 或 Slack

原生 Code API（/api/code）提供隔离的 Codex、Claude、Cursor 和 Grok 会话，具备持久 transcript 和原生 resume。参见 native Code sessions。

安装

# macOS / Linux
JAW_SAFE=1 npm install -g cli-jaw    # skips optional tool/runtime setup
jaw init                              # interactive setup later when you're ready

Windows 支持。 推荐使用 WSL 路径，它是稳定的。原生 PowerShell 安装脚本也可以用，但仍处于 beta 阶段：

irm https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/install.ps1 | iex

需要 Node.js 22.4+。

管理面板在 24576 端口，每个 agent 的 Web UI 在 3457 端口。如果执行策略挡住了 jaw.ps1，不要放宽策略，直接用 .cmd：

jaw.cmd doctor

原生 Windows 的开机自启通过 windows-startup 后端注册。jaw service install 同样支持 macOS(launchd) 和 Linux(systemd)。

无论走哪条路径，cli-jaw 现在都能把两者精确区分开：jaw doctor --json 会把 platform 报告为 windows-native 或 wsl，两者各有独立诊断。原生 Windows 不会再仅仅因为机器上配置了 WSL interop 就收到“在 WSL 里重新安装” 的建议。

# macOS / Linux / WSL with Node.js 22+ already installed
npm install -g cli-jaw
jaw dashboard

npm 12+？ npm 现在默认阻止依赖的安装脚本。如果看到 npm warn allow-scripts，请批准脚本后再安装：

npm install -g cli-jaw --allow-scripts=cli-jaw

npm 12+ 可能完成全局安装，同时阻止 CLI-JAW 的依赖 postinstall。只批准这一个包然后重新安装，或把批准保存下来供 以后升级使用：

npm install -g cli-jaw --allow-scripts=cli-jaw
npm config set allow-scripts=cli-jaw --location=user
jaw doctor

如果 PowerShell 报告 jaw.ps1 无法加载，因为脚本执行 已被禁用，请在下列受控变通方案中选择一个：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
jaw.cmd doctor
node "$(npm prefix -g)\node_modules\cli-jaw\dist\bin\cli-jaw.js" doctor

jaw.ps1 是 PowerShell 的 npm shim，受执行策略约束； jaw.cmd 是等价的 cmd shim，不走该策略。直接使用 node 的形式会绕过两个 shim。jaw doctor 会报告被阻止或过期的安装、 残留的 npm 暂存目录，以及当前 PowerShell 策略；它还会 打印对应的恢复指引。

完成。打开 http://localhost:24576 进入管理仪表盘。单个 agent Web UI 在运行 jaw serve 时仍从 http://localhost:3457 提供。需要 Node.js 22.4+。

第一次用？ 默认 npm 安装会初始化 CLI-JAW，并尝试配置原生 Claude。其他 AI CLI 是可选项；在 macOS/Linux 上如需安装全部工具，可运行 CLI_JAW_INSTALL_CLI_TOOLS=1 npm install -g cli-jaw。Windows 请使用下方 WSL 安装路径。

已退役的 runtime。 Claude E（claude-e）和 AI-E multiplexer（ai-e）已被移除。已保存的选择会以已退役状态显示，且无法执行；请选择一个可用的 runtime。详情：runtime integration。

curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/install.sh | bash
source "${ZDOTDIR:-$HOME}/.zshrc" 2>/dev/null || true
bash "$(npm root -g)/cli-jaw/scripts/verify-fresh-install.sh"

# 1. Install WSL (PowerShell as Admin)
wsl --install

重启后打开 Ubuntu，然后：

# 2. Install CLI-JAW + all dependencies
curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/install-wsl.sh | bash
source ~/.bashrc
jaw dashboard
bash "$(npm root -g)/cli-jaw/scripts/verify-fresh-install.sh"

从 Windows PowerShell 进入 WSL 时，请通过 login shell 运行命令，以便加载 WSL profile PATH：

wsl.exe -d Ubuntu -- bash -lc "jaw dashboard"

jaw serve 会保留它继承的 stdout 和 stderr 流，并把 两个流都追加到 <JAW_HOME>\logs\serve.log。启动时，已经达到 5 MiB 的文件 会被轮转一次为 serve.log.1。原生 Windows 仍然没有注册的 jaw service 日志后端。PowerShell 的 Start-Process -RedirectStandardOutput/-RedirectStandardError 会在每次启动时创建或 截断目标文件，所以不要把这两个选项指向 实例自有的 serve.log。

如果需要独立的、由运维方拥有的 stdout/stderr 文件，请改为在子 PowerShell 进程 内部做重定向。下面的示例把它们追加到 <JAW_HOME>\logs 下，同时避开 Start-Process 的截断默认行为：

$jawHome = 'C:\jaw\worker-a'
$port = 3458
$logDir = Join-Path $jawHome 'logs'
$outLog = Join-Path $logDir 'serve.out.log'
$errLog = Join-Path $logDir 'serve.err.log'
New-Item -ItemType Directory -Force -Path $logDir -ErrorAction Stop | Out-Null
foreach ($path in @($outLog, $errLog)) {
    # OpenOrCreate preserves existing content while proving that the child can append.
    $probe = [IO.File]::Open($path, 'OpenOrCreate', 'Write', 'ReadWrite')
    $probe.Dispose()
}

$jaw = (Get-Command jaw.cmd -ErrorAction Stop).Source
$childCommand = "& '$jaw' --home '$jawHome' serve --port $port --no-open 1>> '$outLog' 2>> '$errLog'"
$encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($childCommand))
Start-Process -FilePath powershell.exe -ArgumentList '-NoProfile', '-EncodedCommand', $encoded -WindowStyle Hidden | Out-Null

请在各自独立的 PowerShell 终端里读取每个流（Get-Content -Wait 会占用该终端）。这些命令使用显式路径，因为启动终端里的变量 在新的 PowerShell 会话中不可用：

# Terminal 1
Get-Content -LiteralPath 'C:\jaw\worker-a\logs\serve.out.log' -Tail 100 -Wait

# Terminal 2
Get-Content -LiteralPath 'C:\jaw\worker-a\logs\serve.err.log' -Tail 100 -Wait

生命周期命令以 home 为作用域，在发送信号前会校验 <JAW_HOME>\jaw.pid.json：

& $jaw --home $jawHome service stop --port $port
& $jaw --home $jawHome service restart --port $port

单独运行 service restart 会以分离方式安全重启实例，但 无法重现运维方的文件重定向。要保留文件捕获，请 stop、可选地轮转已关闭的日志，然后重新运行上面的启动块：

$pidFile = Join-Path $jawHome 'jaw.pid.json'
$serverProcess = $null
if (Test-Path -LiteralPath $pidFile -PathType Leaf) {
    $record = Get-Content -LiteralPath $pidFile -Raw -ErrorAction Stop | ConvertFrom-Json
    $serverProcess = Get-Process -Id ([int]$record.pid) -ErrorAction SilentlyContinue
}

& $jaw --home $jawHome service stop --port $port
if ($LASTEXITCODE -ne 0) {
    throw "jaw service stop failed with exit code $LASTEXITCODE"
}
if ($serverProcess) {
    try {
        if (-not $serverProcess.WaitForExit(5000)) {
            throw "jaw serve pid $($serverProcess.Id) did not exit within 5000ms"
        }
    } finally {
        $serverProcess.Dispose()
    }
}

$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
foreach ($path in @($outLog, $errLog)) {
    if (Test-Path -LiteralPath $path) {
        Move-Item -LiteralPath $path -Destination "$path.$stamp" -ErrorAction Stop
    }
}
# Run the Start-Process launch block above again.

不要使用 Get-Process node | Stop-Process；它可能终止无关的 cli-jaw 实例和 AI runtime 进程。

发布安装器变更前，请在干净 VM 上运行此流程。collector 会把环境快照、installer 日志、实际运行的 collector/installer/verifier 脚本及其 SHA-256 哈希、verifier 日志和新 shell PATH probe 写入 ~/cli-jaw-fresh-install-evidence-*。

# macOS Terminal
COLLECTOR=/tmp/cli-jaw-collect-fresh-install-evidence.sh
curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/collect-fresh-install-evidence.sh -o "$COLLECTOR"
bash "$COLLECTOR" --target macos

# Ubuntu inside WSL
COLLECTOR=/tmp/cli-jaw-collect-fresh-install-evidence.sh
bash "$COLLECTOR" --target wsl

从 Windows PowerShell 进入受支持的 WSL 路径：

wsl.exe -d Ubuntu -- bash -lc 'COLLECTOR=/tmp/cli-jaw-collect-fresh-install-evidence.sh; curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/collect-fresh-install-evidence.sh -o "$COLLECTOR"; bash "$COLLECTOR" --target wsl'

如果 collector 报告 WSL 内没有 powershell.exe，请在审计前从 Windows PowerShell 运行：

wsl.exe -d Ubuntu -- bash -lc 'EVIDENCE_DIR="$(ls -dt ~/cli-jaw-fresh-install-evidence-* | head -1)"; { echo "command=wsl.exe -d Ubuntu -- bash -lc jaw --version"; jaw --version; } | tee "$EVIDENCE_DIR/33-powershell-to-wsl-probe.log"'

对于未合并的分支或本地 VM 检出，请显式传入本地安装器和 verifier：

bash scripts/collect-fresh-install-evidence.sh --target macos --install-script scripts/install.sh --verifier-script scripts/verify-fresh-install.sh
bash scripts/collect-fresh-install-evidence.sh --target wsl --install-script scripts/install-wsl.sh --verifier-script scripts/verify-fresh-install.sh

在把收集到的每个目录当作目标证据之前，请先审计：

EVIDENCE_DIR="$(ls -dt ~/cli-jaw-fresh-install-evidence-* | head -1)"
AUDITOR="$(npm root -g)/cli-jaw/scripts/audit-fresh-install-evidence.mjs"
node "$AUDITOR" "$EVIDENCE_DIR" --target macos
node "$AUDITOR" "$EVIDENCE_DIR" --target wsl

# For a local checkout, audit with the checkout's auditor:
node scripts/audit-fresh-install-evidence.mjs "$EVIDENCE_DIR" --target macos
node scripts/audit-fresh-install-evidence.mjs "$EVIDENCE_DIR" --target wsl

发布安装器变更前，请用两个严格的 evidence 目录运行 matrix gate：

GATE="$(npm root -g)/cli-jaw/scripts/verify-release-evidence.mjs"
node "$GATE" --macos /path/to/macos-evidence --wsl /path/to/wsl-evidence

# For a local checkout:
node scripts/verify-release-evidence.mjs --macos /path/to/macos-evidence --wsl /path/to/wsl-evidence

matrix gate 会拒绝用过期 collector、installer 或 verifier 脚本收集到的证据；归档的证据脚本必须与运行该 gate 的当前包或检出匹配。

当 scripts/promote-to-main.sh、scripts/release-preview.sh 或 npm publish 检测到自上一个 tag 以来有安装器敏感变更时，它会在任何 git push 或 npm publish 之前运行同一个 matrix gate。请在开始发布前设置证据目录：

CLI_JAW_MACOS_EVIDENCE_DIR=/path/to/macos-evidence \
CLI_JAW_WSL_EVIDENCE_DIR=/path/to/wsl-evidence \
bash scripts/promote-to-main.sh

scripts/promote-to-main.sh 只提升已经通过认证的 preview head。除非存在针对该精确 preview SHA 的成功 test.yml push run，否则它拒绝启动。不带参数时，它提升当前的 origin/preview head；可选的 SHA 参数必须等于同一个 head，因此它起断言作用，而不是用来提升更旧的提交。

脚本会派发 npm publish，然后不检查发布是否成功就退出，之后也无法再次运行。对于部分完成的发布——npm publish 缺失、GitHub release 缺失、latest 上的版本不对，或 main 上的红色提交——的恢复方法记录在 structure/infra.md § 릴리스 파이프라인과 부분 실패 복구。

docker compose up -d       # → http://localhost:3457

认证

你只需要一个。选择你已有的订阅：

# Free options (no credit card needed)
copilot login        # GitHub Copilot (free tier available)
opencode             # OpenCode — free models available
kiro                 # AWS Kiro (free tier with AWS account)

# Paid (monthly subscription you already pay for)
claude auth login    # Anthropic Claude Pro or higher
codex login          # OpenAI ChatGPT Pro or higher
cursor-agent login   # Cursor
grok login --oauth   # xAI Grok / Grok Heavy

一次性检查全部：jaw doctor

🦈 CLI-JAW Doctor — 13 checks

 ✅ Node.js        v22.15.0
 ✅ Claude CLI      installed
 ✅ Codex CLI       installed
 ✅ Cursor CLI      installed
 ✅ OpenCode CLI    installed
 ✅ Copilot CLI     installed
 ✅ Database        jaw.db OK
 ✅ Skills          29 active, 238 reference
 ✅ MCP (plugins)   3 servers configured
 ✅ Memory          structured/ exists
 ✅ Server          port 3457 available

你能得到什么

员工：你的 CLI 调用其他 CLI

你只和一个 AI（“Boss”）对话。当它需要专业工作时，会把任务分派给员工——每个员工运行自己的 CLI 和模型——并在回答你之前审查它们的输出。

You: "Fix the frontend styling and update the API endpoint"

Boss (Claude)
  ├── Frontend employee (OpenCode) → "Fix the CSS grid layout in dashboard.tsx"
  ├── Backend employee (Codex)     → "Update /api/users to return pagination metadata"
  └── Synthesizes both results for you

jaw dispatch --agent "Backend" --task "Run read-only verification" --watch
jaw dispatch --virtual "security" --task "Review this branch for auth and secret leaks" --watch

PABCD：计划、审计、构建、检查、完成

对于复杂任务，CLI-JAW 运行结构化工作流。每一次转换都由你批准；只读工作者验证计划和结果。

| 阶段 | 会发生什么 | |---|---| | P — Plan | Boss 写出 diff 级别的计划，然后停下等你审查 | | A — Audit | 只读工作者检查计划是否可行 | | B — Build | Boss 实现；只读工作者进行验证 | | C — Check | 类型检查、文档更新、一致性检查 | | D — Done | 汇总所有变更，回到空闲状态 |

状态在重启后保留。用 jaw orchestrate 或 /pabcd 开始，用 /continue 恢复，用 /goal 让长期目标保持存活。参见 PABCD。

记忆、技能和 MCP

• 三层记忆 — 最近的会话历史、从对话中沉淀出来的结构化笔记，以及可搜索的 soul/task 快照：jaw memory search "how did we set up the API auth?"
• 200+ 技能 — 办公文档（PDF、DOCX、XLSX、PPTX、HWP）、浏览器和桌面自动化、媒体、GitHub、Notion 和开发指南：jaw skill install <name>
• 所有引擎共用一份 MCP 配置 — jaw mcp install @anthropic/context7 会一次同步 Claude、Codex、Kiro、OpenCode、Copilot 和 Antigravity

浏览器和桌面自动化

通过 DevTools Protocol 驱动 Chrome；用 jaw browser vision-click "Login button" 按描述点击；在 macOS 和 Windows 上通过 Codex Computer Use 控制桌面应用；用 jaw browser web-ai 询问 ChatGPT、Gemini 或 Grok 的 Web UI。

消息

从 Telegram（语音消息、论坛主题、定时 heartbeat 任务）、Discord 和 Slack（Socket Mode、线程、文件中继、mention 监听）与你的 agent 聊天。可以同时启用多个渠道；home 渠道会接收主动发送的内容。

1. 给 @BotFather 发消息 → /newbot → 复制 token
2. jaw init --telegram-token YOUR_TOKEN，或使用 Web UI 设置
3. 给 bot 发送任意消息。Chat ID 会在第一条消息时自动保存

1. jaw slack setup — 打印 app manifest、打开 Slack 应用页面、实时校验两个 token，并写入设置
2. 在 bot 需要读取的每个频道执行 /invite @cli-jaw，然后重启 jaw serve

群组 DM 需要 message.mpim 事件和 mpim:history scope。在容器中，SLACK_BOT_TOKEN、SLACK_APP_TOKEN、SLACK_TEAM_ID 和 SLACK_CHANNEL_IDS 在运行时拥有各自的字段。详情：Slack tools。

桌面应用

Electron 应用会启动管理面板，随包提供内置的 Node.js sidecar，并常驻你的菜单栏。请从 GitHub Releases 下载：

• macOS（Apple Silicon） — 打开 DMG，把 CLI-JAW 拖入 Applications。构建产物经过 Developer ID 签名、公证和 stapling，并支持应用内更新。
• Windows（x64） — 运行 Setup .exe。它没有签名，因此 SmartScreen 可能会要求你确认。
• Linux（x64） — 给 AppImage 添加执行权限后运行。

首次启动后，接受 Install CLI command（或使用托盘项 Install CLI to Terminal），即可在终端中得到 jaw，无需全局 npm 安装。

AI 运行时

无按 token 的 API 计费。通过你已经在付费的订阅路由。

| CLI | 默认模型 | 认证 | 费用 | |---|---|---|---| | Pi | grok-composer-2.5-fast | Settings profile API key、local proxy，或 PI_CODING_AGENT_BIN | 通过隔离 profile 连接 local/API endpoint | | Claude | claude-opus-4-8 | claude auth login | Claude Pro 或更高订阅 | | Antigravity | AGY-selected | 由 agy 在运行时检查 | 实验性 print-mode runtime | | Codex | gpt-5.5 | codex login | ChatGPT Pro 或更高订阅 | | Codex App | gpt-5.5 | codex login | ChatGPT Pro 或更高订阅 | | Cursor | composer-2.5 | cursor-agent login 或 CURSOR_API_KEY | Cursor 订阅 | | Grok | grok-build | grok login --oauth | Grok 订阅 | | Kiro | registry-selected | kiro | AWS Kiro 免费层 | | OpenCode | opencode-go/kimi-k2.6 | opencode | 有免费模型可用 | | Copilot | claude-sonnet-4.6 | copilot login | 有免费层可用 |

如果某个引擎被限速，下一个会接上（/fallback）。用 /cli codex 实时切换引擎，用 /model gpt-5.5 切换模型 — 可在 Web、终端、Telegram、Discord 或 Slack 中使用。

CLI

# Core
jaw dashboard                     # launch manager dashboard
jaw serve                         # start an agent server (http://localhost:3457)
jaw chat                          # terminal chat UI
jaw ask "question"                # one prompt, one answer — no TTY needed
jaw doctor                        # installation and runtime diagnostics

# Instances
jaw clone ~/project                           # clone instance to new directory
jaw --home ~/project serve --port 3458        # run a second instance
jaw service install                           # auto-start on boot (macOS launchd / Linux systemd)
jaw --home ~/project service restart --port 3458  # restart only this instance

# Agents and workflow
jaw employee list
jaw dispatch --agent "Backend" --task "..." --watch
jaw orchestrate                   # PABCD workflow
jaw goal status                   # persistent goals

# Skills, MCP, memory, browser
jaw skill list
jaw mcp install <package>
jaw memory search <query>
jaw browser fetch "https://example.com" --json

用 jaw clone 创建的每个实例都有自己的设置、记忆、数据库和 MCP 配置，管理面板可以看到全部。远程和无头主机：structure/remote-headless.md。完整命令参考：CLI docs。

文档

| 主题 | 位置 | |---|---| | 官网和快速上手 | lidge-ai.github.io/cli-jaw | | 指南、概念、参考 | Developer docs | | 架构 | docs/ARCHITECTURE.md · structure/ | | Slack 工具和本地 API | docs/slack-tools.md | | Runtime 集成（含已退役 runtime） | structure/runtime-integration.md |

开发

npm run build          # tsc → dist/
npm run build:frontend # vite → public/dist/
npm run dev            # tsx server.ts (hot-reload)
npm test               # node:test driver (tests/run.mts)
npm run gate:all       # release/docs parity gates
npm run electron:dev   # desktop app with hot reload

故障排查

| 问题 | 解决办法 | |---|---| | cli-jaw: command not found | 再运行一次 npm install -g cli-jaw。macOS/Linux/WSL：检查 ~/.local/bin 或 npm prefix -g + /bin 是否在 $PATH 中。从 Windows PowerShell 调用 WSL 时，请通过 login shell：wsl.exe -d Ubuntu -- bash -lc "jaw dashboard"。 | | npm warn allow-scripts ... | npm >= 12 会阻止依赖安装脚本：npm install -g cli-jaw --allow-scripts=cli-jaw，或用 npm config set allow-scripts=cli-jaw --location=user 持久保存。已经装过了？jaw init 会完成设置。 | | pnpm/bun 阻止了构建脚本 | pnpm 11+：pnpm add -g --allow-build=cli-jaw cli-jaw。bun：bun add -g --trust cli-jaw。 | | 全新安装的 verifier 失败 | 修复报告出的 PATH 或可执行位问题，然后重新运行 bash "$(npm root -g)/cli-jaw/scripts/verify-fresh-install.sh"。 | | Error: node version | 升级到 Node.js 22.4+：nvm install 22 | | NODE_MODULE_VERSION mismatch | npm run ensure:native | | EADDRINUSE: port 3457 | 另一个实例正在运行。使用 --port 3458 或先停止它 | | Telegram / Discord / Slack 认证失败 | 运行 jaw doctor，检查 token，重启 jaw serve | | 员工分派挂起 | 运行 jaw employee list，确认员工 CLI 已认证（jaw doctor），然后用 jaw dispatch --watch 重试 |

参与贡献

公开代码和产品文档保存在这里。私有规划和历史只保存在独立的同级克隆 cli-jaw-internal 中；请通过 issue 申请访问权限。不要在本检出中创建私有记录，包括 devlog、_plan、_fin 或 .jwc 别名，也不要在公开文档或源码中包含私有记录路径。上传变更前，请先完成本地 pre-push 设置和检查。

1. 从 dev Fork 并创建分支
2. npm run build && npm run build:frontend && npm test
3. 对发布敏感的变更，还要运行 npm run gate:all
4. 提交 PR