Skip to content

Commit d89ad16

Browse files
steipetesteipete
committed
docs: document anthropic cli config helpers
1 parent c466104 commit d89ad16

11 files changed

Lines changed: 71 additions & 0 deletions

‎extensions/anthropic/api.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Public Anthropic provider API barrel. It exposes provider construction,
3+
* Claude CLI helpers, and stream wrappers for config/runtime consumers.
4+
*/
15
export { CLAUDE_CLI_BACKEND_ID, isClaudeCliProvider } from "./cli-shared.js";
26
export { buildAnthropicProvider } from "./register.runtime.js";
37
export {

‎extensions/anthropic/claude-model-refs.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Claude CLI model-ref normalization. It maps family aliases and retired model
3+
* ids to current Anthropic runtime refs while preserving auth-profile suffixes.
4+
*/
15
import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
26
import { CLAUDE_CLI_BACKEND_ID, CLAUDE_CLI_MODEL_ALIASES } from "./cli-constants.js";
37

@@ -7,6 +11,7 @@ const DEFAULT_CLAUDE_MODEL_BY_FAMILY: Record<string, string> = {
711
haiku: "claude-haiku-4-5",
812
};
913

14+
/** Normalized Claude CLI selection plus runtime refs used by setup migrations. */
1015
export type ClaudeCliAnthropicModelRefs = {
1116
selectedRef: string;
1217
runtimeRefs: string[];
@@ -182,6 +187,7 @@ function upgradeOldClaudeModelId(normalized: string): string | null {
182187
return null;
183188
}
184189

190+
/** Resolve a Claude CLI model ref into selected and Anthropic-compatible runtime refs. */
185191
export function resolveClaudeCliAnthropicModelRefs(
186192
raw: string,
187193
): ClaudeCliAnthropicModelRefs | null {
@@ -214,6 +220,7 @@ export function resolveClaudeCliAnthropicModelRefs(
214220
};
215221
}
216222

223+
/** Resolve a known Anthropic/Claude CLI model ref to its current Anthropic model ref. */
217224
export function resolveKnownAnthropicModelRef(raw?: string): string | null {
218225
if (!raw) {
219226
return null;

‎extensions/anthropic/cli-auth-seam.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
1+
/**
2+
* Claude CLI auth seam. Setup may prompt for keychain-backed credentials while
3+
* runtime paths stay non-interactive.
4+
*/
15
import { readClaudeCliCredentialsCached } from "openclaw/plugin-sdk/provider-auth";
26

7+
/** Read Claude CLI credentials for interactive setup paths. */
38
export function readClaudeCliCredentialsForSetup() {
49
return readClaudeCliCredentialsCached();
510
}
611

12+
/** Read Claude CLI credentials for setup checks that must not prompt. */
713
export function readClaudeCliCredentialsForSetupNonInteractive() {
814
return readClaudeCliCredentialsCached({ allowKeychainPrompt: false });
915
}
1016

17+
/** Read Claude CLI credentials for runtime without keychain prompts. */
1118
export function readClaudeCliCredentialsForRuntime() {
1219
return readClaudeCliCredentialsCached({ allowKeychainPrompt: false });
1320
}

‎extensions/anthropic/cli-backend.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Claude CLI backend descriptor. It configures Claude Code process arguments,
3+
* MCP bundling, session handling, environment scrubbing, and watchdog defaults.
4+
*/
15
import type { CliBackendPlugin } from "openclaw/plugin-sdk/cli-backend";
26
import {
37
CLI_FRESH_WATCHDOG_DEFAULTS,
@@ -13,6 +17,7 @@ import {
1317
resolveClaudeCliExecutionArgs,
1418
} from "./cli-shared.js";
1519

20+
/** Build the Claude CLI backend plugin descriptor. */
1621
export function buildAnthropicCliBackend(): CliBackendPlugin {
1722
return {
1823
id: CLAUDE_CLI_BACKEND_ID,

‎extensions/anthropic/cli-catalog.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Claude CLI model catalog entries. Subscription-backed CLI models use picker
3+
* metadata and do not require API-key auth rows.
4+
*/
15
import type { ModelCatalogEntry } from "openclaw/plugin-sdk/agent-runtime";
26
import { CLAUDE_CLI_BACKEND_ID, CLAUDE_CLI_DEFAULT_ALLOWLIST_REFS } from "./cli-constants.js";
37

@@ -39,6 +43,7 @@ function extractClaudeCliModelIds(): string[] {
3943
return ids;
4044
}
4145

46+
/** Build catalog entries for the default Claude CLI allowlist. */
4247
export function buildClaudeCliCatalogEntries(): ModelCatalogEntry[] {
4348
return extractClaudeCliModelIds().map((id) => {
4449
return {

‎extensions/anthropic/cli-constants.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,20 @@
1+
/**
2+
* Shared Claude CLI constants. These identify the synthetic backend, default
3+
* model refs, aliases, and session-id fields used across runtime and setup.
4+
*/
5+
/** Synthetic provider/backend id for Claude Code CLI-backed Anthropic models. */
16
export const CLAUDE_CLI_BACKEND_ID = "claude-cli";
7+
/** Default Claude CLI model ref for agent defaults and live tests. */
28
export const CLAUDE_CLI_DEFAULT_MODEL_REF = `${CLAUDE_CLI_BACKEND_ID}/claude-opus-4-8`;
9+
/** Default Claude CLI models allowed when setup seeds the model allowlist. */
310
export const CLAUDE_CLI_DEFAULT_ALLOWLIST_REFS = [
411
CLAUDE_CLI_DEFAULT_MODEL_REF,
512
`${CLAUDE_CLI_BACKEND_ID}/claude-opus-4-7`,
613
`${CLAUDE_CLI_BACKEND_ID}/claude-sonnet-4-6`,
714
`${CLAUDE_CLI_BACKEND_ID}/claude-opus-4-6`,
815
] as const;
916

17+
/** User-facing Claude CLI model aliases normalized before execution. */
1018
export const CLAUDE_CLI_MODEL_ALIASES: Record<string, string> = {
1119
opus: "opus",
1220
"opus-4.8": "claude-opus-4-8",
@@ -21,6 +29,7 @@ export const CLAUDE_CLI_MODEL_ALIASES: Record<string, string> = {
2129
haiku: "haiku",
2230
};
2331

32+
/** JSONL fields that may contain Claude CLI session ids. */
2433
export const CLAUDE_CLI_SESSION_ID_FIELDS = [
2534
"session_id",
2635
"sessionId",

‎extensions/anthropic/cli-migration.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Claude CLI setup migration helpers. They rewrite legacy Claude CLI model refs
3+
* to Anthropic refs while preserving runtime allowlist entries for CLI execution.
4+
*/
15
import {
26
CLAUDE_CLI_PROFILE_ID,
37
type OpenClawConfig,
@@ -168,6 +172,7 @@ function modelEntryWithClaudeCliRuntime(entry: unknown): Record<string, unknown>
168172
return base;
169173
}
170174

175+
/** Return whether Claude CLI credentials are available for setup migration. */
171176
export function hasClaudeCliAuth(options?: { allowKeychainPrompt?: boolean }): boolean {
172177
return Boolean(
173178
options?.allowKeychainPrompt === false
@@ -209,6 +214,7 @@ function buildClaudeCliAuthProfiles(
209214
];
210215
}
211216

217+
/** Build the config migration result for adopting Claude CLI-backed Anthropic defaults. */
212218
export function buildAnthropicCliMigrationResult(
213219
config: OpenClawConfig,
214220
credential?: ClaudeCliCredential | null,

‎extensions/anthropic/cli-shared.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Shared Claude CLI backend normalization. It sanitizes command args, maps
3+
* thinking levels, and keeps OpenClaw-managed CLI runs isolated from shell env.
4+
*/
15
import type {
26
CliBackendConfig,
37
CliBackendNormalizeConfigContext,
@@ -17,6 +21,7 @@ export {
1721
// consulting its local login state, so inherited shell overrides must not
1822
// steer OpenClaw-managed Claude CLI runs toward a different provider,
1923
// endpoint, token source, plugin/config tree, or telemetry bootstrap mode.
24+
/** Environment variables removed before launching OpenClaw-managed Claude CLI runs. */
2025
export const CLAUDE_CLI_CLEAR_ENV = [
2126
"ANTHROPIC_API_KEY",
2227
"ANTHROPIC_API_KEY_OLD",
@@ -67,6 +72,7 @@ const CLAUDE_BYPASS_PERMISSION_MODE = "bypassPermissions";
6772

6873
type ClaudeCliEffort = "low" | "medium" | "high" | "xhigh" | "max";
6974

75+
/** Return whether a provider id refers to the Claude CLI backend. */
7076
export function isClaudeCliProvider(providerId: string): boolean {
7177
return normalizeOptionalLowercaseString(providerId) === CLAUDE_CLI_BACKEND_ID;
7278
}
@@ -81,6 +87,7 @@ function isOpenClawRequestedYolo(context?: CliBackendNormalizeConfigContext): bo
8187
return security === "full" && ask === "off";
8288
}
8389

90+
/** Resolve Claude permission mode from OpenClaw exec security settings. */
8491
export function resolveClaudePermissionMode(context?: CliBackendNormalizeConfigContext): {
8592
mode?: string;
8693
overrideExisting: boolean;
@@ -90,6 +97,7 @@ export function resolveClaudePermissionMode(context?: CliBackendNormalizeConfigC
9097
: { overrideExisting: false };
9198
}
9299

100+
/** Normalize Claude permission arguments, removing legacy skip-permissions flags. */
93101
export function normalizeClaudePermissionArgs(
94102
args?: string[],
95103
options?: { mode?: string; overrideExisting?: boolean },
@@ -138,6 +146,7 @@ export function normalizeClaudePermissionArgs(
138146
return normalized;
139147
}
140148

149+
/** Ensure Claude CLI setting sources stay restricted to user settings. */
141150
export function normalizeClaudeSettingSourcesArgs(args?: string[]): string[] | undefined {
142151
if (!args) {
143152
return args;
@@ -172,6 +181,7 @@ export function normalizeClaudeSettingSourcesArgs(args?: string[]): string[] | u
172181
return normalized;
173182
}
174183

184+
/** Map OpenClaw thinking levels to Claude CLI effort flags for a model id. */
175185
export function mapClaudeCliThinkingLevelToEffort(
176186
thinkingLevel?: string | null,
177187
): ClaudeCliEffort | undefined {
@@ -216,6 +226,7 @@ function stripClaudeEffortArgs(args: readonly string[]): string[] {
216226
return normalized;
217227
}
218228

229+
/** Resolve final Claude CLI execution args for one backend invocation. */
219230
export function resolveClaudeCliExecutionArgs(
220231
context: CliBackendResolveExecutionArgsContext,
221232
): string[] {
@@ -226,6 +237,7 @@ export function resolveClaudeCliExecutionArgs(
226237
return [...stripClaudeEffortArgs(context.baseArgs), CLAUDE_EFFORT_ARG, effort];
227238
}
228239

240+
/** Normalize Claude CLI backend config before registration or execution. */
229241
export function normalizeClaudeBackendConfig(
230242
config: CliBackendConfig,
231243
context?: CliBackendNormalizeConfigContext,

‎extensions/anthropic/config-defaults.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Anthropic config defaulting helpers. They seed default Anthropic/Claude CLI
3+
* model refs and cache-retention params based on configured auth mode.
4+
*/
15
import type { OpenClawConfig } from "openclaw/plugin-sdk/plugin-entry";
26
import {
37
isRecord,
@@ -274,6 +278,7 @@ function normalizeAnthropicProviderConfig<T extends { api?: string; models?: unk
274278
return { ...providerConfig, api: ANTHROPIC_PROVIDER_API };
275279
}
276280

281+
/** Normalize Anthropic provider config defaults for one provider entry. */
277282
export function normalizeAnthropicProviderConfigForProvider<
278283
T extends { api?: string; models?: unknown[] },
279284
>(params: { provider: string; providerConfig: T }): T {
@@ -284,6 +289,7 @@ export function normalizeAnthropicProviderConfigForProvider<
284289
return normalizeAnthropicProviderConfig(params.providerConfig);
285290
}
286291

292+
/** Apply Anthropic and Claude CLI defaults to an OpenClaw config object. */
287293
export function applyAnthropicConfigDefaults(params: {
288294
config: OpenClawConfig;
289295
env: NodeJS.ProcessEnv;

‎extensions/anthropic/contract-api.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Contract API barrel for Anthropic stream wrapper helpers. Tests and contract
3+
* checks import this lightweight path instead of the full provider entry.
4+
*/
15
export {
26
createAnthropicBetaHeadersWrapper,
37
createAnthropicFastModeWrapper,

0 commit comments

Comments
 (0)