---
slug: app-actions
title: "앱 실행 도구: run_aiakiv_app_action 과 연결마다 다른 점"
description: "AI가 AiAkiv 앱(콘솔 앱 등)에 일을 시키는 도구. 폴더 연결과 API 키 연결, 플러그인으로 설치한 연결에는 있고, 앱 디렉터리에서 설치하거나 계정에 등록한 연결(ChatGPT의 공식 플러그인, Claude 웹과 모바일)에는 없다. 없는 연결에서 할 수 있는 것과 이 도구가 있는 연결. ChatGPT에서는 개발자 모드로 직접 연결하거나 폴더에 API 키로 연결하면 쓸 수 있다."
lang: ko
---


# 27. 앱 실행 도구: run_aiakiv_app_action 과 연결마다 다른 점

AI가 팀을 만들고, 초대를 보내고, 내가 만든 카드를 내리는 일은 모두 도구 하나를
거친다. **`run_aiakiv_app_action`** 이다. 이 도구는 어느 연결에나 있는 것이 아니다.
이 문서는 이 도구가 무엇이고, 어느 연결에 있고 어느 연결에 없는지, 없을 때 무엇을
하면 되는지를 정리한다.

> **한 줄 요약.** `run_aiakiv_app_action` 은 AI가 AiAkiv 앱에 일을 시키는 도구다.
> 폴더 연결과 API 키 연결, 그리고 Claude Code와 Cursor에 플러그인으로 설치한 연결에
> 있다. 앱 디렉터리에서 설치하거나 계정에 등록한 연결(ChatGPT의 플러그인 디렉터리
> 설치, Claude 웹과 모바일 앱의 계정 커넥터)에는 없다. 그 연결에서도 기억 저장과
> 검색, 카드 만들기는 그대로 되고, 콘솔 관리는 웹 콘솔에서 직접 한다.
>
> 이 도구로 AI에게 콘솔 관리 같은 앱 일을 시키는 기능을 **앱 기능**이라고 부른다.
> **앱 기능은 공식 ChatGPT 플러그인에서 지원하지 않는다.** ChatGPT에서 앱 기능을
> 쓰려면 개발자 모드로 직접 연결하거나 폴더에 API 키로 연결한다(§3).

이 문서는 사람과 AI가 같이 읽는다. §1~§5는 사람용, **§6은 AI용 레퍼런스**다.

---

## 1. 무엇인가

`run_aiakiv_app_action` 은 **AiAkiv 앱에 일을 시키는 창구**다. AI는 어느 앱(`app`)에
무슨 일(`action`)을 시킬지 골라 이 도구를 부른다.

- **콘솔 앱**(`app="console"`)이 대표다. 팀, 초대, 연결, 감사 기록, 저장 대상 이력,
  프로젝트, 저장 대상(Main), 그리고 내가 만든 카드의 목록과 삭제, 검색 노출, 분류
  태그를 대화에서 다룬다 → [AI에게 콘솔 일 시키기](console-actions).
- 그 밖의 AiAkiv 앱도 같은 도구로 부른다.

콘솔 앱이 하는 일은 대략 이렇다.

- **팀**: 내 팀 목록 보기, 팀 만들기, 초대 보내기, 받은 초대 수락과 거절
- **팀 연결**: 초대 코드 발급과 상환, 연결 수락과 거절, 일시정지와 재개
- **기록**: 팀의 권한 감사 기록과 저장 대상(Main) 전환 이력 보기
- **프로젝트**: 만들기, 기본 프로젝트 지정, 페르소나 고치기, 삭제
- **저장 대상**: Main 바꾸기와 해제, Main 끄고 켜기, 공개 대상 보기와 숨기기
- **카드**: 내가 만든 카드의 목록, 분류 태그, 검색 노출, 내리기
- **AI 권한**: 내가 켜 둔 AI 권한 확인

**이 일은 모두 사람이 웹 콘솔(대시보드, [app.aiakiv.com](https://app.aiakiv.com))에
접속해 직접 할 수 있다.** AI에게 시키는 것은 편의다. 이 도구가 없는 연결을 쓰는
사람도 웹 콘솔에서 전부 할 수 있다. 계정 삭제, 팀 삭제, 소유권 이전, API 키 발급 같은
일은 원래부터 웹 콘솔에서만 한다.

**저장과는 다르다.** 기억을 남기는 것은 `save_memory` 이고, 사용자가 `ak` 로 명시했을
때만 한다([저장하기](saving)). `run_aiakiv_app_action` 은 기억을 남기는 도구가
아니라 앱이 맡은 일을 실행하는 도구다. 콘솔 앱으로 팀을 만들어도 기억이 하나 생기지는
않는다.

**카드 만들기는 이 도구가 아니다.** 카드는 전용 도구 `create_aiakiv_card` 로 만든다
(§4).

---

## 2. 어느 연결에 있나

AiAkiv 서버는 하나다. 어떻게 붙였느냐에 따라 AI에게 보이는 도구 목록이 다르다.
계정, 권한, 읽을 수 있는 기억은 어느 연결에서나 같다.

| 연결 | 예 | `run_aiakiv_app_action` |
|------|-----|------|
| **폴더 연결**: 프로젝트를 정해서 붙인 연결 | Claude Code와 Claude Desktop `</> Code` 의 `.mcp.json`, Cursor의 `.cursor/mcp.json` | **있다** |
| **API 키 연결** | Gemini CLI, ChatGPT의 폴더 연결(`.codex/config.toml`), Antigravity | **있다** |
| **플러그인으로 설치한 연결** | Claude Code와 Cursor에 AiAkiv 플러그인으로 설치한 경우 | **있다** |
| **ChatGPT에서 개발자 모드로 직접 연결한 연결** | chatgpt.com 웹페이지에서 개발자 모드를 켜고 §3의 주소를 직접 등록한 경우 | **있다** |
| **앱 디렉터리에서 설치하거나 계정에 등록한 연결** | ChatGPT와 ChatGPT classic에서 플러그인 디렉터리로 설치한 AiAkiv Memory, Claude 웹과 모바일 앱에서 쓰는 계정 커넥터 | **없다** |

프로젝트를 정하지 않고 주소만 넣어 로그인으로 붙인 그 밖의 연결도 마지막 줄과 같다.

**앱 기능은 공식 ChatGPT 플러그인에서 지원하지 않는다.** ChatGPT 플러그인 디렉터리의
공식 AiAkiv Memory 플러그인은 앱 기능(AI에게 콘솔 관리 같은 앱 일을 시키는 기능)을
지원하지 않는다. ChatGPT에서 앱 기능을 쓰는 방법은 둘이다. 개발자 모드로 직접
연결하거나, 폴더에 API 키로 연결한다(§3).

두 목록의 차이는 이 도구 하나다. 저장, 검색, 원문 조회, 연결된 팀 읽기, 그래프 질의,
카드 만들기는 어느 연결에서나 같다.

Claude Code와 Claude Desktop의 `</> Code` 는 폴더 연결과 계정 커넥터를 한 대화에 함께
붙일 수 있다. 그때 이 도구는 폴더 연결 쪽에만 있다 → [계정 커넥터와 폴더
연결](account-connector).

플러그인으로 설치했는데 이 도구가 보이지 않으면 플러그인이 예전 판일 수 있다.
플러그인을 최신 판으로 올린다.

### 없는 연결에서 부르면

도구 목록에 아예 나오지 않는다. AI가 이름을 기억해 불러도 다음 문구로 거절되고,
**아무 일도 일어나지 않는다.**

```
This tool is not available on this connection.
```

### 그 연결에서 할 수 있는 것

| 하고 싶은 일 | 이 도구가 없는 연결에서 |
|-------------|--------------------------|
| 기억 저장, 검색, 고치기, 숨기기 | 그대로 된다 |
| 카드 만들기 | 그대로 된다(`create_aiakiv_card`) |
| 카드 목록, 삭제, 검색 노출, 분류 태그 | 웹 콘솔 **데이터 → 카드**에서 직접 한다 |
| 팀, 초대, 연결, 프로젝트, 저장 대상, Main 끄고 켜기 | 웹 콘솔([app.aiakiv.com](https://app.aiakiv.com))에서 직접 한다 |
| 저장 대상(Main) 바꾸기 | 콘솔에서 바꾸거나, AI가 프로젝트 목록과 함께 건네는 전환 링크(`switch_url`)를 눌러 바꾼다 |

---

## 3. 이 도구가 필요할 때

AI에게 콘솔 관리를 시키는 일은 `run_aiakiv_app_action` 이 있는 연결에서 된다. 폴더
연결, API 키 연결, 플러그인으로 설치한 연결, ChatGPT에서 개발자 모드로 직접 연결한
연결이 그렇다. 앱 디렉터리에서 설치하거나 계정에 등록한 연결에는 이 도구가
없으므로, 그 연결에서는 웹 콘솔에서 직접 관리한다.

클라이언트마다 이 도구가 있는 연결은 다음과 같다.

- **Claude**: Claude Code와 Claude Desktop의 `</> Code` 는 폴더에 `.mcp.json` 을 두고
  연결한다 → [폴더 바인딩](folder-binding), [Claude Desktop](desktop-binding).
  Claude Code에 AiAkiv 플러그인으로 설치한 연결에도 있다. Claude 웹과 모바일 앱에서
  쓰는 계정 커넥터에는 없다. 계정 커넥터와 폴더 연결이 함께 붙을 때의 주의는
  [계정 커넥터와 폴더 연결](account-connector)에 있다.
- **ChatGPT**: 앱 기능은 공식 ChatGPT 플러그인에서 지원하지 않는다. 플러그인
  디렉터리의 공식 AiAkiv Memory 플러그인으로 설치한 연결에는 이 도구가 없다.
  ChatGPT에서 쓰는 방법은 둘이다.
  - **개발자 모드로 직접 연결**: chatgpt.com 웹페이지에서 개발자 모드를 켜고 주소
    `https://mcp.aiakiv.com/mcp?apps=all` 을 직접 등록한다. 계정 전체에 적용되고
    Main 프로젝트를 따른다. 자세한 순서는 [ChatGPT 연결](chatgpt) §6.
  - **폴더에 API 키로 연결**: 작업 폴더의 `.codex/config.toml` 에 프로젝트 고정 API
    키로 붙는다. 그 폴더가 한 프로젝트에 고정된다. 플러그인 설치와 함께 둘 수 있고,
    폴더 쪽은 `AiAkiv-<프로젝트 이름>` 이라는 다른 이름으로 보인다
    → [ChatGPT 연결](chatgpt) §2, §4.

  플러그인으로 설치한 연결과 직접 연결은 도구 이름이 같으니 한 대화에는 하나만 켠다.
- **Cursor**: 폴더의 `.cursor/mcp.json` 으로 붙인 연결과 AiAkiv 플러그인으로 설치한
  연결에 있다 → [폴더 바인딩](folder-binding).
- **API 키만 받는 클라이언트**(Gemini CLI, Antigravity 등) → [연결 인증](auth).

AI에게 무언가를 **바꾸는** 콘솔 일을 시키려면, API 키는 발급할 때 **"AI 콘솔 관리
허용 (manage)"** 을 체크한 키여야 한다([연결 인증](auth)).

---

## 4. 카드 만들기는 전용 도구로

카드는 **`create_aiakiv_card`** 로 만든다. 이 도구는 모든 연결에 있다. 입력 칸이
정해져 있어서 형식을 따로 묻는 단계가 없다 → [카드](cards).

예전에는 `run_aiakiv_app_action(app="card", action="create")` 로 만들었다. 이 경로는
**당분간 동작**하지만, 응답에 "다음 요청부터 `create_aiakiv_card` 로 만들라"는 안내가
붙는다. 예전 판 AiAkiv 스킬이 이 경로를 쓰고 있다면 그 안내가 보일 것이다. 그 카드는
이미 만들어졌으니 다시 시킬 필요는 없다.

---

## 5. 권한은 콘솔 문서에서

이 도구로 콘솔 일을 시킬 때의 권한은 따로 있다. 액션마다 붙는 **AI 권한**(읽기는
기본 켜짐, 편집은 기본 꺼짐), API 키의 **manage 스코프**, 시킬 수 있는 액션 전체 표는
[AI에게 콘솔 일 시키기](console-actions)에 있다.

---

## 6. AI를 위한 레퍼런스

이 절은 AiAkiv에 연결된 AI가 읽는다.

### 있는지 판단

- **도구 목록에 `run_aiakiv_app_action` 이 있는지로 판단한다.** 목록에 없으면 부르지
  않는다.
- 불렀는데 `This tool is not available on this connection.` 이 오면 **아무 일도
  일어나지 않았다.** 다시 부르지 않는다.
- 이 도구가 없는 연결에서 콘솔 일(팀, 초대, 연결, 프로젝트, 저장 대상, 카드 관리)을
  요청받으면, 이 연결에서는 할 수 없다고 말하고 웹 콘솔(`https://app.aiakiv.com`)의
  해당 메뉴를 알려 준다. 카드 관리는 **데이터 → 카드**다.
- 한 대화에 AiAkiv 연결이 둘이면 연결마다 도구 목록을 따로 본다. 이 도구는 폴더 연결
  쪽에만 있을 수 있다.

### 부르는 법

| 일 | 도구 |
|----|------|
| 카드 만들기 | `create_aiakiv_card(title=…, bullets=[…], conclusion=…, source_count=…, tags=[…], body=…)` → [카드 §8](cards) |
| 콘솔 일 | `run_aiakiv_app_action(app="console", action="<이름>", data={...})`. 액션 표는 `action="describe"` → [AI에게 콘솔 일 시키기 §8](console-actions) |
| 기억 저장 | `save_memory`. 이 도구로 저장하지 않는다 |

- 카드를 `run_aiakiv_app_action(app="card", …)` 로 만들지 않는다. 그 경로의 응답에
  `next_request_note` 가 있으면, 그 카드는 이미 공개된 것이다. **같은 호출을 다시
  하지 않는다.**
- 콘솔 일의 권한 오류(`console_permission_disabled`)는 `settings_url` 을 사용자에게
  건네고 멈춘다([AI에게 콘솔 일 시키기 §8](console-actions)).

### 연결별 요약

| 연결 | `run_aiakiv_app_action` |
|------|----------|
| 폴더 연결(프로젝트가 정해진 연결) | 있다 |
| API 키 연결 | 있다 |
| 플러그인으로 설치한 연결(Claude Code, Cursor) | 있다 |
| ChatGPT에서 개발자 모드로 직접 연결한 연결(§3) | 있다 |
| 앱 디렉터리에서 설치하거나 계정에 등록한 연결(ChatGPT의 플러그인 디렉터리 설치, Claude 웹과 모바일 앱의 계정 커넥터) | 없다 |
| 프로젝트를 정하지 않고 로그인으로 붙인 그 밖의 연결 | 없다 |

`create_aiakiv_card` 는 어느 연결에나 있다. 연결 방식은 도구 목록만 바꾸고 계정과
권한, 읽을 수 있는 범위는 바꾸지 않는다.

---

## 관련 문서

- 콘솔 일과 AI 권한 → [AI에게 콘솔 일 시키기](console-actions)
- 카드 만들기와 관리 → [카드](cards)
- AI용 도구 지도 → [AI를 위한 안내](for-ai-agents)
- OAuth와 API 키, manage 스코프 → [연결 인증](auth)
- 폴더 연결 → [폴더 바인딩](folder-binding)
- ChatGPT 연결 → [ChatGPT 연결](chatgpt)