Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

Launch permission onboarding from doctor

Leo7e0382295925
diff --git a/README.md b/README.md
index b9dc6b9..5ed3a7a 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ npm install -g open-computer-use
安装任意一个后,都会同时提供这三个命令别名:
```bash
-# 检查当前权限状态,确认 Accessibility / Screen Recording 是否已经授权
+# 检查当前权限状态;如果有缺失会直接拉起权限 onboarding 窗口
open-computer-use doctor
# 以 stdio MCP server 模式启动,给 Claude Desktop / Cursor / Cline / 自定义 client 连接
@@ -110,6 +110,7 @@ npm install -g open-computer-use
```bash
swift build
+# 缺权限时会打开权限 onboarding 窗口
.build/debug/OpenComputerUse doctor
.build/debug/OpenComputerUse list-apps
```
diff --git a/apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swift b/apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swift
index 7661897..db37427 100644
--- a/apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swift
+++ b/apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swift
@@ -21,6 +21,9 @@ enum OpenComputerUseMain {
case "doctor":
let permissions = PermissionDiagnostics.current()
print(permissions.summary)
+ if !permissions.missingPermissions.isEmpty {
+ PermissionOnboardingApp.launch()
+ }
case "list-apps":
print(service.listApps().primaryText ?? "")
case "snapshot":
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e5d555f..f5dd931 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -5,7 +5,7 @@
## 当前目录结构
- `apps/OpenComputerUse`
- 主入口,负责 `mcp`、`doctor`、`list-apps`、`snapshot` 等 CLI 命令;不带参数启动时默认进入无 Dock 图标的 app 模式权限引导窗口。
+ 主入口,负责 `mcp`、`doctor`、`list-apps`、`snapshot` 等 CLI 命令;不带参数启动时默认进入无 Dock 图标的 app 模式权限引导窗口,`doctor` 在检测到缺失权限时也会直接拉起这套 onboarding UI。
- `apps/OpenComputerUseFixture`
本地 GUI fixture app,用来承载低风险、可预测的点击/输入/滚动/拖拽验证路径。
- `apps/OpenComputerUseSmokeSuite`
diff --git a/docs/RELIABILITY.md b/docs/RELIABILITY.md
index 346f7cc..c3f3db8 100644
--- a/docs/RELIABILITY.md
+++ b/docs/RELIABILITY.md
@@ -17,7 +17,7 @@
## 当前故障排查顺序
-1. 先跑 `.build/debug/OpenComputerUse doctor`,确认权限状态。
+1. 先跑 `.build/debug/OpenComputerUse doctor`,确认权限状态;如果缺权限,命令会直接拉起权限 onboarding 窗口。
2. 用 `.build/debug/OpenComputerUse list-apps` 确认目标 app 是否被发现。
3. 用 `.build/debug/OpenComputerUse snapshot <app>` 看是 transport 问题还是 snapshot / action 问题。
4. 如果只想验证仓库基线,直接跑 fixture + smoke,不要先在复杂第三方 app 上排查。
diff --git a/docs/histories/2026-04/20260417-2155-doctor-launches-permission-onboarding.md b/docs/histories/2026-04/20260417-2155-doctor-launches-permission-onboarding.md
new file mode 100644
index 0000000..cfc3c6b
--- /dev/null
+++ b/docs/histories/2026-04/20260417-2155-doctor-launches-permission-onboarding.md
@@ -0,0 +1,29 @@
+## [2026-04-17 21:55] | Task: 让 doctor 缺权限时拉起授权页
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `GPT-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> `open-computer-use doctor` 现在打印 `Permissions: accessibility=missing, screenRecording=missing` 时,需要跳出授权页。
+
+### 🛠 Changes Overview
+**Scope:** `apps/OpenComputerUse`、`packages/OpenComputerUseKit`、`docs/`、`scripts/npm`
+
+**Key Actions:**
+- **补 doctor 后续动作**:`doctor` 打印权限状态后,如果仍有缺失,会直接拉起现有的权限 onboarding 窗口。
+- **补可测试诊断结果**:在 `PermissionDiagnostics` 增加 `missingPermissions`,让 CLI 决策复用权限层结果,并补对应单测。
+- **同步用户文档**:更新仓库 README、架构文档、稳定性文档和 npm README 模板,明确 `doctor` 缺权限时会进入 onboarding。
+
+### 🧠 Design Intent (Why)
+仓库已经有完整的权限 onboarding UI,但 `doctor` 之前只负责打印结果,用户从 CLI 看到 `missing` 后还要自己再找入口。直接在缺权限时复用现有 onboarding,可以把诊断和修复收成一条更短的路径,同时避免在 CLI 里再复制一套单独的权限引导逻辑。
+
+### 📁 Files Modified
+- `apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swift`
+- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/Permissions.swift`
+- `packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift`
+- `README.md`
+- `docs/ARCHITECTURE.md`
+- `docs/RELIABILITY.md`
+- `scripts/npm/build-packages.mjs`
diff --git a/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/Permissions.swift b/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/Permissions.swift
index 3694be5..74393c8 100644
--- a/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/Permissions.swift
+++ b/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/Permissions.swift
@@ -79,6 +79,10 @@ public struct PermissionDiagnostics: Sendable {
"Permissions: accessibility=\(accessibilityTrusted ? "granted" : "missing"), screenRecording=\(screenCaptureGranted ? "granted" : "missing")"
}
+ public var missingPermissions: [SystemPermissionKind] {
+ SystemPermissionKind.allCases.filter { !isGranted($0) }
+ }
+
public func isGranted(_ permission: SystemPermissionKind) -> Bool {
switch permission {
case .accessibility:
diff --git a/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift b/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
index e67ee36..a789144 100644
--- a/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
+++ b/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
@@ -7,6 +7,24 @@ final class OpenComputerUseKitTests: XCTestCase {
XCTAssertEqual(ToolDefinitions.all.count, 9)
}
+ func testPermissionDiagnosticsListsMissingPermissionsInCanonicalOrder() {
+ let diagnostics = PermissionDiagnostics(
+ accessibilityTrusted: false,
+ screenCaptureGranted: true
+ )
+
+ XCTAssertEqual(diagnostics.missingPermissions, [.accessibility])
+ }
+
+ func testPermissionDiagnosticsHasNoMissingPermissionsWhenAllGranted() {
+ let diagnostics = PermissionDiagnostics(
+ accessibilityTrusted: true,
+ screenCaptureGranted: true
+ )
+
+ XCTAssertTrue(diagnostics.missingPermissions.isEmpty)
+ }
+
func testKeyPressParserSupportsCommandStyleChord() throws {
let parsed = try KeyPressParser.parse("super+c")
XCTAssertEqual(parsed.displayValue, "c")
diff --git a/scripts/npm/build-packages.mjs b/scripts/npm/build-packages.mjs
index d5f5eb7..e338b61 100644
--- a/scripts/npm/build-packages.mjs
+++ b/scripts/npm/build-packages.mjs
@@ -237,7 +237,7 @@ In practice, using this package as MCP is: global install, add the JSON config,
## Use
\`\`\`bash
-# Check permissions and diagnose whether Accessibility / Screen Recording are granted
+# Check permissions; if Accessibility / Screen Recording is missing, open the permission onboarding window
open-computer-use doctor
# Start the stdio MCP server for Claude Desktop, Cursor, Cline, or another MCP client