myagents-cli

name	myagents-cli
description	你正在 MyAgents 这款 AI 产品里运行——MyAgents 自带一套"产品能力"（定时任务、任务中心、想法收集、MCP 工具接入、 模型 Provider、IM Bot 渠道、社区插件、Skills 安装、MyAgents Cloud Space、Generative UI Widget、Goal 目标模式等），全部通过内置 `myagents` CLI 暴露给你。 当用户的需求**落在 MyAgents 产品能力的射程内**，就加载并使用这个 skill，用 CLI 主动帮用户把事情做掉， 而不是让用户去 GUI 点击。 典型触发场景：用户说"每天 X 点帮我 Y"（→ cron）、"记一下这个想法"（→ thought）、"派发成任务"（→ task）、 "接个 X 工具进来"（→ mcp）、"配 X 模型/Provider"（→ model）、"在飞书/钉钉/Telegram 里跟我聊"（→ agent channel）、 "装个 X 插件 / 装个 X skill"（→ plugin / skill）、"处理 Space Issue / 下载附件 / 回复 Issue"（→ space）、 "把图发到 IM 里"（→ im send-media）、"用已配置的读图模型理解图片"（→ vision analyze）、"持续执行直到目标完成"（→ goal）、 "做个图表/仪表盘" （→ widget readme）、"看下我有啥任务/定时/Runtime/版本"（→ list / status / version）、"改下应用设置"（→ config）。 即使用户没说"用 MyAgents 做"几个字，只要意图能映射到上述能力之一，就该走这个 skill。 反向边界：纯业务任务（写代码、查资料、读文件）不归这里；用户自己会话里给 AI 排任务用 im-cron MCP，不是这里。
author	MyAgents

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

你正运行在 MyAgents 产品内。MyAgents 不只是一个 chat UI，它是一套带状态的 Agent 平台：Goal 目标模式、定时任务、任务中心、IM Bot、MCP、Provider、插件、Skill、Cloud Space、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. 按 leaf 契约预览：只有精确 leaf help 明确声明支持的命令才使用 --dry-run；不支持的 mutation 会 fail closed，不能声称已预览
3. 机器可读：加 --json 解析结构化输出
4. 失败即恢复：CLI 失败响应会带 → Run: <cmd> 恢复提示，照着跑就行

安全规范

• 改配置前先读精确 leaf help——该 leaf 明确支持 --dry-run 时先预览；未声明支持时不要假装存在 preview
• API Key：用户在对话里明确给了你才写入；没给就引导他去 设置 → 对应页面 填，不要追问
• 删除前确认：用户说"删了吧"也要回读"我要删的是 X，确认吗"

生效时机

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

---

命令速查 + 何时使用

MCP 工具（mcp）

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

CLI 工具注册表（tool） — PRD 0.2.36，实验室开启后可用

这是实验功能，默认关闭。使用前先运行 myagents tool --help：

• 如果 help 提示去「设置 → 关于&反馈 → 实验室 → CLI 工具注册表」开启，说明当前会话不能创建、注册或管理用户 CLI 工具；不要继续尝试 tool-creator / myagents tool add，转而完成一次性任务或请用户打开实验开关。
• 如果 help 返回完整 list/add/remove/env 用法，才按下面流程处理。

注册的 CLI 工具会投 shim 到 ~/.myagents/bin/（全 runtime + 终端的 PATH 上）， description 自动注入所有新 session 的上下文——未来的 AI 会自己发现并使用它。 写一个新工具用 tool-creator skill（钉死 Agent-CLI 契约：非交互 / 退出码 / --json / readme 子命令 / ≤800 字 description）；这里只管注册与管理。

myagents tool list                       # 注册表总览（含 enabled 状态 + 缺失 env key）
myagents tool add <dir>                  # 注册（dir 须含 tool.json + 入口脚本；不在
                                         #  ~/.myagents/tools/ 下会自动拷入）[--dry-run]
myagents tool info <name>                # 看 manifest + enabled + 缺失 env
myagents tool enable <name>              # 进新 session 的上下文
myagents tool disable <name>             # 从上下文隐藏（shim 仍在 PATH，可手动调）
myagents tool remove <name> [--purge]    # 反注册（--purge 连工具目录一起删）
myagents tool env <name> set KEY=val     # 设 per-tool 环境变量（API key；工具启动时读）
myagents tool env <name> get             # 读（值已脱敏）
myagents tool env <name> delete KEY      # 删

何时用：

• 用户说"把这个脚本/能力注册成工具、以后直接用" → 先走 tool-creator skill 把它规范化，再 tool add
• "我有哪些自己的工具" → tool list
• 工具报缺 API key（退出码 3）→ tool env <name> set KEY=<用户提供的值>
• 注册名撞系统命令会被打回（~/.myagents/bin 在 PATH 前列，重名会遮蔽系统命令）→ 换带领域前缀的名字
• 注册成功后 MUST 在回复中告知用户：工具名 + 干什么 + 可在 设置 → 工具箱 管理

官方图片理解工具（vision）

这是 MyAgents 内置官方 CLI 工具，不属于 MCP，也不属于用户注册 tool 实验功能。它用于在当前会话启用“图片理解”工具时，让不支持多模态的主模型把本地工作区图片交给用户在「设置 → 工具箱」里配置好的读图模型分析。

myagents vision readme
myagents vision analyze --image <path> [--image <path> ...] [--prompt "what to inspect"]
myagents vision analyze --image <path> --prompt-file <workspace-relative-text-file>
myagents vision analyze --image @myagents_files/screenshot.png --prompt "Extract the error text and UI state"

约束：

• 只接受当前 MyAgents 工作区内的本地图片路径；不要传 URL。
• --prompt 是短指令；长/多行/含引号的检查指令写进当前 workspace 内的文本文件，再用 --prompt-file。
• --prompt-file 路径也按当前 workspace 安全解析；不要传 URL、symlink 或 workspace 外路径。
• 如果报“not enabled / not configured”，让用户在「设置 → 工具箱」启用图片理解并选择支持图片输入的模型。

何时用：

• 当前主模型不支持图片，但会话里出现截图 / 图片附件，并且系统提示里说明 vision 工具可用。
• 用户要求“看这张图 / 截图里写了什么 / 读一下错误信息”，先 vision analyze 拿文字观察，再基于观察继续回答。

模型 Provider（model）

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）

myagents agent list                                     # 列出所有 Agent
myagents agent list --active                            # 只列出未归档 Agent 工作区
myagents agent list --archived                          # 只列出已归档 Agent 工作区
myagents agent show <id>                                # 看某 Agent 的 effective 默认（runtime/model/permissionMode）
myagents agent enable <id>                              # 启用
myagents agent disable <id>                             # 禁用
myagents agent archive <id>                             # 归档 Agent 工作区，并暂停 proactive Channel
myagents agent unarchive <id>                           # 取消归档；若归档前是 proactive，会恢复启用
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"'
• "项目结束了，先收起来" → agent archive <id>；需要恢复时用 agent unarchive <id>
• "飞书 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）

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-auto ≠ 内置的 auto / plan / fullAgency）——别混。

Skills（skill）

myagents skill list                                     # 已装 skill（全局 + 项目级）
myagents skill info <name>                              # 某 skill 的详情
myagents skill add <url-or-spec> [--scope user|project] [--plugin X] [--skill Y] [--force] [--dry-run]
myagents skill remove <name>                            # 删除
myagents skill enable <name>                            # 启用
myagents skill disable <name>                           # 禁用
myagents skill sync                                     # 把 ~/.claude/skills 里用户自己装的同步过来

skill add 输入形态（同一 resolver 全吃）：

输入	说明
foo/bar	GitHub owner/repo 简写
https://github.com/foo/bar	完整 URL
https://github.com/foo/bar/tree/main/skills/baz	子路径，只装 baz
foo/bar@baz	仓库内多 skill 选其一
"npx skills add foo/bar --skill baz"	用户从 README 复制的整条命令（用引号包）
https://example.com/x.zip	直连 zip/tar.gz

不支持：GitLab、私有仓库、git SSH。

何时用：

• 用户贴 GitHub 链接或 npx skills add ... → 直接 skill add "<原文>"，resolver 自己剥前缀
• "装 React 最佳实践" → skill add vercel-labs/skills --skill react-best-practices
• 报错 该仓库是 Claude Plugins 市场 → 按提示加 --plugin <name>，比如 skill add anthropics/skills --plugin document-skills 一次装 docx/pdf/pptx/xlsx
• 报错 技能 X 已存在 → 跟用户确认要不要 --force 覆盖
• 用户在 ~/.claude/skills/ 自己塞了东西 MyAgents 看不见 → skill sync

定时任务（cron）

myagents cron list                                      # 列出【当前工作区】的定时任务（按作用域过滤，非全局！）
                                                        # 空结果≠系统无任务——可能在别的工作区。响应带 scope+提示文案
myagents cron list --workspace <abs>                    # 查看指定工作区的定时任务（跨工作区查看的唯一方式）
myagents cron add --name "..." --prompt "..." --schedule "..." --workspace <abs>
                                                        # --schedule "0 18 * * *" 标准 cron / --every 15 每 N 分钟
                                                        # --prompt-file <path> 也行（多行 / 含 backtick 用这个，1MB 上限）
myagents cron update <taskId> [--name X --prompt X --schedule X --every N --model X --permissionMode X]
                                                        # 改任意字段，没传的不动
myagents cron start <taskId>                            # 启动已停止的任务
myagents cron stop <taskId>                             # 停止运行中的任务
myagents cron run-now <taskId>                          # 立即手动触发一次（不影响计划）
myagents cron remove <taskId>                           # 删除
myagents cron runs <taskId> [--limit N]                 # 看执行历史
myagents cron status                                    # 概览：总数 / 运行中 / 下次执行（同样按【当前工作区】作用域，0 ≠ 全局无任务）
myagents cron exit [--reason "..."]                     # 仅在 cron 任务自己的 session 内可用，且任务的 Allow AI to exit 必须开
                                                        # AI 判断"该结束了"时主动退出当前轮
myagents cron readme                                    # 拉 cron 工具的完整使用文档（progressive disclosure）

何时用：

• "帮我每天 6 点出日报" → cron add --name "日报" --prompt "..." --schedule "0 18 * * *" --workspace /path
• "把日报的 prompt 改一下" → cron update <taskId> --prompt "新内容"
• "立刻跑一次看看" → cron run-now <taskId>
• "停了它别再跑" → cron stop（保留配置）；彻底删用 cron remove
• "上次执行成功了吗" → cron runs <taskId>
• cron exit / cron readme 是 AI 在自己 cron 任务运行中用的——给用户管 cron 用前面那一串

Goal 目标模式（goal）

Goal 是当前会话内的持续执行模式：宿主会在每轮完成后自动发起下一轮，直到 AI 主动标记完成/受阻，或用户在 UI 中取消。它复用当前 session 上下文，不是独立任务中心任务。

myagents goal get                                      # 查看当前 session 的 Goal
myagents goal create --objective-file myagents_files/goal-objective.txt   # 为当前 session 创建并启动 Goal
myagents goal update --status complete                 # AI 判断目标完成时主动退出
myagents goal update --status blocked                  # AI 判断无法继续时主动退出

何时用：

• 用户明确要求进入 Goal 时，先用标准文件工具把 objective 写入 workspace 内的文本文件，再传 --objective-file；不要把用户文本拼入 Shell 命令。
• 当前会话进入 Goal 后，你完成了用户目标 → goal update --status complete
• 你连续尝试后确认缺关键输入/外部状态，无法继续推进 → goal update --status blocked
• 用户问"现在目标是什么/状态如何" → goal get
• 不要用 goal update 表示用户取消；取消由 UI/宿主控制。

任务中心（task / thought）

myagents thought list [--tag X --query X --limit N]     # 列想法（用户先记下来、后续派发的轻量条目）
myagents thought create '...'                           # 记一条想法（首选：单引号包裹防 shell 注入；
                                                        # 用 #xxx 内联打 tag —— 没有 --tag flag）
myagents thought create --content "..."                 # 显式 flag 形态，跟单引号等价
myagents thought create --content-file <abs-path>       # 内容含多行 / CJK / shell 元字符 /
                                                        # Windows 下单引号失灵时的保底通道

myagents task list [--status X --workspaceId X --tag X --includeDeleted]
myagents task get <taskId>                              # 详情 + statusHistory + 各 .md 文档路径
myagents task create-direct --name "..." --workspaceId <id> --workspacePath <abs> \
    [--taskMdFile <path> | --taskMdContent "..."] \
    [--runtime X --model X --permissionMode X --runtimeConfig <jsonStr> --mcpEnabledServers a,b] \
    [--executor agent --executionMode once --runMode X --tags x,y --sourceThoughtId X]
myagents task create-from-alignment <alignmentSessionId> --name "..." [--run] [其它同 create-direct]
                                                        # 从 AI 对齐会话物化任务（workspaceId/Path/sourceThoughtId 自动继承）
                                                        # --run 创建后立刻派发，省一步
myagents task run <taskId>                              # 派发 todo 任务
myagents task rerun <taskId>                            # 从 blocked/stopped/done 重新派发
myagents task update-status <taskId> <status> [--message "..."]
                                                        # 状态机：todo→running→verifying→done（或 →blocked/stopped）、done→archived
myagents task append-session <taskId> <sessionId>       # 把一个聊天 session 关联到任务（任务过程中开了新会话用这个登记）
myagents task archive <taskId> [--message "..."]        # 归档（仅用户可操作；AI 走会被拒）
myagents task delete <taskId>                           # 软删除（30 天保留）

任务级 runtime/model/permissionMode 覆盖：create-direct / create-from-alignment 支持仅对该任务生效的覆盖 flag，不会改 Agent 工作区默认。典型场景："实现用 Claude Code、review 用 Codex" → 创两个任务，--runtime 不一样，工作区配置不变。

Flag	语义
--runtime	builtin / claude-code / codex / gemini，不传则继承
--model	值取决于 runtime，先 runtime describe <runtime> 查
--permissionMode	值取决于 runtime，同样先 runtime describe
--runtimeConfig	JSON 对象字符串，runtime 专属配置（罕用）
--mcpEnabledServers	逗号分隔 MCP id；"" 表示该任务显式不用 MCP

task update <taskId> 清覆盖用显式 flag：--clearProviderOverride / --clearRuntimeOverride / --clearMcpOverride。注意 --mcpEnabledServers "" 不是清回继承，而是显式无 MCP。

何时用：

• "看我还有啥没做完的" → task list --status running / task list
• "这个想法派发出去" → task create-from-alignment <sessionId> --name "..." --run
• "创个 review PR 的任务用 codex" → task create-direct ... --runtime codex --model gpt-5.2 --permissionMode full-auto
• "任务过程中我开了个新对话登记一下" → task append-session <taskId> <sessionId>
• "标记完成" → task update-status <taskId> done --message "..."
• "重新跑一遍" → task rerun <taskId>
• 只读类 task get / task list：CLI 输出会带各 .md 文档路径（task.md / verify.md / progress.md / alignment.md），用 Read/Edit/Write 直接读改即可

验证与恢复：CLI 在转发给 Rust 前会前置校验 --runtime / --model / --permissionMode，不合法直接拒绝并带 → Run: myagents runtime describe <rt> 指引；输出会打印 overridesRequested vs overridden，传了 override 但没落到持久化态会明确提示 drift。

MyAgents Cloud Space（space）

myagents space list --json
myagents space whoami --space <slug> --json
myagents space goal list --space <slug> --json
myagents space assignee list --space <slug> --json
myagents space issue create --space <slug> --title "..." --body-file issue.md \
  [--goal <goalId>] [--assignee agent:<id>|user:<id>] [--attachment <path> ...]
myagents space issue list --space <slug> --goal <goalId> --state todo --limit 30
myagents space issue view <issueId> --space <slug> --comments --json     # current Issue + latest 5 comments
myagents space issue update <issueId> --space <slug> --goal <goalId> --json
myagents space issue update <issueId> --space <slug> --clear-goal --json
myagents space issue update <issueId> --space <slug> --human-only false --json
myagents space issue comments <issueId> --space <slug> --json [--limit 20] [--cursor <opaque-cursor>]
myagents space issue comment get <issueId> <commentId> --space <slug> --json
myagents space issue comment <issueId> --space <slug> \
  [--body-file <path>] [--attachment <path> ...]
myagents space issue claim <issueId> --space <slug> --deliveryId <deliveryId> --create-attached \
  --workspaceId <id> --workspacePath <path> --name "..." --taskMdContent-file task.md
myagents space issue delivery ignore <deliveryId> --space <slug>
myagents space issue complete <issueId> --space <slug> --workspacePath <path> \
  --taskId <taskId> --body-file result.md [--attachment <path> ...] --message "completed Space issue"
myagents space issue attachment add <issueId> --space <slug> --file <path> [--file <path> ...]
myagents space attachment download <attachmentId> --space <slug> [--output myagents_files/space/file.bin]

何时用：

• 普通会话先 myagents space list --json 选择明确的 slug；所有 Space 业务命令都必须带 --space <slug>，不猜“默认社区”或上次使用的 Space。
• 当前 workspace 在该 Space 有 active registration 时，CLI 自动以 Registered Agent 身份执行；否则自动以当前 User 身份执行，权限与这个 User 在 UI 中一致。delivery-bound Session 的身份/工作区不匹配会直接拒绝，不会静默降级成 User。身份不确定时先 space whoami。
• 需要创建、筛选或移动 Issue 时，先 space goal list --json，只复制 active data.items[].id；不要把 Goal title 或 goalPathLabel 当 ID。myagents goal ... 是本地 Session Goal Mode，myagents space goal ... 是 Cloud Space Goal，两者不是同一资源。
• issue create 不传 --goal 会进入 Inbox；已发布 Issue 用 issue update --goal <goalId> 移动，使用 --clear-goal 清回 Inbox。不要用 --goal null、--goal inbox 或空字符串表达清除。更新后用 issue view --json 核对权威 goalId/goalPathLabel。
• 具体命令参数优先运行精确 leaf help，例如 myagents space issue comment --help；这些 help 是给 Agent 的完整调用说明。
• 收到 Space delivery → 先 myagents space issue view <issueId> --space <slug> --comments --json 读取当前服务端状态；delivery trigger 只用于定位，不替代当前状态。
• trigger 的 comment 标记为截断 → 用 myagents space issue comment get <issueId> <commentId> --space <slug> --json 精确读取，不要扫描分页猜触发评论。
• subscription 通知不适合当前 Agent → space issue delivery ignore 只忽略这次投送；适合承担时用 claim --create-attached 建立/复用责任和本地 Task。
• assignment 表示责任已经明确交给当前 Agent；仍用 claim --create-attached 确认并建立本地 Task/Session 关联，不要 ignore 或自行取消指派。
• Issue/评论里有附件 → 用 myagents space attachment download <attachmentId> --space <slug> 下载到当前工作区，再读取本地文件。
• 需要回写结论 → space issue comment 可原子提交正文和附件；只有附件也合法。评论附件只属于该评论，不会跑到 Issue 顶部。
• 需要给已发布的 Issue 正文单独补附件 → 用 space issue attachment add，它会立即生效并触发正常的 Issue 更新投送。
• 工作完成 → 使用一次 space issue complete --taskId ... --body-file ...，它会原子完成 Cloud 结果评论 + Issue，再将 attached Task 标为 done；成功后不要再调用 task update-status done。

安全边界：

• CLI 在 Rust 内解析并持有 User/Registered Agent token；不要让用户提供 token，也不要传显式 actor。
• Space mutation 当前不支持 preview；携带 --dry-run 会在网络前返回 DRY_RUN_UNSUPPORTED。确认写入意图后按精确 leaf help 调用，不能把失败说成已经预览。
• --body-file、--taskMdContent-file 与附件只能读取当前 workspace 内的普通文件，拒绝 symlink 和 workspace 外路径；每次最多 5 个附件、每个最多 25 MB；attachment download --output 也只能写在当前 workspace 内。
• view --comments 固定最新 5 条；更早历史使用 issue comments --limit 20 --cursor <opaque-cursor>，有 nextCursor 再继续拉。

社区插件（plugin）

myagents plugin list                                    # 已装的 OpenClaw 社区插件
myagents plugin install <npmSpec>                       # 从 npm 安装（如 @anthropic/wechat）
myagents plugin remove <pluginId>                       # 卸载

何时用：

• "装个微信插件" → plugin install <npm 包名>
• "我哪里能找到飞书插件" → 让用户去 OpenClaw 仓库找 npm 包名，再 install

安装走内置 Node.js 的 npm，可能需要 10-30 秒。卸载前会检查是否有 Channel 还在用这个插件——有的话先把 Channel 移掉。

Claude 插件（cc-plugin） — PRD 0.2.17

myagents cc-plugin list                                 # 已装 Claude 插件 + 启停状态
myagents cc-plugin install <source>                     # 来源：owner/repo / GitHub URL / 直链 zip / file:///abs
myagents cc-plugin uninstall <name> [--purgeData]       # 卸载（数据目录默认保留）
myagents cc-plugin enable <name>                        # 启用（下次 session 生效）
myagents cc-plugin disable <name>                       # 禁用
myagents cc-plugin show <id|name>                       # 详情（含 manifest + 组件清单）

与上面 plugin 的区别： cc-plugin 是 Anthropic 官方的 Claude Plugin 协议（自带 skills/agents/MCP/hooks 的目录），落在 ~/.myagents/plugins/<name>/；启用后由 SDK 自动装载组件。plugin（无前缀）则是 OpenClaw 的 IM 渠道插件，两套体系不冲突。

何时用：

• "粘个 GitHub URL 装个插件" → cc-plugin install owner/repo
• "装本地正在调的插件" → cc-plugin install file:///path/to/plugin
• "禁掉 X 插件" → cc-plugin disable X

启停 / 安装 / 卸载后会触发 SDK 柔性重启（500ms 防抖），下一次发消息时 plugin 内组件才生效。外部 Runtime（Claude Code CLI / Codex / Gemini）下不读取这里——它们各自管自己的 plugin 体系。

通用配置 + 状态（config / status / version / reload）

myagents config get <key>                               # 读，支持点号路径如 proxySettings.host
myagents config set <key> <value> [--dry-run]           # 写，value 是 JSON 字面量（字符串要带引号）
myagents status                                         # 应用整体运行状态
myagents version                                        # 应用版本号
myagents reload [--workspacePath <abs>]                 # 热加载配置（不重启进程）

何时用：

• "现在配的代理是啥" → config get proxySettings
• "把代理 host 改成 X" → config set proxySettings.host '"X"'
• "应用版本" → version
• "改完手动让它生效" → reload（多数命令已经自动 broadcast，这个是兜底）

IM 媒体下发（im）

myagents im send-media --file <绝对路径> [--caption "..."]
                                                        # 仅在 IM Bot / Agent Channel session 内可用
myagents im readme                                      # 拉 IM 工具完整文档

何时用：

• 你正在某个 IM 渠道（Telegram / 飞书 / 钉钉 / OpenClaw）的会话里跟用户聊，要发图片 / 视频 / 文件给对方时用 im send-media
• --file 必须是绝对路径，且路径白名单：必须落在 workspace / /tmp / MyAgents scratch 目录之一——这是为了防 prompt injection 把 ~/.ssh/id_rsa 之类发给聊天对方
• 不在 IM session 内调用会返回 "No IM context"，正常——这命令本来就是 session-scoped

Session 间通信（session, PRD 0.2.37）

# 让另一个 session 做新工作或接收通知；从 shell/Bash 工具调用
myagents session send <sessionId> -p "<prompt>"
myagents session send <sessionId> --prompt-file <abs-path>   # 多行/长文本(>4KB)必用,跨平台稳定

# 默认: 目标 turn 结束后,MyAgents 会把结果推回当前 session
# 仅通知:不需要结果回流时加 --no-reply
myagents session send <sessionId> -p "<prompt>" --no-reply

# 监听另一个 session 当前正在进行的工作；不创建新工作
myagents session watch <sessionId>
myagents session --help                                      # 完整用法 / EXIT CODES / 示例

何时用:

• 使用 send: 另一个 session 需要做新工作、接收通知、澄清或后续指令
• 使用 watch: 当前任务依赖另一个 session 的工作,或用户明确希望你监听另一个 session 的当前/最新结果
• 用户在对话里直接给了你一个 sessionId,让你与其交互或监听
• 不要用于答复当前用户(直接回复就行);不要用于给 IM peer 发消息(用 im send-media)
• AI 身份(from label)系统会自动从你所在 session 元数据推导——你不需要也不应该手动指定

异步语义(关键):

• send CLI 立即返回投递结果,不等待对方处理
• 默认期待结果推回:对方处理完后,你将在新 turn 收到 <myagents-session-event type="send.result">
• --no-reply:仅通知,reply 不回流(对方按自己呈现路径输出)
• target session idle/dead 不影响投递——系统会自动唤起
• watch 只观察目标 session 当前工作；目标已经 idle 时,CLI 会直接返回 <myagents-session-event type="watch.already_idle"> 和最近结果
• watch 不会向目标 session 注入新 prompt；需要新工作时用 send

Windows 安全:

• -p 内容含 \n 或 > 4KB → CLI 立即 fail-fast(exit 3),提示切到 --prompt-file
• 习惯上长 / 多行内容永远走 --prompt-file,跨平台一致

Generative UI Widget 设计文档（widget）

myagents widget readme                                  # 看有哪些 widget 模块（chart/diagram/interactive/dashboard/art）
myagents widget readme <module1> [<module2> ...]        # 拉具体模块的完整设计规范

何时用：

• 用户让你"做个图表 / 仪表盘 / SVG 流程图"前，先 widget readme <module> 拉对应模块的完整规范（含输出格式契约、palette、组件库），不要凭印象写
• 模块清单：chart（Chart.js 图表）/ diagram（SVG 流程图）/ interactive（滑块/计算器/对比卡）/ dashboard（多图表 + 控件）/ art（SVG 插画）
• 渲染输出有严格 <generative-ui-widget> 格式契约——readme 开头会说明，跳读会出错

cron readme / im readme / widget readme 都是 progressive disclosure：brief 已经在系统 prompt 里，要用时才 fetch full doc。

---

典型工作流

接入 MCP 工具

1. 从用户给的文档提取：server ID、类型（stdio/sse/http）、command 或 URL、所需环境变量
2. myagents mcp add --dry-run ... 预览
3. 给用户看预览，确认
4. 执行：mcp add → mcp enable --scope both → 配 env（如需）→ 如果是 OAuth 类的再 mcp oauth start
5. myagents mcp test <id> 实际握手测试
6. myagents reload
7. 告诉用户："发条新消息我就能用了"

配置模型服务（最常见、最有价值）

协议优先级：Anthropic 协议永远先于 OpenAI 兼容

MyAgents 基于 Claude Agent SDK，原生协议是 Anthropic Messages API。接入第三方 API 时：

1. Anthropic 协议（最优先）：原生协议，零转换开销，所有 SDK 能力（工具调用 / 流式 / Extended Thinking）都正常
2. OpenAI 兼容（兜底）：服务商只给 /v1/chat/completions 时用 --protocol openai，过协议桥接层转换，部分高级功能受限

从文档提取配置

第一步：找 Anthropic / Claude Code 接入板块（优先）

大多数支持 Anthropic 协议的服务商，会在文档里以「接入 Claude Code」的形式呈现——MyAgents 和 Claude Code 共享 SDK，所以 Claude Code 的接入方式就是我们最原生的接入方式。

文档里搜：Claude Code / Anthropic / ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY / /anthropic。

提取：

• ANTHROPIC_BASE_URL → --base-url
• 认证方式（Bearer Token vs API Key）→ --auth-type
• 模型名称列表 → --models

即使文档同时给了 OpenAI 兼容方式，只要有 Anthropic 方式就用 Anthropic。

第二步：实在没 Anthropic 才用 OpenAI 兼容

搜：OpenAI 兼容 / /v1/chat/completions / chat completions。

• API base → --base-url（通常 /v1 结尾或去掉 /chat/completions）
• 加 --protocol openai
• --upstream-format：多数 chat_completions（默认），少数新服务商支持 responses

Claude Code 环境变量 → CLI flag 映射

Claude Code 环境变量	MyAgents CLI
ANTHROPIC_BASE_URL	--base-url
ANTHROPIC_API_KEY	model set-key 设置
ANTHROPIC_AUTH_TOKEN	同上，区别在 --auth-type

--auth-type 选择：

• 文档说设 ANTHROPIC_AUTH_TOKEN → auth_token
• 文档说设 ANTHROPIC_API_KEY → api_key
• 两个都设 / 没说清 → both（默认，最安全）
• OpenRouter 等特殊服务商 → auth_token_clear_api_key

model add 完整 flag

myagents model add \
  --id <唯一ID>              # 必填
  --name <显示名>             # 必填
  --base-url <API地址>        # 必填
  --models <模型ID列表>       # 必填，逗号分隔或多次 --models
  --model-names <显示名列表>   # 可选，与 models 一一对应
  --model-series <系列名>      # 可选，默认取 provider ID
  --primary-model <默认模型>   # 可选，默认取第一个 model
  --auth-type <认证类型>       # 可选，默认 auth_token
  --protocol <协议>           # 可选，anthropic(默认) 或 openai
  --upstream-format <格式>     # 可选（仅 openai），chat_completions(默认) 或 responses
  --max-output-tokens <数字>   # 可选（仅 openai），默认 8192
  --vendor <供应商名>          # 可选，默认取 name
  --website-url <官网>         # 可选
  --dry-run

免费模型优先策略

很多 Provider 同时提供付费模型和免费模型。model verify 会用 primaryModel 发一条测试消息——如果用户还没充值，验付费模型会失败。

策略：Provider 既有免费也有付费时，把免费模型放在 --models 列表第一位，primaryModel 自动选中免费模型，验证更易过。例外：用户明确说要哪个就用哪个。

完整流程

1. model list 看是不是已有内置 Provider
2. 是内置 → 直接 model set-key
3. 要新增 → model add --dry-run ... 预览
4. 给用户看预览，确认
5. model add ... 正式加
6. model set-key <id> <key>
7. model verify <id>
8. 验证失败按报错排查：
   • 认证失败 → 检查 Key 和 --auth-type
   • 模型不存在 → 检查模型名称
   • 余额不足 → 切到免费模型验证
   • 协议不对 → --protocol 在 anthropic / openai 之间切
9. 视情况 model set-default <id>

配置 Agent Channel

myagents agent channel list <agentId>                                       # 看现有
myagents agent channel add <agentId> --type telegram --bot-token <token>
myagents agent channel add <agentId> --type feishu --feishu-app-id <id> --feishu-app-secret <secret>
myagents agent channel add <agentId> --type dingtalk --dingtalk-client-id <id> --dingtalk-client-secret <secret>
myagents agent channel remove <agentId> <channelId>

不同平台需要不同凭证（flag 名必须与配置字段一致）。OpenClaw 社区插件（如飞书 openclaw-lark、微信）的 --type 是 openclaw:<pluginId>，并需要先 plugin install 装好对应插件。