MUL-3574: update runtime and CLI docs (#4460)

* docs: update runtime and CLI docs for MUL-3574 Co-authored-by: multica-agent <github@multica.ai> * docs: address runtime docs review for MUL-3574 Co-authored-by: multica-agent <github@multica.ai> --------- Co-authored-by: J <j@multica.ai> Co-authored-by: multica-agent <github@multica.ai>
2026-07-05 13:29:44 +02:00 · 2026-06-23 17:26:12 +08:00
parent 294953ba37
commit cfc488769b
8 changed files with 189 additions and 12 deletions
--- a/apps/docs/content/docs/cli.ja.mdx
+++ b/apps/docs/content/docs/cli.ja.mdx
@@ -54,14 +54,23 @@ CI やヘッドレス環境では、ブラウザフローをスキップでき
 | `multica issue get <id>` | 単一のイシューを表示（イシューキーまたは UUID を受け取る） |
 | `multica issue create --title "..."` | 新しいイシューを作成 |
 | `multica issue update <id> ...` | イシューを更新（ステータス、優先度、担当者など） |
-| `multica issue assign <id> --agent <slug>` | エージェントに割り当て（即座にタスクをトリガー） |
-| `multica issue status <id> --set <status>` | ステータス変更のショートカット |
+| `multica issue assign <id> --to <name>` | メンバー、エージェント、またはスクワッドに割り当て（エージェントへの割り当ては実行をトリガー） |
+| `multica issue status <id> <status>` | ステータス変更のショートカット |
 | `multica issue search <query>` | キーワード検索 |
+| `multica issue children <id>` | サブイシューを stage ごとに一覧 |
+| `multica issue pull-requests <id>` | 紐付いた pull request と状態を一覧 |
 | `multica issue runs <id>` | イシュー上のエージェント実行を表示 |
+| `multica issue run-messages <task-id>` | 1 回の実行メッセージを表示 |
+| `multica issue usage <id>` | イシュー単位の集計 token 使用量を表示 |
 | `multica issue rerun <id>` | イシューの現在のエージェント担当者向けに新しいタスクを再キューイング |
+| `multica issue cancel-task <task-id>` | キュー中または実行中のタスクをキャンセル |
 | `multica issue comment <id> ...` | ネスト: コメントの表示 / 投稿 |
+| `multica issue comment resolve/unresolve <comment-id>` | コメントスレッドを解決済み / 未解決にする |
 | `multica issue subscriber <id> ...` | ネスト: 購読 / 購読解除 |
+| `multica issue metadata <id> ...` | ネスト: イシューメタデータの読み書き |
+| `multica issue label <id> ...` | ネスト: イシューのラベルを管理 |
 | `multica project list/get/create/update/delete/status` | プロジェクトの CRUD |
+| `multica label list/create/update/delete` | ワークスペースラベルの CRUD |

 ## エージェントとスキル

@@ -74,6 +83,8 @@ CI やヘッドレス環境では、ブラウザフローをスキップでき
 | `multica agent archive <slug>` | アーカイブ |
 | `multica agent restore <slug>` | アーカイブ済みのエージェントを復元 |
 | `multica agent tasks <slug>` | エージェントのタスク履歴を表示 |
+| `multica agent avatar <slug>` | エージェントのアバターをアップロード |
+| `multica agent env <slug> ...` | エージェントの custom environment variables を読み取り / 置換 |
 | `multica agent skills ...` | ネスト: スキルのアタッチ / デタッチ |
 | `multica skill list/get/create/update/delete` | スキルの CRUD |
 | `multica skill import ...` | GitHub、ClawHub、またはローカルマシンからスキルをインポート |
@@ -117,6 +128,10 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica autopilot delete <id>` | 削除 |
 | `multica autopilot runs <id>` | 実行履歴を表示 |
 | `multica autopilot trigger <id>` | 手動で実行をトリガー |
+| `multica autopilot trigger-add/update/delete <id>` | schedule または webhook trigger を管理 |
+| `multica autopilot trigger-rotate-url <id> <trigger-id>` | webhook trigger URL をローテート |
+
+`multica autopilot create/update` は、`create_issue` モードの autopilot が作成するイシューの既定購読者を設定する `--subscriber` も受け取ります。`update` では `--clear-subscribers` で削除できます。

 ## デーモンとランタイム

@@ -130,7 +145,9 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica runtime list` | 現在のワークスペースのランタイムを一覧 |
 | `multica runtime usage` | リソース使用量を表示 |
 | `multica runtime activity` | 最近のアクティビティログ |
-| `multica runtime update <id> ...` | ランタイムの構成を更新 |
+| `multica runtime update <id> ...` | ランタイム上で CLI 更新を開始 |
+| `multica runtime delete <id> [--cascade]` | ランタイムを削除し、必要なら紐付くエージェントもアーカイブ |
+| `multica runtime profile ...` | カスタム runtime profile とローカルパス上書きを管理 |

 ## その他

--- a/apps/docs/content/docs/cli.ko.mdx
+++ b/apps/docs/content/docs/cli.ko.mdx
@@ -54,14 +54,23 @@ CI나 headless 환경에서는 브라우저 플로우를 건너뛰세요. 웹
 | `multica issue get <id>` | 단일 이슈 표시(이슈 키 또는 UUID를 받음) |
 | `multica issue create --title "..."` | 새 이슈 생성 |
 | `multica issue update <id> ...` | 이슈 업데이트(상태, 우선순위, 담당자 등) |
-| `multica issue assign <id> --agent <slug>` | 에이전트에게 할당(즉시 작업을 트리거) |
-| `multica issue status <id> --set <status>` | 상태 변경 단축 명령 |
+| `multica issue assign <id> --to <name>` | 멤버, 에이전트, 또는 스쿼드에 할당(에이전트에 할당하면 실행이 트리거됨) |
+| `multica issue status <id> <status>` | 상태 변경 단축 명령 |
 | `multica issue search <query>` | 키워드 검색 |
+| `multica issue children <id>` | 하위 이슈를 stage별로 나열 |
+| `multica issue pull-requests <id>` | 연결된 pull request와 상태 나열 |
 | `multica issue runs <id>` | 이슈의 에이전트 실행 표시 |
+| `multica issue run-messages <task-id>` | 한 실행의 메시지 표시 |
+| `multica issue usage <id>` | 이슈의 집계 token 사용량 표시 |
 | `multica issue rerun <id>` | 이슈의 현재 에이전트 담당자에게 새 작업을 다시 큐에 넣기 |
+| `multica issue cancel-task <task-id>` | 대기 중이거나 실행 중인 작업 취소 |
 | `multica issue comment <id> ...` | 중첩: 댓글 보기 / 작성 |
+| `multica issue comment resolve/unresolve <comment-id>` | 댓글 스레드를 해결 / 미해결로 표시 |
 | `multica issue subscriber <id> ...` | 중첩: 구독 / 구독 취소 |
+| `multica issue metadata <id> ...` | 중첩: 이슈 metadata 읽기 / 쓰기 |
+| `multica issue label <id> ...` | 중첩: 이슈의 label 관리 |
 | `multica project list/get/create/update/delete/status` | 프로젝트 CRUD |
+| `multica label list/create/update/delete` | 워크스페이스 label CRUD |

 ## 에이전트와 스킬

@@ -74,6 +83,8 @@ CI나 headless 환경에서는 브라우저 플로우를 건너뛰세요. 웹
 | `multica agent archive <slug>` | 보관 |
 | `multica agent restore <slug>` | 보관된 에이전트 복원 |
 | `multica agent tasks <slug>` | 에이전트의 작업 기록 표시 |
+| `multica agent avatar <slug>` | 에이전트 아바타 업로드 |
+| `multica agent env <slug> ...` | 에이전트 custom environment variables 읽기 / 교체 |
 | `multica agent skills ...` | 중첩: 스킬 연결 / 분리 |
 | `multica skill list/get/create/update/delete` | 스킬 CRUD |
 | `multica skill import ...` | GitHub, ClawHub, 또는 로컬 기기에서 스킬 가져오기 |
@@ -117,6 +128,10 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica autopilot delete <id>` | 삭제 |
 | `multica autopilot runs <id>` | 실행 기록 표시 |
 | `multica autopilot trigger <id>` | 수동으로 실행 트리거 |
+| `multica autopilot trigger-add/update/delete <id>` | schedule 또는 webhook trigger 관리 |
+| `multica autopilot trigger-rotate-url <id> <trigger-id>` | webhook trigger URL 회전 |
+
+`multica autopilot create/update`는 `create_issue` 모드 autopilot이 만드는 이슈의 기본 구독자를 설정하는 `--subscriber`도 받습니다. `update`에서는 `--clear-subscribers`로 제거할 수 있습니다.

 ## 데몬과 런타임

@@ -130,7 +145,9 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica runtime list` | 현재 워크스페이스의 런타임 나열 |
 | `multica runtime usage` | 리소스 사용량 표시 |
 | `multica runtime activity` | 최근 활동 로그 |
-| `multica runtime update <id> ...` | 런타임의 구성 업데이트 |
+| `multica runtime update <id> ...` | 런타임에서 CLI 업데이트 시작 |
+| `multica runtime delete <id> [--cascade]` | 런타임 삭제, 필요하면 연결된 에이전트도 보관 |
+| `multica runtime profile ...` | 사용자 지정 runtime profile과 로컬 경로 override 관리 |

 ## 기타

--- a/apps/docs/content/docs/cli.mdx
+++ b/apps/docs/content/docs/cli.mdx
@@ -54,14 +54,23 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica issue get <id>` | Show a single issue (accepts an issue key or a UUID) |
 | `multica issue create --title "..."` | Create a new issue |
 | `multica issue update <id> ...` | Update an issue (status, priority, assignee, etc.) |
-| `multica issue assign <id> --agent <slug>` | Assign to an agent (triggers a task immediately) |
-| `multica issue status <id> --set <status>` | Shortcut to change status |
+| `multica issue assign <id> --to <name>` | Assign to a member, agent, or squad (assigning to an agent triggers a run) |
+| `multica issue status <id> <status>` | Shortcut to change status |
 | `multica issue search <query>` | Keyword search |
+| `multica issue children <id>` | List sub-issues grouped by stage |
+| `multica issue pull-requests <id>` | List linked pull requests and their status |
 | `multica issue runs <id>` | Show agent runs on an issue |
+| `multica issue run-messages <task-id>` | Show messages for one execution |
+| `multica issue usage <id>` | Show aggregated token usage for an issue |
 | `multica issue rerun <id>` | Re-enqueue a fresh task for the issue's current agent assignee |
+| `multica issue cancel-task <task-id>` | Cancel a queued or running task |
 | `multica issue comment <id> ...` | Nested: view / post comments |
+| `multica issue comment resolve/unresolve <comment-id>` | Mark a comment thread resolved or unresolved |
 | `multica issue subscriber <id> ...` | Nested: subscribe / unsubscribe |
+| `multica issue metadata <id> ...` | Nested: read / write issue metadata |
+| `multica issue label <id> ...` | Nested: manage labels on an issue |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
+| `multica label list/create/update/delete` | Workspace label CRUD |

 ## Agents and skills

@@ -74,6 +83,8 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica agent archive <slug>` | Archive |
 | `multica agent restore <slug>` | Restore an archived agent |
 | `multica agent tasks <slug>` | Show an agent's task history |
+| `multica agent avatar <slug>` | Upload an agent avatar |
+| `multica agent env <slug> ...` | Read or replace an agent's custom environment variables |
 | `multica agent skills ...` | Nested: attach / detach skills |
 | `multica skill list/get/create/update/delete` | Skill CRUD |
 | `multica skill import ...` | Import a skill from GitHub, ClawHub, or the local machine |
@@ -123,6 +134,12 @@ See [Squads](/squads) for the full model.
 | `multica autopilot delete <id>` | Delete |
 | `multica autopilot runs <id>` | Show run history |
 | `multica autopilot trigger <id>` | Trigger a run manually |
+| `multica autopilot trigger-add/update/delete <id>` | Manage schedule or webhook triggers |
+| `multica autopilot trigger-rotate-url <id> <trigger-id>` | Rotate a webhook trigger URL |
+
+`multica autopilot create/update` also accepts `--subscriber` to set default
+subscribers for issues created by a `create_issue` autopilot; update accepts
+`--clear-subscribers` to remove them.

 ## Daemon and runtimes

@@ -136,7 +153,9 @@ See [Squads](/squads) for the full model.
 | `multica runtime list` | List runtimes in the current workspace |
 | `multica runtime usage` | Show resource usage |
 | `multica runtime activity` | Recent activity log |
-| `multica runtime update <id> ...` | Update a runtime's configuration |
+| `multica runtime update <id> ...` | Initiate a CLI update on a runtime |
+| `multica runtime delete <id> [--cascade]` | Delete a runtime, optionally archiving bound agents |
+| `multica runtime profile ...` | Manage custom runtime profiles and local path overrides |

 ## Miscellaneous

--- a/apps/docs/content/docs/cli.zh.mdx
+++ b/apps/docs/content/docs/cli.zh.mdx
@@ -54,14 +54,23 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica issue get <id>` | 查看单条 issue（接受 issue key 或 UUID） |
 | `multica issue create --title "..."` | 创建新 issue |
 | `multica issue update <id> ...` | 修改 issue（状态、优先级、分配人等） |
-| `multica issue assign <id> --agent <slug>` | 分配给智能体（立即触发任务） |
-| `multica issue status <id> --set <status>` | 快捷改状态 |
+| `multica issue assign <id> --to <name>` | 分配给成员、智能体或小队（分配给智能体会触发一次运行） |
+| `multica issue status <id> <status>` | 快捷改状态 |
 | `multica issue search <query>` | 关键字搜索 |
+| `multica issue children <id>` | 按 stage 分组查看子 issue |
+| `multica issue pull-requests <id>` | 查看关联 PR 及其状态 |
 | `multica issue runs <id>` | 查看 issue 上智能体跑过的任务 |
+| `multica issue run-messages <task-id>` | 查看某次执行的消息 |
+| `multica issue usage <id>` | 查看单个 issue 聚合 token 用量 |
 | `multica issue rerun <id>` | 给该 issue 当前的智能体分配人重新创建一条任务 |
+| `multica issue cancel-task <task-id>` | 取消排队中或运行中的任务 |
 | `multica issue comment <id> ...` | 嵌套：看 / 发评论 |
+| `multica issue comment resolve/unresolve <comment-id>` | 标记评论线程已解决 / 未解决 |
 | `multica issue subscriber <id> ...` | 嵌套：订阅 / 取消订阅 |
+| `multica issue metadata <id> ...` | 嵌套：读写 issue metadata |
+| `multica issue label <id> ...` | 嵌套：管理 issue 上的 label |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
+| `multica label list/create/update/delete` | Workspace label CRUD |

 ## 智能体和 Skill

@@ -74,6 +83,8 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica agent archive <slug>` | 归档 |
 | `multica agent restore <slug>` | 恢复归档的智能体 |
 | `multica agent tasks <slug>` | 查看智能体的任务历史 |
+| `multica agent avatar <slug>` | 上传智能体头像 |
+| `multica agent env <slug> ...` | 读取或替换智能体的 custom environment variables |
 | `multica agent skills ...` | 嵌套：挂载 / 卸载 Skill |
 | `multica skill list/get/create/update/delete` | Skill CRUD |
 | `multica skill import ...` | 从 GitHub / ClawHub / 本机导入 Skill |
@@ -117,6 +128,10 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica autopilot delete <id>` | 删除 |
 | `multica autopilot runs <id>` | 查看运行历史 |
 | `multica autopilot trigger <id>` | 手动触发一次 |
+| `multica autopilot trigger-add/update/delete <id>` | 管理 schedule 或 webhook trigger |
+| `multica autopilot trigger-rotate-url <id> <trigger-id>` | 轮换 webhook trigger URL |
+
+`multica autopilot create/update` 还支持 `--subscriber`，为 `create_issue` 模式创建的 issue 设置默认订阅人；`update` 支持 `--clear-subscribers` 清空默认订阅人。

 ## 守护进程和运行时

@@ -130,7 +145,9 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica runtime list` | 列出当前工作区的 runtime |
 | `multica runtime usage` | 查看资源使用情况 |
 | `multica runtime activity` | 近期活动记录 |
-| `multica runtime update <id> ...` | 更新 runtime 配置 |
+| `multica runtime update <id> ...` | 在某个 runtime 上触发 CLI 更新 |
+| `multica runtime delete <id> [--cascade]` | 删除 runtime，可选择同时归档绑定的智能体 |
+| `multica runtime profile ...` | 管理自定义 runtime profile 和本机路径覆盖 |

 ## 杂项

--- a/apps/docs/content/docs/daemon-runtimes.ja.mdx
+++ b/apps/docs/content/docs/daemon-runtimes.ja.mdx
@@ -58,6 +58,29 @@ graph TD
 - **同じデーモン、ワークスペース、ツールは、ちょうど 1 つのランタイムを作ります** — デーモンを再起動しても重複レコードは生まれません
 - Multica UI の**ランタイム**ページがこれらの行を一覧表示します

+## カスタムランタイムプロファイル
+
+組み込み provider 検出は一般的なツールを対象にしていますが、Multica が対応するプロトコルファミリーで動作し、ワークスペース固有の起動コマンドが必要な AI CLI には **custom runtime profile** を定義できます。Runtimes UI か CLI で管理します。
+
+```bash
+multica runtime profile list
+multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
+multica runtime profile update <profile-id> --command-name agent
+multica runtime profile delete <profile-id>
+```
+
+入力するコマンドは shell 文字列ではなく argv 形式です。Multica は実行ファイル名と固定引数を保存し、デーモンは `exec.Command(command_name, fixed_args...)` で直接起動します。通常の引数、引用符、バックスラッシュエスケープは使えますが、パイプ、リダイレクト、`&&`、`;`、バッククォート、`$VAR` / `$(...)` 展開は使えません。shell の動作が必要な場合は wrapper script を使ってください。
+現在、コマンドと引数の解析は Runtimes UI が担当します。CLI の profile コマンドは profile 行とローカルのパス上書きを管理します。
+
+デスクトップアプリから起動したデーモンが、ターミナルでは動くコマンドを見つけられない場合は、そのマシンで絶対パスを固定できます。
+
+```bash
+multica runtime profile set-path <profile-id> --path /abs/path/to/agent
+multica runtime profile unset-path <profile-id>
+```
+
+profile のコマンドや引数の変更は、デーモンが再登録された後に新しく取得するタスクへ適用されます。実行中のタスクは開始時の引数を使い続けます。混在デプロイでは、先に server をアップグレードしてから daemon を順次更新することを推奨します。`fixed_args` の入力は server 側の Runtimes UI が担い、`failed_profiles` 登録レポートも server が表示します。古いコンポーネントは未知のフィールドを明示的に失敗させず無視することがあるため、server を先に更新すると rollout を観測しやすくなります。
+
 <Callout type="info">
 **クラウドランタイムが近日提供されます。** 現在は順番待ちリストの段階です。提供が始まれば、ローカルのデーモンを実行せずに Multica Cloud 上で直接エージェントタスクを実行できるようになります。[ダウンロードページ](https://multica.ai/download)でメールアドレスを登録すると通知を受け取れます。
 </Callout>
--- a/apps/docs/content/docs/daemon-runtimes.ko.mdx
+++ b/apps/docs/content/docs/daemon-runtimes.ko.mdx
@@ -58,6 +58,29 @@ graph TD
 - **같은 데몬, 워크스페이스, 도구는 정확히 하나의 런타임을 만듭니다.** 데몬을 재시작해도 중복 레코드가 생기지 않습니다
 - Multica UI의 **런타임** 페이지가 이 행들을 나열합니다

+## 사용자 지정 런타임 프로필
+
+기본 provider 감지는 일반적인 도구를 다룹니다. 팀에서 Multica가 지원하는 프로토콜 패밀리로 동작하지만 워크스페이스별 실행 명령이 필요한 AI CLI를 쓰는 경우에는 **custom runtime profile**을 정의할 수 있습니다. Runtimes UI 또는 CLI에서 관리합니다.
+
+```bash
+multica runtime profile list
+multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
+multica runtime profile update <profile-id> --command-name agent
+multica runtime profile delete <profile-id>
+```
+
+명령은 shell 문자열이 아니라 argv 형식입니다. Multica는 실행 파일 이름과 고정 인수를 저장하고, 데몬은 `exec.Command(command_name, fixed_args...)`로 직접 실행합니다. 일반 인수, 따옴표, 백슬래시 이스케이프는 지원하지만 파이프, 리다이렉션, `&&`, `;`, 백틱, `$VAR` / `$(...)` 확장은 지원하지 않습니다. shell 동작이 필요하면 wrapper script를 사용하세요.
+현재 명령과 인수 파싱은 Runtimes UI가 담당합니다. CLI의 profile 명령은 profile 행과 로컬 경로 override를 관리합니다.
+
+데스크톱 앱에서 시작한 데몬이 터미널에서는 동작하는 명령을 찾지 못한다면, 해당 기기에서 절대 경로를 고정할 수 있습니다.
+
+```bash
+multica runtime profile set-path <profile-id> --path /abs/path/to/agent
+multica runtime profile unset-path <profile-id>
+```
+
+profile의 명령이나 인수 변경은 데몬이 다시 등록된 뒤 새로 가져오는 작업부터 적용됩니다. 이미 실행 중인 작업은 시작할 때의 인수를 유지합니다. 혼합 배포에서는 server를 먼저 업그레이드한 뒤 daemon을 순차적으로 업데이트하는 것을 권장합니다. `fixed_args` 입력은 server 쪽 Runtimes UI가 담당하고, `failed_profiles` 등록 보고도 server가 표시합니다. 오래된 구성요소는 알 수 없는 필드를 명확히 실패시키기보다 무시할 수 있으므로 server를 먼저 올리면 rollout을 더 잘 관찰할 수 있습니다.
+
 <Callout type="info">
 **클라우드 런타임이 곧 제공됩니다.** 현재는 대기자 명단 단계입니다. 제공이 시작되면 로컬 데몬을 실행하지 않고도 Multica Cloud에서 직접 에이전트 작업을 실행할 수 있습니다. [다운로드 페이지](https://multica.ai/download)에서 이메일로 등록하면 알림을 받을 수 있습니다.
 </Callout>
--- a/apps/docs/content/docs/daemon-runtimes.mdx
+++ b/apps/docs/content/docs/daemon-runtimes.mdx
@@ -58,6 +58,44 @@ Key points:
 - **The same daemon, workspace, and tool produces exactly one runtime** — restarting the daemon never creates duplicate records
 - The **Runtimes** page in the Multica UI lists these rows

+## Custom runtime profiles
+
+Built-in provider detection covers the common tools, but teams can also define
+**custom runtime profiles** for AI CLIs that speak one of Multica's supported
+protocol families and need a workspace-specific launch command. Profiles are
+managed from the Runtimes UI or the CLI:
+
+```bash
+multica runtime profile list
+multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
+multica runtime profile update <profile-id> --command-name agent
+multica runtime profile delete <profile-id>
+```
+
+The command is argv-oriented, not a shell string. Multica stores an executable
+name plus fixed arguments, then the daemon launches it directly with
+`exec.Command(command_name, fixed_args...)`. Plain arguments, quotes, and
+backslash escaping are supported; pipes, redirects, `&&`, `;`, backticks, and
+`$VAR` / `$(...)` expansion are not. Use a wrapper script when the runtime needs
+shell behavior. Today the Runtimes UI owns command-and-argument parsing; the CLI
+profile commands manage the profile row and local path overrides.
+
+If a desktop-launched daemon cannot find a command that works in your terminal,
+pin the absolute path on that machine:
+
+```bash
+multica runtime profile set-path <profile-id> --path /abs/path/to/agent
+multica runtime profile unset-path <profile-id>
+```
+
+Profile command or argument edits apply to newly claimed tasks after the daemon
+re-registers. Running tasks keep the launch arguments they started with. For
+mixed deployments, upgrade the server before rolling out newer daemons: the
+server-side Runtimes UI stores `fixed_args`, and the server is what surfaces
+`failed_profiles` registration reports. Older components may ignore fields they
+do not understand instead of failing loudly, so treating the server upgrade as
+the first step keeps the rollout observable.
+
 <Callout type="info">
 **Cloud runtimes are coming**, currently in a waitlist phase. Once available, you'll be able to execute agent tasks directly on Multica Cloud without running a local daemon. Sign up with your email on the [download page](https://multica.ai/download) to get notified.
 </Callout>
--- a/apps/docs/content/docs/daemon-runtimes.zh.mdx
+++ b/apps/docs/content/docs/daemon-runtimes.zh.mdx
@@ -58,6 +58,29 @@ graph TD
 - **同一个守护进程在同一个工作区同一款工具上只会有一条运行时**——重启守护进程不会产生重复记录
 - Multica 界面的 **Runtimes** 页面列的就是这些行

+## 自定义运行时配置
+
+内置 provider 探测覆盖常见工具；如果团队有一款兼容 Multica 已支持协议族、但需要工作区级启动命令的 AI CLI，可以定义 **custom runtime profile**。你可以在 Runtimes UI 里管理，也可以用 CLI：
+
+```bash
+multica runtime profile list
+multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
+multica runtime profile update <profile-id> --command-name agent
+multica runtime profile delete <profile-id>
+```
+
+这里填写的是 argv 风格命令，不是 shell 字符串。Multica 存的是可执行文件名和固定参数，守护进程会直接用 `exec.Command(command_name, fixed_args...)` 启动。支持普通参数、引号和反斜杠转义；不支持管道、重定向、`&&`、`;`、反引号、`$VAR` / `$(...)` 展开。需要 shell 行为时，用 wrapper script 包一层。
+目前命令和参数的解析入口在 Runtimes UI；CLI 的 profile 命令负责管理 profile 记录和本机路径覆盖。
+
+如果桌面应用拉起的守护进程找不到你在终端里能运行的命令，可以在这台机器上固定绝对路径：
+
+```bash
+multica runtime profile set-path <profile-id> --path /abs/path/to/agent
+multica runtime profile unset-path <profile-id>
+```
+
+修改 profile 的命令或参数后，已开始的任务仍使用启动时的参数；守护进程重新注册后，新领取的任务才会使用新配置。混合版本部署时，建议先升级 server，再逐步升级 daemon：`fixed_args` 的录入在 server 侧 Runtimes UI，`failed_profiles` 注册报告也由 server 展示。旧组件可能会忽略自己不认识的字段，而不是明确报错；先升 server 能让 rollout 更可观察。
+
 <Callout type="info">
 **云端运行时即将开放**，目前处于等待名单阶段。上线后，你无需在本地运行守护进程，即可在 Multica Cloud 上直接执行智能体任务。在 [下载页面](https://multica.ai/download) 登记邮箱以获取通知。
 </Callout>