사용 매뉴얼 · CanvasOK

설치와 첫 준비

앱에는 MCP 실행용 Node 런타임이 포함되어 있습니다. 별도 Node 설치나 CanvasOK용 API 키는 필요하지 않습니다. 사용할 AI 서비스의 로그인·이용 조건은 해당 하네스에서 설정합니다.

홈페이지에서 호출 이름·약칭 지원 macOS ZIP을 내려받아 압축을 풀고 CanvasOK.app을 Applications 폴더에 복사합니다. 현재 Apple Silicon용이며 공개 서명·공증 전 시험판입니다.
위의 MCP 연결 키트를 별도 폴더에 풀어둡니다. 터미널에서 아래 명령의 /path/to/CanvasOK-mac-connect를 실제 키트 폴더 경로로 바꿔 실행합니다.
생성된 commands.txt에서 사용할 하네스의 등록 순서를 따릅니다. 기존 설정 파일은 통째로 덮어쓰지 말고 canvasok 항목을 병합합니다. 준비 스크립트 자체는 하네스 설정을 자동 변경하지 않습니다.

mkdir -p "$HOME/Documents/CanvasOK-test"
cd /path/to/CanvasOK-mac-connect
python3 prepare.py \
  --app /Applications/CanvasOK.app \
  --project "$HOME/Documents/CanvasOK-test"

하나의 작업을 여러 하네스에서 이어갈 때는 같은 절대 프로젝트 경로를 사용합니다. 앱이나 키트 위치를 옮기면 prepare.py를 다시 실행하고 등록 경로도 갱신하세요. 모델 비교 실험은 프로젝트 폴더를 각각 따로 두는 편이 좋습니다.

이번 배포는 macOS arm64 시험판입니다. Windows·Linux 설치파일은 아직 제공하지 않습니다. 앱 화면의 언어는 한국어·영어이며, 네 언어 호출 이름 지원과는 별개입니다.

AI 하네스 연결

연결 키트는 같은 네이티브 앱을 호출하는 로컬 stdio MCP 설정을 생성합니다. 외부 MCP 서버의 등록 이름은 canvasok로 유지합니다. 아래는 설정 경로 안내이며, 모든 하네스·모델의 실제 자연어 인식을 보장하는 표는 아닙니다.

commands.txt와 함께 사용할 하네스별 설정 템플릿
하네스	설정과 적용
Codex	codex.toml 또는 commands.txt의 Codex 등록 명령을 사용합니다. 같은 로컬 호스트의 Codex CLI와 Desktop은 MCP 설정을 공유합니다. 등록 후 새 대화에서 도구 연결을 확인합니다.
Claude Code / Claude Desktop	Claude Code CLI·Desktop Code 모드는 claude-code.mcp.json을 참고합니다. Claude Desktop의 일반 Chat은 별도 claude-desktop.json 설정입니다. 해당 파일의 mcpServers를 기존 설정에 병합하고 Desktop을 완전히 종료한 뒤 다시 엽니다.
Gemini CLI Antigravity	Gemini CLI는 gemini.settings.json, Antigravity는 antigravity.mcp.json을 사용합니다. Antigravity에서 Gemini 모델을 선택하는 경로와 일반 Gemini 앱은 별개입니다. 일반 Gemini 앱의 로컬 stdio 연결은 이 키트의 지원 범위에 포함하지 않습니다.
OpenCode	현재 검증 환경의 OpenCode v1은 opencode-v1.json을 사용합니다. v2의 mcp.servers 구조는 별도 opencode-v2.json입니다. 설치된 버전에 맞는 하나를 선택하고, Desktop에서는 같은 로컬 서버·프로젝트를 사용합니다.
Cursor	cursor.mcp.json의 mcpServers 항목을 Cursor MCP 설정에 병합합니다. CLI와 데스크톱 에디터에서 해당 프로젝트의 MCP 서버를 활성화하고 도구 목록을 확인합니다.
Kimi Code	kimi-code.mcp.json을 Kimi Code의 MCP 설정으로 등록합니다. CLI·Desktop에서 같은 로컬 설정을 읽는지 확인하고 MCP 서버를 다시 시작합니다.
ZCode / Z.ai	zcode.config.json의 MCP 설정을 ZCode에 병합합니다. 사용하는 앱 버전의 MCP 관리 화면에서 로컬 canvasok 서버를 활성화합니다.
DeepSeek Harness	deepseek-harness.cordis.yml을 참고하여 dsh의 MCP 클라이언트 플러그인에 등록합니다. 개발자 프리뷰의 버전·플러그인 구조가 달라질 수 있으므로 commands.txt의 단계와 실제 도구 목록을 확인합니다.

각 템플릿은 등록을 돕는 자료입니다. 설치된 하네스 버전, MCP 플러그인, 모델의 도구 호출 지원을 별도로 확인해야 합니다. 원격 하네스 서버는 이 Mac의 로컬 앱 경로를 직접 실행할 수 없습니다.

먼저 AI 클라이언트 하나에서 프로젝트를 열어 CanvasOK 도구를 호출하세요. 앱이 같은 세션을 표시합니다. 여러 클라이언트를 함께 쓸 때는 동일한 프로젝트 상태를 다시 읽고 순서대로 작업하세요.

도구 목록에 canvasok가 보이는지 확인한 뒤 “CanvasOK로 32×32 투명 배경 고양이 도트를 만들어줘”라고 요청해 보세요. 도트 작업은 별도 외부 엔진 없이 시험할 수 있습니다.

다국어 이름과 내 약칭

기본 이름은 다음과 같습니다. 이 이름들은 같은 CanvasOK 도구를 가리키며 문서·레이어 이름이나 하네스의 실행 명령을 바꾸지 않습니다.

기본 제공 호출 이름 · 삭제 대상이 아닌 기본 이름
언어	부를 수 있는 이름
한국어	캔버스오케이 · 캔버스 오케이
English	CanvasOK · Canvas OK
日本語	キャンバスオーケー
中文	画布OK · 畫布OK

앱에서 등록하기

한국어 화면의 도구 → 호출 이름·약칭을 엽니다. “캔오케”처럼 내가 부를 이름을 추가하면 바로 저장됩니다. AI 호출 안내 복사로 현재 대화에 붙여 넣을 안내문도 복사할 수 있습니다. 사용자 약칭은 최대 16개, 이름당 Unicode 문자 32개까지입니다. 글자·숫자·결합 문자·공백과 . _ -를 사용할 수 있고 글자 또는 숫자가 하나 이상 필요합니다.

터미널에서 등록하기

prepare.py를 실행한 연결 키트 폴더에서 아래 명령을 사용할 수 있습니다. list는 목록, add는 추가, resolve는 이름 확인, remove는 사용자 약칭 삭제입니다. --json은 기계가 읽기 쉬운 결과를 출력합니다.

./bin/canvasok aliases list --json
./bin/canvasok aliases add "캔오케" --json
./bin/canvasok aliases resolve "캔오케" --json
./bin/canvasok aliases remove "캔오케" --json

사용자 약칭 전체를 비우려면 ./bin/canvasok aliases reset --json을 실행합니다. 기본 이름은 남습니다. 표시 이름은 입력한 모양을 보존하고, 비교할 때는 전각·반각 등의 NFKC 정규화, 공백 정리, 영문 대소문자 차이를 처리합니다. 약칭은 사용자 데이터 영역의 aliases.json에 저장되며 CANVASOK_ALIASES_FILE로 경로를 지정할 수 있습니다.

저장한 이름은 MCP 초기 안내와 문서 도구 설명·메타데이터에 전달됩니다. 연결 중 도구 목록 변경을 반영하는 하네스도 있지만, 새 약칭이 안 보이면 MCP 서버를 재시작하고 새 대화를 여세요. 실제 설정에 같은 별칭 파일을 읽는지 확인하세요. 외부 하네스 설정 파일을 자동 수정하지는 않습니다.

이렇게 불러보세요

캔오케로 32×32 투명 배경 고양이 도트를 만들어줘.

Use Canvas OK to create a 32×32 pixel cat on a transparent background.

キャンバスオーケーで、背景が透明な32×32ピクセルの猫を描いて。

用画布OK画一只32×32像素的猫，背景透明。

별칭은 도구를 찾도록 돕는 자연어 안내입니다. /캔오케 같은 슬래시 명령을 새로 만들거나 권한을 추가하지 않습니다. harness-instructions.md를 하네스의 지침에 추가해 명시할 수 있습니다. 이해하지 못하면 “캔오케는 canvasok MCP 도구야. 현재 문서를 확인하고 작업해줘”라고 구체적으로 요청하세요.

AI와 직접 편집 이어가기

AI에게 도트 문서를 만들고 편집하도록 요청합니다. CanvasOK 창에서 같은 문서의 변경을 확인합니다.
직접 고치고 싶은 순간 앱의 AI 편집 일시정지를 누릅니다. 진행 중 배치가 안전하게 마무리될 때까지 기다립니다.
눈·귀·색상을 직접 수정한 뒤 변경 적용으로 확정합니다. 현재 편집기 종류에 맞는 적용 동작을 사용하세요.
앱에서 재개하고 외부 하네스에 최신 상태를 다시 읽도록 요청합니다. 정지 전에 대기하던 명령은 자동 실행되지 않습니다.

현재 문서를 다시 읽어줘. 내가 수정한 눈은 유지하고 꼬리 모양만 바꿔줘.

일시정지는 CanvasOK의 AI 쓰기 권한을 제어합니다. 외부 모델의 추론이나 과금을 멈추지는 않습니다. 오래된 상태를 기준으로 거절된 변경은 최신 상태를 읽고 다시 요청해야 합니다.

과정 기록과 MP4

2D 문서의 편집 과정을 이벤트로 기록하고 동영상으로 출력할 수 있습니다. 프롬프트는 명시적으로 기록한 시점에 맞춰 영상 하단에 누적 표시됩니다.

앱의 기록·동영상 메뉴에서 기록을 시작합니다. 화면에 보여줄 프롬프트도 등록하거나 AI에게 프롬프트를 기록하라고 명시합니다.
AI 작업과 사람의 직접 편집·적용을 이어갑니다. 일시정지·재개 과정도 기록으로 남습니다. 내보내기 전 기록 미리보기를 확인합니다.
원하는 배속을 선택하고 MP4로 내보냅니다. 편집 가능한 원본도 번들로 따로 저장해 두세요.

현재 MP4 출력에는 별도 FFmpeg가 필요합니다. 결과 영상은 무음이며, 모든 외부 채팅이나 데스크톱 화면을 자동 녹화하는 기능은 아닙니다.

입력 파일과 현재 범위

이미지와 AI 문맥: 이미지를 가져와 작업하거나 참고 영역을 고를 수 있습니다. 이미지 문맥은 선택한 입력과 허용된 연결 설정에서 전달합니다. 로컬 파일을 열었다고 외부 모델에 자동 전송하지는 않습니다. 이미지 전달은 해당 하네스·모델의 지원도 필요합니다.
MIDI: MIDI를 가져와 음표·트랙을 AI와 함께 편집하고 MIDI로 저장합니다. 악기 소리를 내는 MIDI 재생·렌더는 후속 기능입니다.
오디오 클립: WAV/MP3 입력, 재생과 파형, 클립 구간·음량·페이드 편집과 WAV 출력을 지원합니다. 음성 인식·음성 생성·음악 생성 기능은 포함하지 않습니다.
외부 엔진과 후속 분야: 도트·MIDI·오디오 편집은 내장 경로로 시작할 수 있습니다. 벡터 작업에는 VectorCraft, 일부 브러시·레이어 작업에는 PhotoCraft가 필요합니다. 3D·본격 영상 편집은 후속 범위입니다.

잘 안 될 때

새 약칭을 AI가 못 알아들어요: aliases list로 등록을 확인하고, 하네스의 MCP 서버를 재시작한 뒤 새 대화를 엽니다. CANVASOK_ALIASES_FILE을 사용한다면 앱과 하네스가 같은 파일을 읽어야 합니다. 실제 모델이 이름을 이해하는지는 연결마다 다르므로 canvasok를 함께 명시해 요청합니다.
앱이 열리지 않거나 다른 문서가 보여요: 앱과 키트 위치, 절대 프로젝트 경로를 확인하고 prepare.py를 다시 실행합니다. 생성된 commands.txt의 수동 세션 연결 명령을 참고하세요. 이전 프로젝트를 가리키는 중복 MCP 등록은 제거합니다.
AI의 수정이 거절돼요: 앱에서 AI 쓰기가 일시정지되어 있는지, 사람이 적용한 뒤 문서 상태가 바뀌었는지 확인합니다. 재개 후 현재 문서와 작업 상태를 다시 읽어 새 변경을 요청하세요. 거절된 옛 명령을 그대로 재전송하지 않습니다.
모델을 비교하려면요?: 같은 입력·프롬프트·예산으로 별도 프로젝트를 만들고 모델명과 하네스 이름·버전을 따로 기록하세요. 모델 결과, 사람이 개입한 횟수, 소요 시간과 과정 영상을 함께 비교합니다.

support@mdok.net ↗

이름을 부르고,함께 만들어보세요.