vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-30 18:43:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document cli agent helpers

Browse Source
This commit is contained in:
Peter Steinberger
2026-06-04 09:02:44 -04:00
parent 258373717a
commit 34f7d78449
4 changed files with 43 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/agents/cli-auth-epoch.ts
View File

@@ -1,3 +1,7 @@
/**
* Builds auth-state epochs for CLI-backed runtimes so reusable sessions reset
* when the owning local credential identity changes.
*/
import crypto from "node:crypto";
import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
import { loadAuthProfileStoreForRuntime } from "./auth-profiles/store.js";
@@ -27,12 +31,15 @@ const defaultCliAuthEpochDeps: CliAuthEpochDeps = {
const cliAuthEpochDeps: CliAuthEpochDeps = { ...defaultCliAuthEpochDeps };
/** Version salt for CLI auth epoch encoding semantics. */
export const CLI_AUTH_EPOCH_VERSION = 5;
/** Overrides credential readers for auth-epoch unit tests. */
export function setCliAuthEpochTestDeps(overrides: Partial<CliAuthEpochDeps>): void {
Object.assign(cliAuthEpochDeps, overrides);
}
/** Restores default credential readers after auth-epoch unit tests. */
export function resetCliAuthEpochTestDeps(): void {
Object.assign(cliAuthEpochDeps, defaultCliAuthEpochDeps);
}
@@ -198,6 +205,7 @@ function getAuthProfileCredential(
return store.profiles[authProfileId];
}
/** Resolves the stable auth epoch hash for a CLI runtime/provider session. */
export async function resolveCliAuthEpoch(params: {
provider: string;
authProfileId?: string;

13
src/agents/cli-backends.ts
View File

@@ -1,3 +1,6 @@
/**
* Resolves CLI runtime backends registered by plugins or setup metadata.
*/
import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
@@ -34,6 +37,7 @@ const defaultCliBackendsDeps: CliBackendsDeps = {
let cliBackendsDeps: CliBackendsDeps = defaultCliBackendsDeps;
/** Fully merged CLI backend definition used by agent runner execution. */
export type ResolvedCliBackend = {
id: string;
modelProvider?: string;
@@ -60,6 +64,7 @@ type ResolvedCliBackendLiveTest = {
dockerBinaryName?: string;
};
/** Binding between a model provider and the CLI runtime that serves it. */
export type CliRuntimeModelBackendBinding = {
provider: string;
runtime: string;
@@ -184,6 +189,7 @@ function addCliRuntimeModelBinding(
});
}
/** Lists model-provider to CLI-runtime bindings from runtime and optional setup registries. */
export function listCliRuntimeModelBackendBindings(
params: {
config?: OpenClawConfig;
@@ -216,6 +222,7 @@ export function listCliRuntimeModelBackendBindings(
);
}
/** Lists CLI runtime ids that alias canonical model providers. */
export function listCliRuntimeProviderIds(
params: {
config?: OpenClawConfig;
@@ -235,6 +242,7 @@ export function listCliRuntimeProviderIds(
].toSorted();
}
/** Resolves the canonical model provider served by a CLI runtime id. */
export function resolveCliRuntimeCanonicalProvider(params: {
runtime: string | undefined;
config?: OpenClawConfig;
@@ -262,6 +270,7 @@ export function resolveCliRuntimeCanonicalProvider(params: {
return setupBackend ? resolveCliBackendModelProvider(setupBackend.backend) : undefined;
}
/** Resolves the binding for one provider/runtime pair when registered. */
export function resolveCliRuntimeModelBackendBinding(params: {
provider: string | undefined;
runtime: string | undefined;
@@ -301,6 +310,7 @@ export function resolveCliRuntimeModelBackendBinding(params: {
: undefined;
}
/** Checks whether a runtime is registered to serve a model provider. */
export function isCliRuntimeModelBackendForProvider(params: {
provider: string | undefined;
runtime: string | undefined;
@@ -353,6 +363,7 @@ function mergeBackendConfig(base: CliBackendConfig, override?: CliBackendConfig)
};
}
/** Resolves live-test defaults advertised by a CLI backend plugin. */
export function resolveCliBackendLiveTest(provider: string): ResolvedCliBackendLiveTest | null {
const normalized = normalizeBackendKey(provider);
const entry =
@@ -373,6 +384,7 @@ export function resolveCliBackendLiveTest(provider: string): ResolvedCliBackendL
};
}
/** Resolves the executable CLI backend config after plugin defaults and user overrides. */
export function resolveCliBackendConfig(
provider: string,
cfg?: OpenClawConfig,
@@ -484,6 +496,7 @@ export function resolveCliBackendConfig(
};
}
/** Test-only dependency controls for CLI backend registry resolution. */
export const testing = {
resetDepsForTest(): void {
cliBackendsDeps = defaultCliBackendsDeps;

17
src/agents/cli-credentials.ts
View File

@@ -1,3 +1,7 @@
/**
* Reads and refreshes credentials stored by external CLI runtimes such as
* Claude Code, Codex, Gemini, and MiniMax.
*/
import { execFileSync, execSync } from "node:child_process";
import { createHash } from "node:crypto";
import fs from "node:fs";
@@ -36,6 +40,7 @@ let codexCliCache: CachedValue<CodexCliCredential> | null = null;
let minimaxCliCache: CachedValue<MiniMaxCliCredential> | null = null;
let geminiCliCache: CachedValue<GeminiCliCredential> | null = null;
/** Clears in-memory CLI credential caches for isolated tests. */
export function resetCliCredentialCachesForTest(): void {
claudeCliCache = null;
codexCliCache = null;
@@ -43,6 +48,7 @@ export function resetCliCredentialCachesForTest(): void {
geminiCliCache = null;
}
/** Credential shape parsed from Claude Code CLI storage. */
export type ClaudeCliCredential =
| {
type: "oauth";
@@ -58,6 +64,7 @@ export type ClaudeCliCredential =
expires: number;
};
/** Credential shape parsed from Codex CLI storage. */
export type CodexCliCredential = {
type: "oauth";
provider: OAuthProvider;
@@ -68,6 +75,7 @@ export type CodexCliCredential = {
idToken?: string;
};
/** Credential shape parsed from MiniMax portal CLI storage. */
export type MiniMaxCliCredential = {
type: "oauth";
provider: "minimax-portal";
@@ -76,6 +84,7 @@ export type MiniMaxCliCredential = {
expires: number;
};
/** Credential shape parsed from Gemini CLI storage. */
export type GeminiCliCredential = {
type: "oauth";
provider: "google-gemini-cli";
@@ -437,6 +446,7 @@ function readClaudeCliKeychainCredentials(
}
}
/** Reads Claude CLI credentials from macOS Keychain or the CLI credential file. */
export function readClaudeCliCredentials(options?: {
allowKeychainPrompt?: boolean;
platform?: NodeJS.Platform;
@@ -494,6 +504,7 @@ export function readClaudeCliCredentialsCached(options?: {
});
}
/** Writes refreshed Claude OAuth tokens back to the Claude CLI macOS Keychain item. */
export function writeClaudeCliKeychainCredentials(
newCredentials: OAuthCredentials,
options?: { execFileSync?: ExecFileSyncFn },
@@ -550,6 +561,7 @@ export function writeClaudeCliKeychainCredentials(
}
}
/** Writes refreshed Claude OAuth tokens back to the Claude CLI credential file. */
export function writeClaudeCliFileCredentials(
newCredentials: OAuthCredentials,
options?: ClaudeCliFileOptions,
@@ -592,6 +604,7 @@ export function writeClaudeCliFileCredentials(
}
}
/** Writes refreshed Claude OAuth tokens to the preferred Claude CLI credential store. */
export function writeClaudeCliCredentials(
newCredentials: OAuthCredentials,
options?: ClaudeCliWriteOptions,
@@ -612,6 +625,7 @@ export function writeClaudeCliCredentials(
return writeFile(newCredentials, { homeDir: options?.homeDir });
}
/** Reads Codex CLI OAuth credentials from Keychain or CODEX_HOME auth.json. */
export function readCodexCliCredentials(options?: {
codexHome?: string;
allowKeychainPrompt?: boolean;
@@ -673,6 +687,7 @@ export function readCodexCliCredentials(options?: {
};
}
/** Reads Codex CLI credentials with optional short-lived cache and file fingerprinting. */
export function readCodexCliCredentialsCached(options?: {
codexHome?: string;
allowKeychainPrompt?: boolean;
@@ -703,6 +718,7 @@ export function readCodexCliCredentialsCached(options?: {
});
}
/** Reads MiniMax CLI credentials with optional short-lived cache. */
export function readMiniMaxCliCredentialsCached(options?: {
ttlMs?: number;
homeDir?: string;
@@ -720,6 +736,7 @@ export function readMiniMaxCliCredentialsCached(options?: {
});
}
/** Reads Gemini CLI credentials with optional short-lived cache. */
export function readGeminiCliCredentialsCached(options?: {
ttlMs?: number;
homeDir?: string;

5
src/agents/cli-output.ts
View File

@@ -316,6 +316,7 @@ function shouldUnwrapNestedCliResultText(params: {
}
/** Parses JSON CLI output, including mixed stdout that contains embedded JSON objects. */
/** Parses a single JSON payload emitted by a CLI backend. */
export function parseCliJson(
raw: string,
backend: CliBackendConfig,
@@ -624,6 +625,7 @@ function dispatchClaudeCliStreamingToolEvent(params: {
}
/** Creates an incremental JSONL parser for CLI streaming responses and tool events. */
/** Creates a stateful parser for streaming JSONL CLI backend output. */
export function createCliJsonlStreamingParser(params: {
backend: CliBackendConfig;
providerId: string;
@@ -751,6 +753,7 @@ export function createCliJsonlStreamingParser(params: {
}
/** Parses complete JSONL CLI output into the final assistant result and metadata. */
/** Parses complete JSONL output from a CLI backend into normalized text and metadata. */
export function parseCliJsonl(
raw: string,
backend: CliBackendConfig,
@@ -803,6 +806,7 @@ export function parseCliJsonl(
}
/** Parses CLI output according to the backend output mode with text fallback. */
/** Parses CLI backend output using the configured JSON/JSONL/plain-text mode. */
export function parseCliOutput(params: {
raw: string;
backend: CliBackendConfig;
@@ -831,6 +835,7 @@ export function parseCliOutput(params: {
}
/** Extracts the most specific structured CLI error message from mixed or JSON output. */
/** Extracts a human-readable error message from mixed CLI stderr/stdout text. */
export function extractCliErrorMessage(raw: string): string | null {
const parsedRecords = parseJsonRecordCandidates(raw);
if (parsedRecords.length === 0) {