Live2D AI角色

Quick Start

This snippet runs entirely in the browser with no server — paste it in, drop in an OpenAI API key, and it works. It uses the direct browser clients (@charivo/llm/openai, @charivo/tts/openai), which are for local development and demos only. They expose your API key in the browser, so for production use the server-mediated path instead (see Choosing Packages).

pnpm add \
  @charivo/core \
  @charivo/llm \
  @charivo/tts \
  @charivo/render @charivo/render-live2d

import { createCharivo, isCharivoError } from "@charivo/core";
import { createLLMManager } from "@charivo/llm";
import { createOpenAILLMClient } from "@charivo/llm/openai";
import { createTTSManager } from "@charivo/tts";
import { createOpenAITTSPlayer } from "@charivo/tts/openai";
import { createRenderManager } from "@charivo/render";
import { createLive2DRenderer } from "@charivo/render-live2d";

// Dev/demo only: this key is shipped to the browser. Never do this in production.
const OPENAI_API_KEY = "sk-...";

const canvas = document.querySelector("canvas")!;

const renderManager = createRenderManager(createLive2DRenderer({ canvas }), {
  canvas,
  mouseTracking: "document",
});
await renderManager.initialize();
await renderManager.loadModel?.("/live2d/Hiyori/Hiyori.model3.json");

const charivo = createCharivo({
  renderer: renderManager,
  llm: createLLMManager(createOpenAILLMClient({ apiKey: OPENAI_API_KEY })),
  tts: createTTSManager(createOpenAITTSPlayer({ apiKey: OPENAI_API_KEY })),
  character: {
    id: "hiyori",
    name: "Hiyori",
    personality: "Cheerful and helpful assistant",
    voice: { voiceId: "marin" },
  },
});

try {
  await charivo.userSay("Hello");
} catch (error) {
  if (isCharivoError(error)) {
    console.error(error.code, error.message);
  }
  throw error;
}

await charivo.dispose();

For a complete app with the production server-mediated path, see examples/web.

Text chat can also drive the character's face and body: register the catalog-constrained tools from @charivo/avatar on the LLM manager and the model calls setExpression / playMotion / lookAt while it replies. See the LLM guide's avatar tool-calling walkthrough for the wiring.

Live demos

• Live2D web app — https://charivo.vercel.app/
• Companion (Realtime voice + cross-session memory) — https://charivo-companion.vercel.app/

Choosing Packages

Use the remote/server-mediated path by default:

• LLM: @charivo/llm/remote + a server route using a provider package such as @charivo/server/openai, @charivo/server/openclaw, or @charivo/server/gemini
• TTS: @charivo/tts/remote + @charivo/server/openai or @charivo/server/gemini
• STT: @charivo/stt/remote + @charivo/server/openai or @charivo/server/gemini
• Realtime: @charivo/realtime/remote + a server route using a provider package such as @charivo/server/openai or @charivo/server/gemini

Direct browser packages are for local development, demos, and testing only:

• @charivo/llm/openai
• @charivo/llm/openclaw
• @charivo/llm/gemini
• @charivo/realtime/openai-agents (dev apiKey mints the client secret in-browser)
• @charivo/realtime/gemini (dev apiKey mints the ephemeral token in-browser)
• @charivo/tts/openai
• @charivo/tts/gemini
• @charivo/stt/openai
• @charivo/stt/gemini

@charivo/realtime/openai is server-mediated despite being a direct transport — it accepts only apiEndpoint or sessionBootstrap and never takes a key.

The dev/testing-only classification above applies to the browser client, player, or transcriber factory on each of these seven subpaths (createOpenAILLMClient, createOpenClawLLMClient, createGeminiLLMClient, createOpenAITTSPlayer, createGeminiTTSPlayer, createOpenAISTTTranscriber, createGeminiSTTTranscriber). The same subpaths also export the server-side provider (createOpenAILLMProvider, createOpenClawLLMProvider, createGeminiLLMProvider, createOpenAITTSProvider, createGeminiTTSProvider, createOpenAISTTProvider, createGeminiSTTProvider), which refuses to run in a browser unless you pass dangerouslyAllowBrowser: true.

Browser-native packages are useful when you explicitly want no server dependency:

• @charivo/tts/web
• @charivo/stt/web

Package Map

Core:

• @charivo/core: orchestrator, event bus, domain types

LLM:

- @charivo/llm: stateful conversation manager - @charivo/llm/remote: browser client for server API routes - @charivo/llm/openai: direct OpenAI browser client (dev/testing only) and the createOpenAILLMProvider server-side provider - @charivo/llm/openclaw: direct OpenClaw browser client (dev/testing only) and the createOpenClawLLMProvider server-side provider - @charivo/llm/gemini: direct Gemini browser client (dev/testing only) and the createGeminiLLMProvider server-side provider - @charivo/llm/stub: canned responses for tests and demos - @charivo/server/openai: re-exports createOpenAILLMProvider from @charivo/llm/openai (realtime is implemented here; see Realtime below) - @charivo/server/openclaw: re-exports createOpenClawLLMProvider from @charivo/llm/openclaw - @charivo/server/gemini: re-exports createGeminiLLMProvider from @charivo/llm/gemini (realtime is implemented here; see Realtime below)

TTS:

- @charivo/tts: TTS session manager and lip-sync coordination - @charivo/tts/remote: browser player for server TTS routes - @charivo/tts/openai: direct OpenAI browser player (dev/testing only) and the createOpenAITTSProvider server-side provider - @charivo/tts/gemini: direct Gemini browser player (dev/testing only) and the createGeminiTTSProvider server-side provider - @charivo/tts/web: Web Speech API player - @charivo/server/openai: re-exports createOpenAITTSProvider(...) from @charivo/tts/openai - @charivo/server/gemini: re-exports createGeminiTTSProvider(...) from @charivo/tts/gemini

STT:

- @charivo/stt: STT session manager and recording helper - @charivo/stt/remote: browser transcriber for server STT routes - @charivo/stt/openai: direct OpenAI browser transcriber (dev/testing only) and the createOpenAISTTProvider server-side provider - @charivo/stt/gemini: direct Gemini browser transcriber (dev/testing only) and the createGeminiSTTProvider server-side provider - @charivo/stt/web: Web Speech API transcriber - @charivo/stt/openai-realtime: streaming WebRTC transcriber for an OpenAI Realtime transcription session, bootstrapped by an app-supplied function - @charivo/stt/gemini-live: streaming WebSocket transcriber for a Gemini Live transcription session, bootstrapped by an app-supplied function - @charivo/server/openai: re-exports createOpenAISTTProvider(...) from @charivo/stt/openai - @charivo/server/gemini: re-exports createGeminiSTTProvider(...) from @charivo/stt/gemini

Realtime:

- @charivo/realtime: provider-agnostic realtime manager, tool registry, typed state, and session config helpers Supports explicit updateSession(...) session patching without a reconnect on the OpenAI transports. - @charivo/realtime/remote: adapter-dispatched browser client for server realtime routes - @charivo/realtime/openai-agents: OpenAI Agents SDK realtime transport client and adapter - @charivo/realtime/openai: legacy low-level OpenAI realtime transport client and adapter - @charivo/realtime/gemini: Gemini Live WebSocket realtime transport client and adapter - @charivo/server/openai: exports createOpenAIRealtimeProvider(...) - @charivo/server/gemini: exports createGeminiRealtimeProvider(...)

Avatar:

- @charivo/avatar: catalog-constrained avatar expression/motion/gaze tool definitions, instructions, and a result projector, for use with either @charivo/llm or @charivo/realtime

Rendering:

• @charivo/render: render manager, mouse tracking, lip-sync bridge
• @charivo/render-live2d: Live2D Cubism renderer
• @charivo/render/stub: console renderer for tests and demos