---
name: qoderwork-guidance
version: 1.0.0
description: Guides AI to manage QoderWork application capabilities through the built-in Connector. Use when users ask about managing QoderWork settings, MCP servers, skills, scheduled tasks, IM channels, connectors, or any application configuration.
description_zh: 指导 AI 通过内置 Connector 管理 QoderWork 应用能力。当用户提到管理 QoderWork 设置、MCP 服务器、技能、定时任务、IM 频道、连接器或应用配置时使用。
---

# QoderWork Connector Guidance

QoderWork exposes its full configuration capabilities through a built-in MCP Connector. You interact with it using two tools:

- **`mcp__builtin_qoderwork__query`** -- Read-only queries. Input: `{ key }`.
- **`mcp__builtin_qoderwork__action`** -- Execute operations. Input: `{ key, action, params? }`.

All operations use a **dot-separated key hierarchy** (e.g. `qoderwork.settings.connector.market.github`). Start with `query({ key: "qoderwork" })` to discover all available keys.

---

## Complete Key Reference

| Key | Actions | Description |
|-----|---------|-------------|
| `qoderwork` | query | App global status (version, platform, all available keys) |
| `qoderwork.settings` | query, open | Settings overview (all setting categories) |
| `qoderwork.settings.connector` | query, open | All connectors overview (builtin + market MCP + custom MCP). Supports keyword param. |
| `qoderwork.settings.connector.builtin.apple` | query, open | Apple connectors list |
| `qoderwork.settings.connector.builtin.apple.{id}` | query, enable, disable | Single Apple connector toggle |
| `qoderwork.settings.connector.builtin.ms365` | query, open, connect, disconnect | Microsoft 365 connector status |
| `qoderwork.settings.connector.builtin.ms365.{subId}` | query, enable, disable | Microsoft 365 sub-connector toggle |
| `qoderwork.settings.connector.builtin.browser` | query, open, enable, disable | Browser connector status and toggle |
| `qoderwork.settings.connector.builtin.computer_use` | query, open, enable, disable, execute | Computer Use connector |
| `qoderwork.settings.connector.market` | query, open | Market (built-in) MCP servers list. Supports keyword param. |
| `qoderwork.settings.connector.market.{name}` | query, open, enable, disable, install, uninstall, execute | Market MCP server (install/uninstall = enable/disable) |
| `qoderwork.settings.connector.custom` | query, open | Custom (user-added) MCP servers list. Supports keyword param. |
| `qoderwork.settings.connector.custom.add` | open, execute | Add a new custom MCP server |
| `qoderwork.settings.connector.custom.{name}` | query, open, update, enable, disable, remove, execute | Custom MCP server CRUD |
| `qoderwork.settings.preferences` | query, open, update | User preferences (auto-launch, MCP lazy load, prevent sleep, etc.) |
| `qoderwork.settings.profile` | query, open | User profile (account info, subscription tier) |
| `qoderwork.settings.system` | query, open, update | System settings (auto-launch, prevent sleep, close window action) |
| `qoderwork.settings.keyboard` | query, open | Keyboard shortcuts (all configurable actions and bindings) |
| `qoderwork.settings.vm` | query, open, enable, disable | Secure workspace (status, version, enable/disable) |
| `qoderwork.settings.experimental` | query, open, update | Experimental feature toggles (MCP lazy load, Prompt Suggestions, QuickPick) |
| `qoderwork.settings.permissions` | query, open, execute | macOS system permissions (6 permission types) |
| `qoderwork.settings.skills` | query, open | Installed + builtin skills list |
| `qoderwork.settings.skills.market` | query, execute | Skill marketplace (search, install) |
| `qoderwork.settings.skills.{folderName}` | query, enable, disable, remove | Single skill operations |
| `qoderwork.usage` | query | Credit usage (plan, add-on, Teams shared, remaining %) |
| `qoderwork.cron` | query, open | Scheduled tasks list + summary stats |
| `qoderwork.cron.runlogs` | query | Task execution logs (filter by taskId, status; pagination) |
| `qoderwork.cron.{taskId}` | query, enable, disable, execute, remove | Single task operations |
| `qoderwork.channels` | query, open | IM channels overview (status, capabilities, errors) |
| `qoderwork.channels.{channelId}` | query, enable, disable, execute | Single channel (detail, toggle, restart, QR auth) |
| `qoderwork.channels.{channelId}.pairings` | query, execute, remove | Channel pairing management |
| `qoderwork.feedback` | open | Open feedback dialog (prefill content, user reviews and submits) |

---

## Scenario Routing

For complex operations, read the corresponding guide file before proceeding:

| User Intent | Guide File |
|-------------|------------|
| Install/uninstall skills, search skill market, enable/disable skills | `guide-skills.md` |
| Add/remove/configure MCP servers, check MCP connection status | `guide-mcp.md` |
| Manage scheduled/cron tasks, check execution logs, run tasks | `guide-cron.md` |
| Manage IM channels (DingTalk/Feishu/WeChat/WeCom), QR authentication, pairing | `guide-channels.md` |
| Manage builtin connectors (Apple/Microsoft 365/Browser/Computer Use) | `guide-connectors.md` |
| Settings (preferences, system, VM, keyboard, permissions, experimental, profile, usage) | Documented inline below |

---

## Common Action Patterns

### Query

```
mcp__builtin_qoderwork__query({ key: "qoderwork.settings.connector" })
```

### Open Settings Page

```
mcp__builtin_qoderwork__action({ key: "qoderwork.settings.connector", action: "open" })
```

### Enable / Disable

```
mcp__builtin_qoderwork__action({ key: "qoderwork.settings.connector.custom.my-server", action: "disable" })
```

### Install / Uninstall (Market MCP)

```
mcp__builtin_qoderwork__action({ key: "qoderwork.settings.connector.market.notion", action: "install" })
```

### Update

```
mcp__builtin_qoderwork__action({
  key: "qoderwork.settings.preferences",
  action: "update",
  params: { autoLaunchEnabled: false }
})
```

### Execute

```
mcp__builtin_qoderwork__action({
  key: "qoderwork.settings.connector.custom.add",
  action: "execute",
  params: { name: "my-server", config: { command: "npx", args: ["-y", "some-mcp-server"] } }
})
```

### Remove

```
mcp__builtin_qoderwork__action({ key: "qoderwork.settings.connector.custom.my-server", action: "remove" })
```

---

## Settings Quick Reference

These settings keys are straightforward query/update operations and do not require a separate guide.

### Preferences (`qoderwork.settings.preferences`)

Query returns all preference items. Update with key-value pairs:

| Setting Key | Type | Default | Description |
|-------------|------|---------|-------------|
| `autoLaunchEnabled` | boolean | true | Launch at system startup |
| `mcpLazyLoad` | boolean | true | MCP lazy loading |
| `preventSleepEnabled` | boolean | false | Prevent system sleep |
| `quickPickEnabled` | boolean | false | QuickPick global shortcut window |
| `closeWindowAction` | string | "ask" | Close window behavior: "ask" / "minimize" / "quit" |

```
// Update example
action({ key: "qoderwork.settings.preferences", action: "update", params: { preventSleepEnabled: true } })
```

### Profile (`qoderwork.settings.profile`)

Read-only. Returns account info and subscription tier.

```
query({ key: "qoderwork.settings.profile" })
```

### System (`qoderwork.settings.system`)

Query and update system-level settings (auto-launch, prevent sleep, close window action).

```
action({ key: "qoderwork.settings.system", action: "update", params: { preventSleepEnabled: true } })
```

### Keyboard (`qoderwork.settings.keyboard`)

Read-only. Returns all configurable keyboard shortcuts and their current bindings.

```
query({ key: "qoderwork.settings.keyboard" })
```

### Secure Workspace (`qoderwork.settings.vm`)

Query secure workspace status and version. Enable or disable it:

```
query({ key: "qoderwork.settings.vm" })
action({ key: "qoderwork.settings.vm", action: "enable" })
action({ key: "qoderwork.settings.vm", action: "disable" })
```

### Experimental Features (`qoderwork.settings.experimental`)

Query and toggle experimental feature flags:

```
query({ key: "qoderwork.settings.experimental" })
action({ key: "qoderwork.settings.experimental", action: "update", params: { promptSuggestionsEnabled: true } })
```

### Permissions (`qoderwork.settings.permissions`)

macOS only. Query status of 6 permission types: `fullDiskAccess`, `screenCapture`, `accessibility`, `automation`, `notification`, `location`.

```
// Check all permissions
query({ key: "qoderwork.settings.permissions" })

// Request accessibility access (triggers system prompt)
action({ key: "qoderwork.settings.permissions", action: "execute", params: { operation: "requestAccess", type: "accessibility" } })

// Open system settings for a specific permission
action({ key: "qoderwork.settings.permissions", action: "execute", params: { operation: "openSystemSettings", type: "fullDiskAccess" } })
```

### Credit Usage (`qoderwork.usage`)

Read-only. Returns plan credits, add-on credits, Teams shared resource pack, and aggregate remaining percentage.

```
query({ key: "qoderwork.usage" })
```

### Feedback (`qoderwork.feedback`)

Opens the feedback dialog in QoderWork UI. Optionally prefill content for user to review. The user must manually review and submit -- the agent cannot submit directly.

```
// Open empty feedback dialog
action({ key: "qoderwork.feedback", action: "open" })

// Open with prefilled content
action({ key: "qoderwork.feedback", action: "open", params: { content: "Description of the issue..." } })
```

---

## Important Notes

1. **Connectors include MCP**: MCP servers are managed under `connector.market.*` (built-in MCP) and `connector.custom.*` (user-added MCP). There is no separate `qoderwork.settings.mcp` namespace.
2. **Exact match priority**: `qoderwork.settings.connector.custom.add` is matched exactly before the wildcard `qoderwork.settings.connector.custom.{name}` is tried.
3. **Wildcard parameters**: `{param}` in a key pattern matches any single segment. The extracted value is passed to the handler (e.g. querying `qoderwork.settings.connector.market.github` extracts `name = "github"`).
4. **Segment count must match**: `qoderwork.settings.connector.market` will NOT match `qoderwork.settings.connector.market.github` -- they have different segment counts.
5. **Error handling**: All responses follow `{ success: boolean, data?, message?, error? }`. On failure, check the `error` field for details.
6. **Discovery**: When unsure about available keys, start with `query({ key: "qoderwork" })` to get the full list of registered keys and their supported actions.
7. **install/uninstall**: These are semantic aliases for enable/disable, used only with market MCP servers (`connector.market.{name}`).
