The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(claude): default unset models to Opus 5 (#13055)
Dotta5128b4f32307
diff --git a/docs/adapters/claude-local.md b/docs/adapters/claude-local.mdindex e158877a66..d18ff1c7a9 100644--- a/docs/adapters/claude-local.md+++ b/docs/adapters/claude-local.md@@ -17,7 +17,7 @@ The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports| Field | Type | Required | Description ||-------|------|----------|-------------|| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |-| `model` | string | No | Claude model to use (e.g. `claude-opus-4-6`) |+| `model` | string | No | Claude model to use (default: `claude-opus-5`) || `promptTemplate` | string | No | Prompt used for all runs || `env` | object | No | Environment variables (supports secret refs) || `timeoutSec` | number | No | Process timeout (0 = no timeout) |@@ -25,6 +25,23 @@ The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports| `maxTurnsPerRun` | number | No | Max agentic turns per heartbeat (defaults to `300`) || `dangerouslySkipPermissions` | boolean | No | Skip permission prompts (default: `true`); required for headless runs where interactive approval is impossible |+## Default model++An omitted, empty, or whitespace-only `model` uses Claude Opus 5+(`claude-opus-5`) on both the CLI and ACP engines. This also applies to existing+agents with an unset model, including agents created through the API and agents+running in sandboxes. No database migration is needed. The editor shows the+Paperclip default and leaves the setting unset until you select a model.++An explicit `model` takes precedence over `ANTHROPIC_MODEL`. When only+`ANTHROPIC_MODEL` is configured, the adapter keeps that override. Bedrock and+Vertex configurations without an explicit model keep their provider-specific+default because those providers use different model IDs. Host environment+settings apply only to local targets when resolving the model.++The default does not change explicitly configured agent models or the separate+Paperclip Runner's qualified provider profiles.+## Prompt TemplatesTemplates support `{{variable}}` substitution:diff --git a/packages/adapters/claude-local/src/index.test.ts b/packages/adapters/claude-local/src/index.test.tsnew file mode 100644index 0000000000..8add6054b5--- /dev/null+++ b/packages/adapters/claude-local/src/index.test.ts@@ -0,0 +1,25 @@+import { describe, expect, it } from "vitest";+import { DEFAULT_CLAUDE_LOCAL_MODEL, resolveClaudeModel } from "./index.js";++describe("Claude model defaults", () => {+ it.each([undefined, null, "", " "])("uses Opus 5 for an unset model (%j)", (model) => {+ expect(DEFAULT_CLAUDE_LOCAL_MODEL).toBe("claude-opus-5");+ expect(resolveClaudeModel(model)).toBe("claude-opus-5");+ });++ it("keeps explicit model IDs ahead of environment overrides", () => {+ expect(resolveClaudeModel(" claude-sonnet-4-5 ", { ANTHROPIC_MODEL: "opus" }))+ .toBe("claude-sonnet-4-5");+ expect(resolveClaudeModel("", { ANTHROPIC_MODEL: " custom-model " })).toBe("custom-model");+ });++ it.each([+ { CLAUDE_CODE_USE_BEDROCK: "1" },+ { CLAUDE_CODE_USE_BEDROCK: "true" },+ { ANTHROPIC_BEDROCK_BASE_URL: "https://bedrock.example" },+ { CLAUDE_CODE_USE_VERTEX: "1" },+ ])("keeps provider-specific defaults for %j", (env) => {+ expect(resolveClaudeModel(undefined, env)).toBe("");+ expect(resolveClaudeModel("provider-model", env)).toBe("provider-model");+ });+});diff --git a/packages/adapters/claude-local/src/index.ts b/packages/adapters/claude-local/src/index.tsindex 703a69eef1..1af3540bde 100644--- a/packages/adapters/claude-local/src/index.ts+++ b/packages/adapters/claude-local/src/index.ts@@ -1,3 +1,26 @@+export const DEFAULT_CLAUDE_LOCAL_MODEL = "claude-opus-5";++/** Resolve Paperclip's default without replacing an explicit provider model. */+export function resolveClaudeModel(+ model: unknown,+ env: Record<string, unknown> = {},+): string {+ const configured = typeof model === "string" ? model.trim() : "";+ if (configured) return configured;+ const environmentModel = typeof env.ANTHROPIC_MODEL === "string" ? env.ANTHROPIC_MODEL.trim() : "";+ if (environmentModel) return environmentModel;+ // These providers use their own model IDs and region-specific defaults.+ const providerFlag = (value: unknown) => value === "1" || value === "true";+ if (+ providerFlag(env.CLAUDE_CODE_USE_BEDROCK)+ || providerFlag(env.CLAUDE_CODE_USE_VERTEX)+ || (typeof env.ANTHROPIC_BEDROCK_BASE_URL === "string" && env.ANTHROPIC_BEDROCK_BASE_URL.trim())+ ) {+ return "";+ }+ return DEFAULT_CLAUDE_LOCAL_MODEL;+}+export const type = "claude_local";export const label = "Claude Code";@@ -25,7 +48,7 @@ Core fields:- engine (string, optional): execution engine. Leave unset/auto to use ACP when prerequisites pass and fall back to the Claude Code CLI with diagnostics. Use "cli" to pin the CLI lane or "acp" to require ACP.- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)- instructionsFilePath (string, optional): absolute path to a markdown instructions file injected at runtime-- model (string, optional): Claude model id+- model (string, optional): Claude model id. Missing or blank defaults to ${DEFAULT_CLAUDE_LOCAL_MODEL} in both CLI and ACP, including existing agents. Explicit model IDs and ANTHROPIC_MODEL overrides are preserved. Bedrock/Vertex without an explicit model retain their provider default.- effort (string, optional): reasoning effort passed via --effort (low|medium|high)- chrome (boolean, optional): pass --chrome when running Claude- promptTemplate (string, optional): run prompt templatediff --git a/packages/adapters/claude-local/src/server/acp.test.ts b/packages/adapters/claude-local/src/server/acp.test.tsindex 3ec97c6813..d5c4aacb09 100644--- a/packages/adapters/claude-local/src/server/acp.test.ts+++ b/packages/adapters/claude-local/src/server/acp.test.ts@@ -237,6 +237,28 @@ function buildContext(root: string, overrides: Partial<AdapterExecutionContext>}describe("claude_local ACP lane", () => {+ it("uses the same default model in ACP startup and session identity", async () => {+ const root = await makeTempRoot("paperclip-claude-acp-default-");+ const meta: AdapterInvocationMeta[] = [];+ const execute = createClaudeAcpExecutor({+ createRuntime: (options: FakeRuntimeOptions) => new FakeRuntime(options) as never,+ });+ const result = await execute(buildContext(root, {+ onMeta: async (payload) => { meta.push(payload); },+ }));+ expect(result.exitCode).toBe(0);+ expect(meta[0]?.env?.ANTHROPIC_MODEL).toBe("claude-opus-5");+ });++ it("keeps ACP model precedence consistent with CLI and provider overrides", () => {+ expect(buildClaudeAcpConfig({ model: "claude-sonnet-4-5", env: { ANTHROPIC_MODEL: "opus" } }))+ .toMatchObject({ model: "claude-sonnet-4-5", env: { ANTHROPIC_MODEL: "claude-sonnet-4-5" } });+ expect(buildClaudeAcpConfig({}, { ANTHROPIC_MODEL: "custom-model" }))+ .toMatchObject({ model: "custom-model", env: { ANTHROPIC_MODEL: "custom-model" } });+ expect(buildClaudeAcpConfig({}, { CLAUDE_CODE_USE_BEDROCK: "1" }).model).toBe("");+ expect(buildClaudeAcpConfig({ env: { CLAUDE_CODE_USE_VERTEX: "1" } }).model).toBe("");+ });+it("maps Claude config to the ACPX Claude target", () => {expect(buildClaudeAcpConfig({engine: "acp",diff --git a/packages/adapters/claude-local/src/server/acp.ts b/packages/adapters/claude-local/src/server/acp.tsindex 019e06baa6..d26c48d7e4 100644--- a/packages/adapters/claude-local/src/server/acp.ts+++ b/packages/adapters/claude-local/src/server/acp.ts@@ -53,7 +53,7 @@ import { buildLocalAdapterTestProbeEnv } from "./probe-env.js";import { detectClaudeLoginRequired, parseClaudeStreamJson } from "./parse.js";import { buildClaudeProbePermissionArgs } from "./permissions.js";import { ADAPTER_AUTH_MISSING_CHECK_CODE } from "./auth-check.js";-import { SANDBOX_INSTALL_COMMAND } from "../index.js";+import { resolveClaudeModel, SANDBOX_INSTALL_COMMAND } from "../index.js";const moduleDir = path.dirname(fileURLToPath(import.meta.url));const packageRootDir = path.resolve(moduleDir, "../..");@@ -127,7 +127,12 @@ function firstNonEmptyString(...values: unknown[]): string | undefined {return undefined;}-export function buildClaudeAcpConfig(config: Record<string, unknown>): Record<string, unknown> {+export function buildClaudeAcpConfig(+ config: Record<string, unknown>,+ inheritedEnv: Record<string, unknown> = {},+): Record<string, unknown> {+ const env = parseObject(config.env);+ const model = resolveClaudeModel(config.model, { ...inheritedEnv, ...env });const agentCommand = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);const stateDir = firstNonEmptyString(config.stateDir, config.acpStateDir);const mode = firstNonEmptyString(config.mode, config.acpMode) ?? DEFAULT_ACP_ENGINE_MODE;@@ -144,6 +149,9 @@ export function buildClaudeAcpConfig(config: Record<string, unknown>): Record<streturn {...config,+ model,+ // ACP reads ANTHROPIC_MODEL at startup; keep it aligned with CLI precedence.+ ...(model ? { env: { ...env, ANTHROPIC_MODEL: model } } : {}),agent: "claude",mode,permissionMode,@@ -349,9 +357,13 @@ export function createClaudeAcpExecutor(options: ClaudeAcpExecutorOptions = {}):currentExecutor = createAcpxEngineExecutor(withClaudeAcpDefaults(options));executor = currentExecutor;}+ const target = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });const result = await currentExecutor({...ctx,- config: buildClaudeAcpConfig(ctx.config),+ config: buildClaudeAcpConfig(ctx.config, target?.kind === "remote" ? {} : process.env),});return mapClaudeAcpAuthErrorCode(result);};diff --git a/packages/adapters/claude-local/src/server/execute.remote.test.ts b/packages/adapters/claude-local/src/server/execute.remote.test.tsindex ec2eb60f5b..5291aae67b 100644--- a/packages/adapters/claude-local/src/server/execute.remote.test.ts+++ b/packages/adapters/claude-local/src/server/execute.remote.test.ts@@ -85,6 +85,7 @@ describe("claude remote execution", () => {afterEach(async () => {vi.clearAllMocks();+ vi.unstubAllEnvs();resetClaudeCliCapabilitiesCacheForTests();while (cleanupDirs.length > 0) {const dir = cleanupDirs.pop();@@ -94,6 +95,8 @@ describe("claude remote execution", () => {});it("prepares the workspace, syncs Claude runtime assets, and restores workspace changes for remote SSH execution", async () => {+ vi.stubEnv("CLAUDE_CODE_USE_BEDROCK", "1");+ vi.stubEnv("ANTHROPIC_MODEL", "host-only-model");const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-"));cleanupDirs.push(rootDir);const workspaceDir = path.join(rootDir, "workspace");@@ -188,6 +191,7 @@ describe("claude remote execution", () => {const call = runChildProcess.mock.calls[0] as unknown as| [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]| undefined;+ expect(call?.[2]).toEqual(expect.arrayContaining(["--model", "claude-opus-5"]));expect(call?.[2]).toContain("--allowedTools");expect(call?.[2]).toContain("Task AskUserQuestion Bash CronCreate CronDelete CronList Edit EnterPlanMode EnterWorktree ExitPlanMode ExitWorktree Glob Grep Monitor NotebookEdit PushNotification Read RemoteTrigger ScheduleWakeup Skill TaskOutput TaskStop TodoWrite ToolSearch WebFetch WebSearch Write",diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.tsindex 0f24419c9f..e875157464 100644--- a/packages/adapters/claude-local/src/server/execute.ts+++ b/packages/adapters/claude-local/src/server/execute.ts@@ -92,7 +92,7 @@ import { resolveClaudeDesiredSkillNames } from "./skills.js";import { isBedrockModelId } from "./models.js";import { prepareClaudePromptBundle } from "./prompt-cache.js";import { buildClaudeExecutionPermissionArgs } from "./permissions.js";-import { SANDBOX_INSTALL_COMMAND } from "../index.js";+import { resolveClaudeModel, SANDBOX_INSTALL_COMMAND } from "../index.js";import {createClaudeAcpExecutor,formatClaudeAcpFallbackMessage,@@ -431,7 +431,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconfig.promptTemplate,DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,);- const model = asString(config.model, "");const effort = asString(config.effort, "");const chrome = asBoolean(config.chrome, false);const maxTurns = asNumber(config.maxTurnsPerRun, 0);@@ -490,6 +489,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec(entry): entry is [string, string] => typeof entry[1] === "string",),);+ const modelEnv = executionTargetIsRemote ? env : effectiveEnv;+ const model = resolveClaudeModel(config.model, modelEnv);const billingType = resolveClaudeBillingType(effectiveEnv);const claudeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);const desiredSkillNames = new Set(resolveClaudeDesiredSkillNames(config, claudeSkillEntries));@@ -870,7 +871,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecheartbeatPromptChars: renderedPrompt.length,};const passesConfiguredModel = Boolean(- model && (!isBedrockAuth(effectiveEnv) || isBedrockModelId(model)),+ model && (!isBedrockAuth(modelEnv) || isBedrockModelId(model)),);const buildClaudeArgs = (diff --git a/packages/adapters/claude-local/src/server/test.ts b/packages/adapters/claude-local/src/server/test.tsindex 7d98e2ff2a..8cada6dfb5 100644--- a/packages/adapters/claude-local/src/server/test.ts+++ b/packages/adapters/claude-local/src/server/test.ts@@ -34,7 +34,7 @@ import {import { isBedrockModelId } from "./models.js";import { buildClaudeProbePermissionArgs } from "./permissions.js";import { prepareSandboxClaudeProbeRuntime } from "./claude-config.js";-import { SANDBOX_INSTALL_COMMAND } from "../index.js";+import { resolveClaudeModel, SANDBOX_INSTALL_COMMAND } from "../index.js";import { resolveClaudeExecutionEngineForRun, testClaudeAcpEnvironment } from "./acp.js";import { ADAPTER_AUTH_MISSING_CHECK_CODE } from "./auth-check.js";import {@@ -239,7 +239,7 @@ export async function testEnvironment(check.code !== "claude_managed_config_dir_failed",);let configuredModelIsCompatible = true;- const configuredModel = asString(config.model, "").trim();+ const configuredModel = resolveClaudeModel(config.model, considerHostEnv ? { ...process.env, ...env } : env);const minimumCliVersion =claudeCommandLooksLike(command, "claude") &&(!hasBedrock || isBedrockModelId(configuredModel))diff --git a/server/src/__tests__/claude-local-execute.test.ts b/server/src/__tests__/claude-local-execute.test.tsindex 4280ef17a5..4014fd4ad5 100644--- a/server/src/__tests__/claude-local-execute.test.ts+++ b/server/src/__tests__/claude-local-execute.test.ts@@ -350,6 +350,34 @@ function createLocalSandboxRunner() {}describe("claude execute", () => {+ it.each([+ [undefined, "claude-opus-5"],+ ["", "claude-opus-5"],+ [" ", "claude-opus-5"],+ ["claude-sonnet-4-5", "claude-sonnet-4-5"],+ ])("passes the resolved model to the CLI for %j", async (model, expected) => {+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-default-"));+ const { workspace, commandPath, capturePath, restore } = await setupExecuteEnv(root);+ try {+ const result = await execute({+ runId: "run-default",+ agent: { id: "agent-1", companyId: "co-1", name: "Test", adapterType: "claude_local", adapterConfig: {} },+ runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },+ config: {+ engine: "cli", model, command: commandPath, cwd: workspace,+ env: { PAPERCLIP_TEST_CAPTURE_PATH: capturePath },+ },+ context: {}, onLog: async () => {},+ });+ expect(result.exitCode).toBe(0);+ const { argv } = JSON.parse(await fs.readFile(capturePath, "utf8"));+ expect(argv[argv.indexOf("--model") + 1]).toBe(expected);+ } finally {+ restore();+ await fs.rm(root, { recursive: true, force: true });+ }+ });+it("uses a strict per-agent MCP config only when managed servers are present", async () => {const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-mcp-config-"));const { workspace, commandPath, capturePath, restore } = await setupExecuteEnv(root);diff --git a/ui/src/components/AgentConfigForm.render.test.tsx b/ui/src/components/AgentConfigForm.render.test.tsxindex bdc8f27ca9..2d7190c56b 100644--- a/ui/src/components/AgentConfigForm.render.test.tsx+++ b/ui/src/components/AgentConfigForm.render.test.tsx@@ -872,6 +872,17 @@ describe("AgentConfigForm environment selector", () => {});});+ it("names the Claude default for new and existing agents without pinning it", async () => {+ const environments = [makeEnvironment({ id: "local-1", name: "Local", driver: "local" })];+ const existing = await renderForm(environments, { adapterType: "claude_local", adapterConfig: {} });+ roots.push(existing.root);+ const created = await renderCreateForm(environments, { adapterType: "claude_local", model: "" });+ roots.push(created.root);+ expect(existing.container.textContent).toContain("Default (claude-opus-5)");+ expect(created.container.textContent).toContain("Default (claude-opus-5)");+ expect(existing.onSave).not.toHaveBeenCalled();+ });+it("keeps secret access out of the main Configuration content", async () => {const result = await renderForm([makeEnvironment({ id: "local-1", name: "Local", driver: "local" }),diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsxindex 2ee76300c6..921e6c98d2 100644--- a/ui/src/components/AgentConfigForm.tsx+++ b/ui/src/components/AgentConfigForm.tsx@@ -24,6 +24,7 @@ import {DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX,DEFAULT_CODEX_LOCAL_MODEL,} from "@paperclipai/adapter-codex-local";+import { DEFAULT_CLAUDE_LOCAL_MODEL } from "@paperclipai/adapter-claude-local";import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";import { DEFAULT_KIMI_LOCAL_MODEL } from "@paperclipai/adapter-kimi-local";@@ -1662,6 +1663,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {}}open={modelOpen}onOpenChange={setModelOpen}+ defaultLabel={adapterType === "claude_local" ? `Default (${DEFAULT_CLAUDE_LOCAL_MODEL})` : undefined}allowDefault={adapterType !== "opencode_local" && adapterType !== "pi_local"}required={adapterType === "opencode_local" || adapterType === "pi_local"}groupByProvider={adapterType === "opencode_local" || adapterType === "pi_local"}