From 113c4f4e9042588416dca77fad19384c8ef5bb06 Mon Sep 17 00:00:00 2001 From: Bohan Jiang <52446949+Bohan-J@users.noreply.github.com> Date: Sun, 17 May 2026 17:20:41 +0800 Subject: [PATCH] docs(agent): clarify openclaw agent id vs name semantics (#2744) Follow-up to #2716. Updates two stale comments that still described openclaw's `name` and `id` as interchangeable. The actual contract: `id` is the routing key passed to `openclaw agent --agent `; `name` is a human display label and is not safe to pass to the CLI. No behavior change. Co-authored-by: multica-agent --- server/pkg/agent/models.go | 12 ++++++++---- server/pkg/agent/openclaw.go | 10 ++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/server/pkg/agent/models.go b/server/pkg/agent/models.go index bba0701fc..e47168e67 100644 --- a/server/pkg/agent/models.go +++ b/server/pkg/agent/models.go @@ -830,10 +830,14 @@ func discoverOpenclawAgents(ctx context.Context, executablePath string) ([]Model } // openclawAgentEntry is the shape parseOpenclawAgentsJSON expects -// from `openclaw agents list --json`. Both `name` and `id` are -// accepted as the identifier (different openclaw versions ship -// different field names); `model` is optional and only used to -// enrich the dropdown label. +// from `openclaw agents list --json`. `id` is the routing key +// passed to `openclaw agent --agent `; `name` is the human +// display label set via `openclaw agents set-identity --name` and +// is only used to enrich the dropdown label. The two are not +// interchangeable — see openclawEntriesToModels for the mapping. +// Older openclaw versions may emit only `name`; in that case we +// fall back to using it as the id for backward compatibility. +// `model` is optional and only used to enrich the dropdown label. type openclawAgentEntry struct { Name string `json:"name"` ID string `json:"id"` diff --git a/server/pkg/agent/openclaw.go b/server/pkg/agent/openclaw.go index b489681f2..7b341d1f9 100644 --- a/server/pkg/agent/openclaw.go +++ b/server/pkg/agent/openclaw.go @@ -178,10 +178,12 @@ func buildOpenclawArgs(prompt, sessionID string, opts ExecOptions, logger *slog. } // OpenClaw binds models to pre-registered agents at `openclaw agents // add/update --model` time; the daemon selects one at runtime by - // passing --agent . The model dropdown populates its list from - // `openclaw agents list`, so opts.Model here is an agent name. Only - // inject when the user hasn't already set --agent via custom_args — - // custom_args wins for backward compatibility with existing configs. + // passing --agent . The model dropdown populates its list from + // `openclaw agents list`, so opts.Model here is an agent id (see + // openclawEntriesToModels — the agent's display name lives in the + // dropdown label, not in opts.Model). Only inject when the user + // hasn't already set --agent via custom_args — custom_args wins for + // backward compatibility with existing configs. customArgs := filterCustomArgs(opts.CustomArgs, openclawBlockedArgs, logger) if opts.Model != "" && !customArgsContains(customArgs, "--agent") { args = append(args, "--agent", opts.Model)