메인 콘텐츠로 건너뛰기

​
Plugin 런타임 헬퍼

등록 중 모든 plugin에 주입되는 api.runtime 객체에 대한 참조 문서입니다. 호스트 내부 구현을 직접 import하지 말고 이 헬퍼를 사용하세요.
단계별 설명이 필요하신가요? Channel Plugins 또는 Provider Plugins에서 이 헬퍼들이 실제로 어떻게 사용되는지 단계별로 확인할 수 있습니다.
register(api) {
  const runtime = api.runtime;
}

​
런타임 네임스페이스

​
api.runtime.agent

에이전트 ID, 디렉터리, 세션 관리. 
// 에이전트 작업 디렉터리 해석
const agentDir = api.runtime.agent.resolveAgentDir(cfg);

// 에이전트 워크스페이스 해석
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);

// 에이전트 ID 가져오기
const identity = api.runtime.agent.resolveAgentIdentity(cfg);

// 기본 thinking 수준 가져오기
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);

// 에이전트 타임아웃 가져오기
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);

// 워크스페이스 존재 보장
await api.runtime.agent.ensureAgentWorkspace(cfg);

// 임베디드 Pi 에이전트 실행
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedPiAgent({
  sessionId: "my-plugin:task-1",
  runId: crypto.randomUUID(),
  sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
  prompt: "최신 변경 사항을 요약해 줘",
  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});
세션 저장소 헬퍼는 api.runtime.agent.session 아래에 있습니다: 
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
const store = api.runtime.agent.session.loadSessionStore(cfg);
await api.runtime.agent.session.saveSessionStore(cfg, store);
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);

​
api.runtime.agent.defaults

기본 모델 및 provider 상수: 
const model = api.runtime.agent.defaults.model; // 예: "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // 예: "anthropic"

​
api.runtime.subagent

백그라운드 subagent 실행을 시작하고 관리합니다. 
// subagent 실행 시작
const { runId } = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "이 쿼리를 집중된 후속 검색으로 확장해 줘.",
  provider: "openai", // 선택적 재정의
  model: "gpt-4.1-mini", // 선택적 재정의
  deliver: false,
});

// 완료 대기
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// 세션 메시지 읽기
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// 세션 삭제
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});
모델 재정의(provider/model)는 config의 plugins.entries.<id>.subagent.allowModelOverride: true를 통한 운영자 opt-in이 필요합니다. 신뢰되지 않은 plugins도 subagent를 실행할 수는 있지만 재정의 요청은 거부됩니다.

​
api.runtime.taskFlow

기존 OpenClaw 세션 키 또는 신뢰된 도구 컨텍스트에 Task Flow 런타임을 바인딩한 다음, 매 호출마다 소유자를 전달하지 않고 Task Flow를 생성하고 관리합니다. 
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);

const created = taskFlow.createManaged({
  controllerId: "my-plugin/review-batch",
  goal: "새 pull request 검토",
});

const child = taskFlow.runTask({
  flowId: created.flowId,
  runtime: "acp",
  childSessionKey: "agent:main:subagent:reviewer",
  task: "PR #123 검토",
  status: "running",
  startedAt: Date.now(),
});

const waiting = taskFlow.setWaiting({
  flowId: created.flowId,
  expectedRevision: created.revision,
  currentStep: "await-human-reply",
  waitJson: { kind: "reply", channel: "telegram" },
});
자체 바인딩 계층에서 이미 신뢰된 OpenClaw 세션 키가 있는 경우 bindSession({ sessionKey, requesterOrigin })를 사용하세요. 원시 사용자 입력으로부터 바인딩하지 마세요.

​
api.runtime.tts

텍스트 음성 합성. 
// 표준 TTS
const clip = await api.runtime.tts.textToSpeech({
  text: "OpenClaw에서 안녕하세요",
  cfg: api.config,
});

// 전화 최적화 TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
  text: "OpenClaw에서 안녕하세요",
  cfg: api.config,
});

// 사용 가능한 음성 나열
const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});
코어 messages.tts 구성과 provider 선택을 사용합니다. PCM 오디오 버퍼 + 샘플 레이트를 반환합니다.

​
api.runtime.mediaUnderstanding

이미지, 오디오, 비디오 분석. 
// 이미지 설명
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

// 오디오 전사
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  mime: "audio/ogg", // 선택 사항, MIME을 추론할 수 없을 때
});

// 비디오 설명
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

// 일반 파일 분석
const result = await api.runtime.mediaUnderstanding.runFile({
  filePath: "/tmp/inbound-file.pdf",
  cfg: api.config,
});
출력이 생성되지 않은 경우(예: 입력 건너뜀) { text: undefined }를 반환합니다.
api.runtime.stt.transcribeAudioFile(...)는 호환성 별칭으로 계속 유지되며, api.runtime.mediaUnderstanding.transcribeAudioFile(...)의 별칭입니다.

​
api.runtime.imageGeneration

이미지 생성. 
const result = await api.runtime.imageGeneration.generate({
  prompt: "노을을 그리는 로봇",
  cfg: api.config,
});

const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

​
api.runtime.webSearch

웹 검색. 
const providers = api.runtime.webSearch.listProviders({ config: api.config });

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: { query: "OpenClaw plugin SDK", count: 5 },
});

​
api.runtime.media

저수준 media 유틸리티. 
const webMedia = await api.runtime.media.loadWebMedia(url);
const mime = await api.runtime.media.detectMime(buffer);
const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "image"
const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);
const metadata = await api.runtime.media.getImageMetadata(filePath);
const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });

​
api.runtime.config

Config 로드 및 기록. 
const cfg = await api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile(cfg);

​
api.runtime.system

시스템 수준 유틸리티. 
await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeatNow();
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);

​
api.runtime.events

이벤트 구독. 
api.runtime.events.onAgentEvent((event) => {
  /* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
  /* ... */
});

​
api.runtime.logging

로깅. 
const verbose = api.runtime.logging.shouldLogVerbose();
const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });

​
api.runtime.modelAuth

모델 및 provider 인증 해석. 
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
  provider: "openai",
  cfg,
});

​
api.runtime.state

상태 디렉터리 해석. 
const stateDir = api.runtime.state.resolveStateDir();

​
api.runtime.tools

메모리 도구 팩토리 및 CLI. 
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);

​
api.runtime.channel

채널 전용 런타임 헬퍼(채널 plugin이 로드된 경우 사용 가능).

​
런타임 참조 저장

register 콜백 외부에서 사용할 런타임 참조를 저장하려면 createPluginRuntimeStore를 사용하세요: 
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");

// 진입점에서
export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "예시",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});

// 다른 파일에서
export function getRuntime() {
  return store.getRuntime(); // 초기화되지 않았으면 throw
}

export function tryGetRuntime() {
  return store.tryGetRuntime(); // 초기화되지 않았으면 null 반환
}

​
기타 최상위 api 필드

api.runtime 외에도 API 객체는 다음을 제공합니다:
필드타입설명
api.idstringPlugin ID
api.namestringPlugin 표시 이름
api.configOpenClawConfig현재 config 스냅샷(사용 가능한 경우 활성 메모리 내 런타임 스냅샷)
api.pluginConfigRecord<string, unknown>plugins.entries.<id>.config의 plugin 전용 config
api.loggerPluginLogger범위 지정 로거(debug, info, warn, error)
api.registrationModePluginRegistrationMode현재 로드 모드, "setup-runtime"은 가벼운 사전 전체 진입점 시작/설정 구간
api.resolvePath(input)(string) => stringplugin 루트를 기준으로 경로 해석

​
관련