openclaw.plugin.json

{
  "id": "openclaw-code-agent",
  "name": "Code Agent",
  "description": "Multi-session coding-agent orchestration from OpenClaw chat",
  "version": "4.7.8",
  "contracts": {
    "tools": [
      "agent_launch",
      "agent_sessions",
      "agent_kill",
      "agent_output",
      "agent_respond",
      "agent_request_plan_approval",
      "agent_request_worktree_decision",
      "agent_send_plan_offer",
      "agent_stats",
      "agent_repo_policy",
      "agent_merge",
      "agent_pr",
      "agent_worktree_cleanup",
      "agent_worktree_status",
      "agent_goal_launch",
      "agent_goal_status",
      "agent_goal_stop",
      "agent_goal_edit"
    ]
  },
  "configContracts": {
    "dangerousFlags": [
      {
        "path": "permissionMode",
        "equals": "bypassPermissions"
      },
      {
        "path": "planApproval",
        "equals": "approve"
      },
      {
        "path": "defaultWorktreeStrategy",
        "equals": "auto-merge"
      },
      {
        "path": "defaultWorktreeStrategy",
        "equals": "auto-pr"
      }
    ]
  },
  "activation": {
    "onStartup": true,
    "onCommands": [
      "agent",
      "agent_kill",
      "agent_output",
      "agent_respond",
      "agent_sessions",
      "agent_stats",
      "agent_policy",
      "agent_goal",
      "agent_goal_status",
      "agent_goal_stop",
      "agent_goal_edit"
    ]
  },
  "setup": {
    "requiresRuntime": false
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "maxSessions": {
        "type": "number",
        "default": 20
      },
      "harnesses": {
        "type": "object",
        "description": "Per-harness launch defaults and model restrictions.",
        "default": {
          "codex": {
            "defaultModel": "gpt-5.6-sol",
            "allowedModels": [
              "gpt-5.6-sol",
              "gpt-5.6-terra",
              "gpt-5.6-luna"
            ],
            "reasoningEffort": "medium",
            "fastMode": false
          },
          "claude-code": {
            "defaultModel": "anthropic/claude-sonnet-4-7",
            "allowedModels": [
              "sonnet",
              "opus"
            ]
          },
          "opencode": {}
        },
        "additionalProperties": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "defaultModel": {
              "type": "string",
              "description": "Default model for this harness when agent_launch omits model. For experimental OpenCode, omit this to use OpenCode's configured provider default."
            },
            "allowedModels": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Restrict which models can be used with this harness. Empty or omitted means no restriction."
            },
            "reasoningEffort": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high",
                "xhigh",
                "max"
              ],
              "description": "Harness-specific reasoning effort. Used by Codex and passed to Claude Code when configured."
            },
            "fastMode": {
              "type": "boolean",
              "default": false,
              "description": "Codex-only fast service-tier mode. When true under harnesses.codex, new Codex App Server thread/resume/turn payloads include service_tier=\"fast\"."
            }
          }
        }
      },
      "defaultModel": {
        "type": "string",
        "description": "Deprecated legacy default model. Mapped to harnesses[defaultHarness].defaultModel."
      },
      "model": {
        "type": "string",
        "description": "Deprecated legacy Codex model override. Use harnesses.codex.defaultModel instead."
      },
      "reasoningEffort": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "xhigh",
          "max"
        ],
        "description": "Deprecated legacy Codex reasoning effort. Use harnesses.codex.reasoningEffort instead."
      },
      "defaultWorkdir": {
        "type": "string",
        "description": "Default working directory for new sessions. Because the default worktree strategy is 'delegate', this should normally be a git repository root unless defaultWorktreeStrategy is changed to 'off'."
      },
      "idleTimeoutMinutes": {
        "type": "number",
        "default": 15,
        "description": "Idle timeout in minutes for multi-turn sessions before auto-kill"
      },
      "sessionGcAgeMinutes": {
        "type": "number",
        "default": 1440,
        "description": "TTL in minutes before terminal runtime sessions are evicted from memory (persisted metadata remains resumable)."
      },
      "maxPersistedSessions": {
        "type": "number",
        "default": 10000,
        "description": "Maximum number of completed sessions to keep in memory for resume. In practice, the 24h GC TTL (`sessionGcAgeMinutes`) is the primary retention control."
      },
      "fallbackChannel": {
        "type": "string",
        "description": "Fallback notification channel. Prefer a fully routable value such as 'telegram|123456789' or 'telegram|my-bot|123456789'; a bare provider like 'telegram' is only a weak fallback."
      },
      "permissionMode": {
        "type": "string",
        "default": "plan",
        "enum": [
          "default",
          "plan",
          "bypassPermissions"
        ],
        "description": "Default plugin orchestration mode for coding-agent sessions. This controls OpenClaw plan/default/bypass behavior and is separate from the fixed Codex execution policy."
      },
      "agentChannels": {
        "type": "object",
        "description": "Map of agent working directories to notification channels",
        "additionalProperties": {
          "type": "string"
        }
      },
      "maxAutoResponds": {
        "type": "number",
        "default": 10,
        "description": "Maximum consecutive auto-responds per session before requiring user input"
      },
      "planApproval": {
        "type": "string",
        "default": "delegate",
        "enum": [
          "approve",
          "ask",
          "delegate"
        ],
        "description": "Plan approval behavior. 'delegate' (default): orchestrator must review the full plan, then approve low-risk plans or escalate to the user. 'ask': always forwards plans to the user for approval. 'approve': orchestrator can auto-approve after verification."
      },
      "defaultHarness": {
        "type": "string",
        "enum": ["claude-code", "codex", "opencode"],
        "default": "claude-code",
        "description": "Default agent harness when agent_launch omits the harness parameter. OpenCode is available as an experimental harness."
      },
      "defaultWorktreeStrategy": {
        "type": "string",
        "default": "delegate",
        "enum": ["off", "manual", "ask", "delegate", "auto-merge", "auto-pr"],
        "description": "Default worktree strategy for all new sessions when agent_launch omits worktree_strategy. Repo integration policy still governs whether merge or PR follow-through is allowed. 'delegate' (default) creates an isolated worktree and wakes the orchestrator to decide follow-through autonomously. 'off' = no worktree. 'manual' = create worktree, no automatic action. 'ask' = notify the user with state-aware buttons such as Merge, Open PR, View PR, Sync PR, Later, and Discard when policy allows them. 'auto-merge' = request automatic merge to base branch on completion. 'auto-pr' = request automatic GitHub PR creation/update on completion."
      },
      "worktreeDir": {
        "type": "string",
        "description": "Base directory for agent worktrees. Defaults to <repoRoot>/.worktrees when unset. Overridden by OPENCLAW_WORKTREE_DIR env var."
      },
      "allowedModels": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Deprecated legacy global model restriction. Use harnesses.<name>.allowedModels instead."
      }
    }
  },
  "uiHints": {
    "fallbackChannel": {
      "label": "Fallback notification channel",
      "help": "Optional but recommended. Default channel used when no workspace-specific agentChannels entry matches the session workdir. Prefer a fully routable channel string; bare providers are only weak fallbacks.",
      "placeholder": "telegram|my-bot|123456789"
    },
    "agentChannels": {
      "label": "Workspace notification channels",
      "help": "Map absolute working-directory paths to notification channels so each workspace routes session updates to the right chat.",
      "sensitive": true,
      "advanced": true
    },
    "defaultWorkdir": {
      "label": "Default working directory",
      "help": "Base directory used for new sessions when agent_launch does not provide a workdir. With the default delegated worktree strategy, choose a git repository root; use the advanced worktree strategy setting to disable worktrees for non-git directories.",
      "placeholder": "/home/user/project"
    },
    "harnesses": {
      "label": "Harness configuration",
      "help": "Per-harness defaults and model restrictions. Set harnesses.codex.fastMode=true to send service_tier=\"fast\" on Codex App Server thread/resume/turn payloads for Codex sessions. OpenCode is experimental; leave harnesses.opencode.defaultModel unset to use OpenCode's provider default, or pass provider/model explicitly. Default: {\"codex\":{\"defaultModel\":\"gpt-5.6-sol\",\"allowedModels\":[\"gpt-5.6-sol\",\"gpt-5.6-terra\",\"gpt-5.6-luna\"],\"reasoningEffort\":\"medium\",\"fastMode\":false},\"claude-code\":{\"defaultModel\":\"anthropic/claude-sonnet-4-7\",\"allowedModels\":[\"sonnet\",\"opus\"]},\"opencode\":{}}.",
      "advanced": true
    },
    "maxSessions": {
      "label": "Maximum concurrent sessions",
      "help": "Upper limit on concurrently running coding-agent sessions.",
      "advanced": true
    },
    "idleTimeoutMinutes": {
      "label": "Idle timeout (minutes)",
      "help": "Minutes a paused multi-turn session can remain idle before the plugin auto-kills it.",
      "advanced": true
    },
    "defaultHarness": {
      "label": "Default harness",
      "help": "Choose the harness you expect to use most often. Pick Codex only when the Codex command and local auth are ready on this machine. Pick OpenCode only for experimental use when local opencode >= 1.16.2 and provider auth are ready.",
      "placeholder": "claude-code"
    },
    "permissionMode": {
      "label": "Default permission mode",
      "help": "Default plugin orchestration mode used when new coding-agent sessions are launched. Use this for plan/default/bypass behavior; Codex execution stays fixed to 'never'.",
      "advanced": true
    },
    "planApproval": {
      "label": "Plan approval policy",
      "help": "Choose whether plans are delegated to the orchestrator for full-plan review first (`delegate`, default), always sent to the user with Approve/Revise/Reject buttons, or auto-approved.",
      "advanced": true
    },
    "defaultWorktreeStrategy": {
      "label": "Default worktree strategy",
      "help": "Applies to all sessions that don't specify worktree_strategy explicitly. Repo policy can downgrade unsafe or impossible merge/PR follow-through. 'delegate' (default) creates a worktree and wakes the orchestrator to decide follow-through. 'off' disables worktrees globally. 'ask' sends state-aware inline worktree buttons such as Merge, Open PR, View PR, Sync PR, Later, and Discard when policy allows them.",
      "advanced": true
    }
  },
  "skills": [
    "./skills"
  ]
}