myagents-cli

# myagents-cli — MyAgents 产品能力的 CLI 入口

你正运行在 MyAgents 产品内。MyAgents 不只是一个 chat UI，它是一套带状态的 Agent 平台：定时任务、任务中心、IM Bot、MCP、Provider、插件、Skill、Widget——这些都是产品能力，由内置 `myagents` CLI 一站暴露给你。

**这个 skill 不只是"管理工具"，它是 MyAgents 产品能力的执行入口**。用户表达的需求只要能映射到产品能力，就该用 CLI 主动帮用户做掉，而不是给用户一堆操作步骤让他自己去 Settings 点。这份文档列出全部能力以及"什么时候应该用哪条命令"。

## 前置：CLI 是否可用

CLI 通过 `~/.myagents/bin/myagents` 暴露，你的 SDK 子进程 PATH 已注入这个目录，直接 `myagents <command>` 就能跑。它通过 HTTP 走 Sidecar Admin API（端口由环境变量 `MYAGENTS_PORT` 注入）。

- 遇到 `command not found`：让用户重启一次应用触发 CLI 同步
- 遇到 `ECONNREFUSED`：Sidecar 没起来，让用户检查应用是否在运行

## 使用模式

1. **探索先行**：不熟的命令组用 `myagents <group> --help`；不知道某个 runtime 支持什么 model/permissionMode 用 `myagents runtime describe <runtime>`，**不要靠猜**
2. **预览写操作**：所有写命令支持 `--dry-run`，先给用户看会改什么再执行
3. **机器可读**：加 `--json` 解析结构化输出
4. **失败即恢复**：CLI 失败响应会带 `→ Run: <cmd>` 恢复提示，照着跑就行

## 安全规范

- **改配置前必先 `--dry-run`**——配置数据是用户的命脉，预览给用户看是保护他们的安全网
- **API Key**：用户在对话里明确给了你才写入；没给就引导他去 **设置 → 对应页面** 填，不要追问
- **删除前确认**：用户说"删了吧"也要回读"我要删的是 X，确认吗"

## 生效时机

- **MCP 工具变更**（增删改 / 启禁用 / 环境变量 / OAuth）：磁盘立即写入，但工具在**下一轮对话**才能调用——MCP server 在 session 创建时绑定。当前轮配完后告诉用户："发条新消息我就能用了"
- **其他配置**（Provider / Agent / cron / skill / plugin / config）：写入即时生效

---

## 命令速查 + 何时使用

### MCP 工具（mcp）

```bash
myagents mcp list                                       # 看用户配了哪些 MCP
myagents mcp show <id>                                  # 看某个 MCP 的完整配置（command/args/env/headers）
myagents mcp add --id <id> --type <stdio|sse|http> ...  # 新增
myagents mcp remove <id>                                # 删除
myagents mcp enable <id> --scope <user|project|both>    # 启用
myagents mcp disable <id> --scope <user|project|both>   # 禁用
myagents mcp test <id>                                  # 实际握手测试连通性
myagents mcp env <id> set KEY=val [KEY2=val2 ...]       # 设环境变量（覆盖）
myagents mcp env <id> get [KEY ...]                     # 读环境变量
myagents mcp env <id> delete KEY [KEY2 ...]             # 删环境变量
myagents mcp oauth discover <id>                        # 探测 MCP server 是否支持 OAuth + 拿到 metadata
myagents mcp oauth start <id> [--clientId X --clientSecret Y --scopes "..." --callbackPort N]
                                                        # 启动 OAuth 授权流程（会打开浏览器）
myagents mcp oauth status <id>                          # 看授权状态（已授权 / token 是否过期）
myagents mcp oauth revoke <id>                          # 撤销授权
```

**何时用：**
- "帮我接个 X 工具" → `mcp add` → `mcp enable --scope both` → `mcp test`
- "看下 playwright 配的啥" → `mcp show playwright`
- "Notion MCP 怎么登录" → `mcp oauth discover` 看支持的 scopes，再 `mcp oauth start`
- "X 工具用不了，是不是登录过期了" → `mcp oauth status <id>`，过期就重跑 `oauth start`
- "给 fetch 加个 API Key 环境变量" → `mcp env fetch set FETCH_API_KEY=sk-xxx`

### 模型 Provider（model）

```bash
myagents model list                                     # 看所有 Provider + 验证状态
myagents model add --id <id> --name <显示名> --base-url <url> --models <m1,m2,...> [其它]
myagents model remove <id>                              # 删除自定义 Provider（内置的删不掉）
myagents model set-key <id> <apiKey>                    # 设 API Key
myagents model set-default <id>                         # 设为默认 Provider
myagents model verify <id> [--model <某个具体模型>]      # 实际发一条测试消息验证
```

**何时用：**
- "帮我配 DeepSeek" → 内置 Provider 直接 `model set-key deepseek <key>` → `model verify`
- "我要用一个新厂商" → 详见下方 §配置模型服务流程
- "把默认改成智谱" → `model set-default zhipu`
- "我之前加的那个废 Provider 删了吧" → `model remove <id>`

### Agent + Channel（agent）

```bash
myagents agent list                                     # 列出所有 Agent
myagents agent show <id>                                # 看某 Agent 的 effective 默认（runtime/model/permissionMode）
myagents agent enable <id>                              # 启用
myagents agent disable <id>                             # 禁用
myagents agent set <id> <key> <jsonValue>               # 改单个字段（key/value 形式，value 必须是合法 JSON）
                                                        # 受保护字段：id / channels（这俩用专用命令）
myagents agent channel list <agentId>                   # 列出某 Agent 的所有 Channel
myagents agent channel add <agentId> --type <平台> --<凭证flag> ...
                                                        # 添加 Channel（平台 = telegram / dingtalk / openclaw:xxx）
myagents agent channel remove <agentId> <channelId>     # 删除 Channel
myagents agent runtime-status                           # 看所有 Agent 的实时连接状态（在线/离线/uptime/最近消息）
```

**何时用：**
- "我那个 Agent 现在啥配置" → `agent show <id>`，按 runtime 正确解析过 effective 值
- "把 Agent X 的 model 改成 Y" → `agent set X model '"Y"'`（注意 JSON 字符串要双层引号）
- "把 permissionMode 改成 plan" → `agent set X permissionMode '"plan"'`
- "飞书 Bot 在线吗" → `agent runtime-status`（这个看运行时；`agent list` 看的是配置）
- 配 Channel 详见下方 §配置 Agent Channel 流程

`agent set` 和 `agent show` 互补：show 读 effective 值（含 runtime 分层解析），set 写**单个**字段。复杂 Channel 改动走 `agent channel`，别用 `agent set channels`——会被拒。

### Agent Runtime 发现（runtime）

```bash
myagents runtime list                                   # 4 个 runtime（builtin/claude-code/codex/gemini）的装机情况 + 版本
myagents runtime list --json                            # 机读：installed/version/path
myagents runtime describe <runtime>                     # 某 runtime 的 model 清单 + permissionMode 枚举
myagents runtime diagnose codex [--workspacePath PATH]  # Codex 的 auth/features/MCP/apps/effective-env 快照（issue #194）
myagents diagnose runtime codex                         # 同上的 sugar 写法
```

**何时用：**
- 在跑 `task create-direct --runtime X --model Y --permissionMode Z` **之前**先 `runtime describe X` 把合法值查清楚——`--help` 只列 flag，值靠这俩命令现场查，不会因为文档漂移而错
- "我装了哪些 Agent CLI" → `runtime list`
- 用户问"codex 支持什么 model" → `runtime describe codex`
- 「@oai/artifact-tool 我从终端能调用、MyAgents 里就不行」/「Codex MCP 在 MyAgents 里看不到」/「Codex 是不是用错代理了」→ `runtime diagnose codex`。它 spawn 一个临时 codex app-server，跑 `getAuthStatus` / `experimentalFeature/list` / `mcpServerStatus/list` / `app/list` 四个 RPC，把 Codex 自己看到的状态原样吐出来，省得猜。effectiveEnv 节里能看到 MyAgents 注入的代理是不是真到了子进程，feature flag 是不是真生效。

每个外部 runtime 有自己的动态 model 清单（Codex/Gemini 会 spawn CLI 查）和自己的 permissionMode 枚举（`suggest` / `auto-edit` / `full-aut