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）

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

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）；这里只管注册与管理。

bash
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 实验功能。它用于在当前会话启用“图片理解”工具时，让不支持多模态的主模型把本地工作区图片交给用户在「设置 → 工具箱」里配置好的读图模型分析。

bash
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）

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 current --json                          # 只看当前 Agent/workspace/Session
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）
                                                        # key 仅限 enabled/runtime/runtimeConfig/providerId/model/permissionMode
                                                        # id / channels 用专用命令；未知 key 会在写盘前拒绝
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 写单个字段。只使用上面列出的 canonical key；provider / permission 不是 alias，分别改用 providerId / permissionMode。providerId/model/permissionMode 会先按当前 Provider 的 credential/readiness 与 model 目录校验，再同步 Agent 权威记录、Project 兼容镜像和运行中的 Channel；Managed Codex 的 permissionMode 可传 suggest/auto-edit/no-restrictions 或产品值 plan/auto/fullAgency，落盘统一规范化为产品值。full-auto 无法无损映射（它保留 workspace-write sandbox，而 fullAgency 会投影成 no-restrictions），因此 setter 会拒绝。复杂 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-auto ≠ 内置的 auto / plan / fullAgency）——别混。

Skills（skill）

bash
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>                           # 禁用非 Required Skill；Required System Skill 会拒绝
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

定时与未来自动化 Task

bash
myagents task readme                                    # 统一自动化模型与当前命令
myagents agent current --json                          # 仅诊断当前 Agent/workspace/Session
myagents task get <taskId> --json                       # 权威配置与运行状态
myagents task run <taskId>                              # 首次启用 Todo Task
myagents task start <taskId>                            # 恢复 schedule；看回执 nextExecutionAt
myagents task stop <taskId>                             # 暂停并停止活跃执行
myagents task runs <taskId> [--limit N]                 # 看 AI 执行历史
myagents task run-now <taskId>                          # 绕过 Detector 立即执行
myagents task exit [--reason "..."]                     # 仅在允许 AI exit 的 Task run 内

定时、未来唤醒、循环执行和“满足条件才处理”是同一类 Task 意图。先加载 myagents-task-automation，由它选择普通 always 激活或 command Detector，并完成创建、回读和启动。不要让用户先选择 Cron 或 Sensor。

myagents cron ... 继续作为旧用户/脚本的兼容 alias，但不是 Agent 新建自动化的规范入口。不要调用系统 cron/crontab/at/launchctl/schtasks。

Goal 目标模式（goal）

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

bash
myagents goal get                                      # 查看当前 session 的 Goal
myagents goal create --objective-file goal-objective.txt --max-executions 12   # 本地任意普通文本文件；可选 deadline/max/AI exit 条件
myagents goal update --status complete                 # AI 判断目标完成时主动退出
myagents goal update --status blocked                  # AI 判断无法继续时主动退出

何时用：

• 用户明确要求进入 Goal 时，先用标准文件工具把 objective 写入本地文本文件（workspace 或系统 temp 均可），再传 --objective-file；不要把用户文本拼入 Shell 命令。可用 --deadline <ISO-8601-with-offset>、--max-executions <正整数>、--ai-can-exit <true|false> 设置已有结束条件；deadline 是最晚停止时间，不是延迟开始。
• 当前会话进入 Goal 后，你完成了用户目标 → goal update --status complete
• 你连续尝试后确认缺关键输入/外部状态，无法继续推进 → goal update --status blocked
• 用户问"现在目标是什么/状态如何" → goal get
• 不要用 goal update 表示用户取消；取消由 UI/宿主控制。

任务中心（task / thought）

用户要定时、未来唤醒、循环执行或满足条件才叫醒 AI 时，统一加载 myagents-task-automation。command Detector 的协议、fixture 和测试由该 Skill 按需路由到自己的 reference；这里仅保留 Task Center 的通用命令索引。

bash
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 --tag X --query X --limit N --includeDeleted]
                                                        # 默认当前 workspace；JSON 是紧凑投影
myagents task get <taskId>                              # 详情 + statusHistory + 各 .md 文档路径
myagents task create-direct --name "..." \
    [--taskMdFile <path> | --taskMdContent "..."] \
    [--runtime X --providerId 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 start <taskId>                            # 按保留 anchor 恢复，以 nextExecutionAt 为准
myagents task stop <taskId>                             # 暂停 schedule 并停止活跃执行
myagents task runs <taskId> [--limit N]                 # 查看最近 AI 执行历史
myagents task exit [--reason "..."]                     # 仅在允许 AI exit 的 scheduled Task 内
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>                           # 不可恢复地移出产品使用；不删工作区脚本

create-direct 和 task list 正常会继承当前 workspace，不需要先枚举 Agent 再手工拼 workspaceId/path；只有明确跨 workspace 时才传两者。myagents agent current --json 是紧凑诊断入口，不是 happy path 前置步骤。

创建 scheduled/recurring Task 可用 --deadline <ISO-8601-with-offset>、--maxExecutions <正整数>、--aiCanExit true|false 设置结束条件；quiet Detector 检查不消耗 maxExecutions。固定 interval 第一次 run 默认约 2 秒后产生首次 tick；要延后首次机会时传 --startAt <ISO-8601-with-offset>。Cron 等下一个墙钟点，scheduled 等 dispatchAt。

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

| Flag | 语义 | |------|------| | --runtime | builtin / claude-code / codex / gemini，不传则继承 | | --providerId | builtin Provider id；必须与 --model 成对设置，不传则继承 | | --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 list --json 只返回紧凑发现字段和 sessionCount，不会展开历史 sessionIds；拿到 ID 后用 task get 读取完整状态与各 .md 文档路径

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

归档与删除：task archive 是仅用户可执行、长期可恢复的归档状态，Agent 调用会被 Task authority 拒绝；task delete 经确认后不可恢复，没有 30 天恢复或 undelete 承诺。删除会停止调度并清平台 Trigger state/pending activation，但内部 tombstone/审计仍用于 authority 与迁移安全，工作区脚本和脚本自持状态不归 TaskStore 删除。

MyAgents Cloud Space（space）

bash
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 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。
• CLI 只有在当前 Session 持久化了精确的 spaceId + registeredAgentId origin 时，才以该 Registered Agent 身份执行；显式 legacy Agent ID 仅作旧调用兼容。workspace 只校验执行边界，绝不用于猜测 actor。没有 Registered Agent origin 的普通 Session 始终使用当前 User 身份；origin、Space 或 workspace 不匹配会直接拒绝，不会静默降级。身份不确定时先 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 通知只表示该 Issue 在路由时匹配订阅，不等于已经指派责任。读取当前 Issue 后，可以不做进一步动作、评论或更新而不 claim；只有确认该 Agent 应负责完成时，才用 claim（需要持久本地执行跟踪时再加 --create-attached）。Delivery 会由本地 connector 自动确认，不存在 Agent-facing ignore/handled/acknowledge 命令。
• 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）

bash
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

bash
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）

bash
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）

bash
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

Agent 身份与 Session 协作（agent / session, PRD 0.4.3）

每个 user-visible Workspace 都有一个稳定 Agent identity。Agent 是工作区 及其执行默认的长期地址；enabled=false 只关闭 channel / heartbeat 等主动 能力，不会取消身份，也不妨碍显式发起 Session。一个 Agent 可以拥有多个 相互隔离的 Session。

bash
# 先发现 Agent，并确认哪个是当前 CLI 调用方
myagents agent list
myagents agent show <agentId>

# 查看某 Agent 最近可复用的历史上下文（只读，不唤醒）
myagents session list --agent <agentId> [--limit 10]

# 在目标 Agent 下开启干净的新上下文
myagents session start --agent <agentId> -p "<prompt>"
myagents session start --agent <agentId> --prompt-file <abs-path>

# 在已知 Session 的既有上下文里继续做新工作
myagents session send <sessionId> -p "<prompt>"
myagents session send <sessionId> --prompt-file <abs-path>   # 多行/长文本(>4KB)必用,跨平台稳定

# start / send 默认在目标 turn 结束后把结果推回当前 Session
# 仅通知、不需要结果回流时加 --no-reply
myagents session start --agent <agentId> -p "<prompt>" --no-reply

# 只观察另一个 Session；不注入新工作
myagents session watch <sessionId>
myagents agent --help                                        # Agent identity 完整契约
myagents session --help                                      # 完整用法 / EXIT CODES / 示例

何时用:

• 使用 agent list/show: 发现目标 Agent、当前调用方身份和目标执行默认
• 使用 session list --agent: 判断最近上下文是否值得复用；它不证明目标正在运行
• 使用 start: 需要目标 Agent 在全新隔离上下文中执行
• 使用 send: 另一个 session 需要做新工作、接收通知、澄清或后续指令
• 使用 watch: 当前任务依赖另一个 session 的工作,或用户明确希望你监听另一个 session 的当前/最新结果
• start 创建 fresh context；send 保留现有 context；watch 不注入工作
• 不要用于答复当前用户(直接回复就行);不要用于给 IM peer 发消息(用 im send-media)
• AI 身份(from label)系统会自动从你所在 session 元数据推导——你不需要也不应该手动指定
• 只使用 discovery 命令返回的 ID，不猜 ID，也不用 workspace path 充当 selector

异步语义(关键):

• start / send CLI 成功只表示首条请求已接纳，不表示工作完成
• start 必须从真实 MyAgents Session 发起；目标按自己的 runtime/model/permission/MCP/plugin/tool 配置执行，不接受调用方覆盖
• start receipt 返回新的 sessionId、messageId；messageId 对应稍后 send.result.requestEventId
• 默认期待结果推回：对方处理完后，你将在新 turn 收到 <myagents-session-event type="send.result">
• --no-reply:仅通知,reply 不回流(对方按自己呈现路径输出)
• send 的 target session idle/dead 不影响投递——系统会自动唤起
• watch 只观察目标 session 当前工作；目标已经 idle 时,CLI 会直接返回 <myagents-session-event type="watch.already_idle"> 和最近结果
• watch 不会向目标 session 注入新 prompt；需要新工作时用 send
• 若 start 返回 admission unconfirmed，保留 receipt IDs，用 session list --agent 辅助观察，不要自动重试

Windows 安全:

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

Generative UI Widget 设计文档（widget）

bash
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 开头会说明，跳读会出错

task 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 之间切

1. 视情况 model set-default <id>

配置 Agent Channel

bash
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 装好对应插件。