> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> cast CLI 또는 MCP 서버를 사용하여 OpenClaw 에이전트 워크플로우에 타입캐스트 TTS를 추가하세요.

<Info>
  [OpenClaw](https://docs.openclaw.ai/)는 도구, 셸 명령, MCP 서버를 실행할 수 있는 AI 에이전트 런타임입니다. 타입캐스트와 함께 사용하면 에이전트가 단일 명령으로 자연스러운 음성을 생성할 수 있습니다.
</Info>

## 할 수 있는 것

타입캐스트와 OpenClaw를 사용하면 다음을 할 수 있습니다:

* **에이전트 워크플로우에서 음성 생성** — 모든 텍스트 출력을 자연스러운 오디오로 변환
* **500개 이상의 보이스 선택** — 성별, 나이, 스타일별로 보이스 선택
* **감정 제어** — 스마트 이모션 또는 이모션 프리셋(happy, sad, angry, whisper 등) 적용
* **37개 언어 지원** — 영어, 한국어, 일본어, 중국어 등으로 음성 생성
* **오디오 파이프라인 자동화** — 다른 도구와 결합하여 엔드투엔드 콘텐츠 제작

***

## 사전 요구 사항

시작하기 전에 다음을 준비하세요:

1. **OpenClaw** 설치 — `npm install -g openclaw@latest`
2. **타입캐스트 API 키** — [여기서 받기](https://typecast.ai/developers/api/)
3. **타입캐스트 CLI (`cast`)** — 가장 빠른 연동 방법

***

## 빠른 시작: cast CLI

공식 타입캐스트 CLI는 음성 생성을 단일 셸 명령으로 처리합니다. 에이전트가 셸 명령을 실행할 수 있다면 커스텀 프로바이더 없이 타입캐스트 오디오를 생성할 수 있습니다.

### 단계 1: CLI 설치

<Tabs>
  <Tab title="Homebrew (macOS/Linux)">
    ```bash theme={null}
    brew install neosapience/tap/cast
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go install github.com/neosapience/cast@latest
    ```
  </Tab>
</Tabs>

### 단계 2: 인증

```bash theme={null}
cast login
```

또는 키를 직접 전달:

```bash theme={null}
cast login <your-api-key>
```

### 단계 3: 확인

```bash theme={null}
cast "안녕하세요!" --out ./test.mp3 --format mp3
```

파일이 정상적으로 생성되면 OpenClaw와 함께 사용할 준비가 된 것입니다.

***

## 연동 방법

### 방법 1: cast를 통한 Local exec (권장)

OpenClaw는 local `exec`과 remote `code_execution`을 구분합니다. 설치된 바이너리에 접근해야 할 때는 local `exec`을 사용하세요.

OpenClaw 에이전트에게 다음과 같이 요청하세요:

```text theme={null}
local exec으로 다음 명령을 실행해줘:
cast "금요일 오후 7시로 예약이 확정되었습니다." --language kor --format mp3 --out ./confirmation.mp3
생성된 파일 경로를 반환해줘.
```

반복적으로 사용하려면 OpenClaw 설정에 프로젝트 인스트럭션을 추가하세요:

```markdown theme={null}
사용자가 음성 오디오를 요청하면 로컬 `cast` CLI를 사용하세요.
기본 명령:

cast "$TEXT" --voice-id "$TYPECAST_VOICE_ID" --language "${TYPECAST_LANGUAGE:-kor}" --format "${TYPECAST_FORMAT:-mp3}" --out "$OUTPUT"

API 키를 출력하지 마세요. 헤드리스 세션에서는 `--out`을 사용하세요.
```

**권장 환경 변수:**

```bash theme={null}
export TYPECAST_VOICE_ID="tc_60e5426de8b95f1d3000d7b5"
export TYPECAST_LANGUAGE="kor"
export TYPECAST_FORMAT="mp3"
```

### 방법 2: MCP 서버 (도구 네이티브)

더 깊은 연동을 위해 타입캐스트 API MCP 서버를 연결하여 OpenClaw가 TTS 도구를 직접 호출하도록 하세요.

<Tabs>
  <Tab title="CLI 등록">
    ```bash theme={null}
    openclaw mcp set typecast '{
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neosapience/typecast-api-mcp-server.git",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "${TYPECAST_API_KEY}",
        "TYPECAST_OUTPUT_DIR": "./typecast_output"
      }
    }'
    ```

    확인:

    ```bash theme={null}
    openclaw mcp show typecast
    ```
  </Tab>

  <Tab title="번들 설정 (JSON)">
    OpenClaw 플러그인 번들에 추가:

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "typecast": {
            "command": "uvx",
            "args": [
              "--from",
              "git+https://github.com/neosapience/typecast-api-mcp-server.git",
              "typecast-api-mcp-server"
            ],
            "env": {
              "TYPECAST_API_KEY": "${TYPECAST_API_KEY}",
              "TYPECAST_OUTPUT_DIR": "./typecast_output"
            },
            "connectionTimeoutMs": 30000
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

등록 후 타입캐스트 도구가 `typecast__synthesize_speech`, `typecast__list_voices` 등으로 나타납니다. 에이전트에게 요청:

```text theme={null}
typecast MCP 도구를 사용해서 "안녕하세요"를 mp3 파일로 합성해줘.
```

<Tip>
  `https://typecast.ai/docs/mcp`에 있는 원격 문서 MCP를 연결하면 오디오를 생성하지 않고도 연동 가이드를 MCP 리소스로 제공받을 수 있습니다.
</Tip>

***

## 보이스 및 감정 제어

### 보이스 찾기

`cast` CLI로 사용 가능한 보이스를 조회하세요:

```bash theme={null}
cast voices --model ssfm-v30
```

또는 에이전트에게 MCP `list_voices` 도구를 사용하여 성별, 나이, 사용 사례별로 검색하도록 요청하세요.

### 감정 옵션

<CardGroup cols={2}>
  <Card title="스마트 이모션" icon="wand-magic-sparkles">
    AI가 텍스트 맥락에서 최적의 감정을 자동으로 감지합니다. 자연스러운 대화와 스토리텔링에 적합합니다.
  </Card>

  <Card title="이모션 프리셋" icon="sliders">
    7가지 감정 중에서 수동으로 선택합니다: Normal, Happy, Sad, Angry, Whisper, Tone Up, Tone Down.
  </Card>
</CardGroup>

**cast CLI로 감정 적용:**

```bash theme={null}
# 스마트 이모션 (ssfm-v30 전용)
cast "정말 믿을 수 없어요!" --model ssfm-v30 --emotion smart --out ./excited.mp3

# 이모션 프리셋
cast "정말 유감입니다." --model ssfm-v30 --emotion sad --out ./sorry.mp3
```

***

## 예시 워크플로우

<AccordionGroup>
  <Accordion title="자동 회의 요약 내레이션">
    1. OpenClaw가 회의 녹취록을 수신
    2. 에이전트가 LLM으로 핵심 내용 요약
    3. 에이전트가 `cast`로 오디오 요약 생성
    4. 출력 파일을 Slack 또는 Google Drive에 업로드
  </Accordion>

  <Accordion title="다국어 콘텐츠 파이프라인">
    1. 에이전트가 영어 콘텐츠 수신
    2. 한국어, 일본어, 중국어로 번역
    3. 각 언어에 대해 타입캐스트 오디오 생성
    4. 모든 오디오 파일을 클라우드 스토리지에 저장
  </Accordion>

  <Accordion title="CI/CD 음성 알림">
    1. 빌드 파이프라인이 OpenClaw 에이전트를 트리거
    2. 에이전트가 상태 메시지 생성: "빌드 성공" 또는 "빌드 실패"
    3. `cast`로 음성 알림 생성
    4. 오디오를 팀 Discord 채널에 게시
  </Accordion>
</AccordionGroup>

***

## 문제 해결

<AccordionGroup>
  <Accordion title="cast: command not found">
    OpenClaw가 도구를 실행하는 동일한 런타임에 CLI를 설치하세요. Homebrew로 설치한 경우 `PATH`에 Homebrew bin 디렉토리가 포함되어 있는지 확인하세요.
  </Accordion>

  <Accordion title="인증 오류">
    `cast login`을 실행하거나 `cast login <api_key>`로 API 키를 직접 전달하세요. [타입캐스트 API 콘솔](https://typecast.ai/developers/api/)에서 확인 가능합니다.
  </Accordion>

  <Accordion title="헤드리스 세션에서 오디오 재생 불가">
    오디오를 재생하는 대신 `--out`으로 파일에 저장하세요. 사용자에게 파일 경로를 반환하세요.
  </Accordion>

  <Accordion title="에이전트가 명령을 출력만 하고 실행하지 않음">
    에이전트에게 `exec` 도구 또는 로컬 셸을 사용하도록 명시적으로 요청하세요. 프로젝트 인스트럭션에 이 동작을 명확히 하세요.
  </Accordion>

  <Accordion title="MCP 서버 연결 실패">
    * `uvx`가 설치되어 있고 `PATH`에 있는지 확인: `command -v uvx`
    * `TYPECAST_API_KEY` 환경 변수가 설정되어 있는지 확인
    * `openclaw mcp show typecast`로 등록 상태 확인
  </Accordion>
</AccordionGroup>

***

## 리소스

<CardGroup cols={2}>
  <Card title="타입캐스트 API 콘솔" icon="key" href="https://typecast.ai/developers/api/">
    API 키 발급받기
  </Card>

  <Card title="보이스 라이브러리" icon="microphone" href="https://typecast.ai/developers/api/voices">
    사용 가능한 모든 보이스 둘러보기
  </Card>

  <Card title="API 레퍼런스" icon="code" href="/ko/api-reference/text-to-speech/text-to-speech">
    타입캐스트 API 탐색하기
  </Card>

  <Card title="MCP 서버" icon="server" href="/ko/integrations/mcp-server">
    타입캐스트 MCP 서버 문서
  </Card>
</CardGroup>