OpenCode iMessage Remote Control

Control your Mac mini from anywhere using iMessage

English • 中文文档 • Installation • Usage

中文文档

📖 简介

本插件让你可以通过 iMessage 远程控制 OpenCode Desktop。从 iPhone 发送命令，即时获得结果——适用于：

• 🏠 家庭服务器管理
• 🚀 远程快速部署
• 📊 查看系统状态
• 🔧 紧急故障排查

✨ 功能特性

• 🔒 安全：只处理授权发送者的消息
• ⚡ 高效：默认待机，不占用资源
• 📱 原生：使用系统自带 iMessage
• 🎯 简单：中文自然语言触发
• 🛡️ 安全：自动阻止危险命令
• 📋 完整：完整命令执行与输出返回
• 🔐 远程授权：手机端数字选项授权

📦 安装

前置要求

• macOS 12.0 或更高版本
• OpenCode Desktop v1.2.6+
• Bun 运行时
• 已配置 Apple ID 的 iMessage

快速安装

# 安装插件
bunx oh-my-imsg install

# 或从 GitHub 安装
bunx github:neal/oh-my-imsg install

手动安装

1. 克隆仓库：

git clone https://github.com/neal/oh-my-imsg.git
cd oh-my-imsg
bun install
bun run build

2. 添加到 OpenCode 配置 (~/.config/opencode/opencode.jsonc)：

{
  "plugin": ["file:///Users/你的用户名/oh-my-imsg"]
}

🎮 使用方法

启动远程控制

在 OpenCode Desktop 中输入以下任一指令：

• i-start
• i-start
• 开始 iMessage 遥控

或使用命令：

/i-start

停止远程控制

在 OpenCode Desktop 中输入以下任一指令：

• i-stop
• i-stop
• 关闭 iMessage 遥控

或使用命令：

/i-stop

查看状态

/i-status

通过 iMessage 发送命令

监听启动后，从 iPhone 发送 shell 命令：

ls -la ~/Projects

你会收到回复：

🤖｜total 32
drwxr-xr-x   8 neal  staff   256 Feb 18 10:00 .
...

🔐 远程授权系统

当你不在电脑前时，可通过手机授权操作：

1. 发送「请求授权」到 Mac
2. 收到带编号的选项
3. 回复数字执行操作

示例：

你：请求授权
Mac：需要授权：插件安装
     [1] 备份配置并安装插件
     [2] 仅备份配置
     [3] 查看状态
     [4] 取消
你：1
Mac：✅ 已备份并安装

⚙️ 配置

编辑 ~/.oh-my-imsg.json：

{
  // 允许发送者 - 你的手机号或 Apple ID
  "allowedSenders": [
    "+8613800138000",
    "[email protected]"
  ],
  
  // 轮询间隔（毫秒）
  "pollInterval": 5000,
  
  // 命令执行超时（毫秒）
  "commandTimeout": 30000,
  
  // 启用调试日志
  "debug": false,
  
  // LLM API 配置（可选，用于自然语言对话）
  // 支持 OpenAI 兼容的 API
  "llm": {
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-xxx",
    "model": "gpt-4o-mini",
    "maxTokens": 500
  }
}

🔌 LLM API 配置说明

插件支持多种 API 格式：

| API 类型 | apiType | baseURL 示例 | model 示例 | |----------|---------|--------------|-----------| | OpenAI 兼容 | openai | https://api.openai.com/v1 | gpt-4o-mini | | Anthropic Claude | claude | https://api.anthropic.com | claude-3-5-sonnet-20241022 | | Google Gemini | gemini | https://generativelanguage.googleapis.com/v1beta | gemini-2.0-flash | | 自动检测 | auto | - | - (默认) |

自动检测规则：

• URL 包含 anthropic.com 或 claude → Claude API
• URL 包含 generativelanguage.googleapis.com 或 gemini → Gemini API
• 其他 → OpenAI 兼容 API

示例配置：

// OpenAI 兼容 API
{
  "llm": {
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-xxx",
    "model": "gpt-4o-mini",
    "apiType": "auto"
  }
}

// Anthropic Claude 原生 API
{
  "llm": {
    "baseURL": "https://api.anthropic.com",
    "apiKey": "sk-ant-xxx",
    "model": "claude-3-5-sonnet-20241022",
    "apiType": "claude"
  }
}

// Google Gemini 原生 API
{
  "llm": {
    "baseURL": "https://generativelanguage.googleapis.com/v1beta",
    "apiKey": "AIza-xxx",
    "model": "gemini-2.0-flash",
    "apiType": "gemini"
  }
}

为什么需要配置 LLM API？

OpenCode 插件 API 有安全限制，无法使用内置模型。因此需要配置外部 API 来支持自然语言对话功能。

如果只使用 Shell 命令：

不需要配置 llm 字段。使用 $ 前缀的 Shell 命令不需要 LLM API：

$ ls -la
$ pwd
$ docker ps

⚠️ 其他兼容方案

如果不想使用原生 API，还可以使用以下方案：

方案 1：OpenRouter（统一接口）

OpenRouter 提供统一的 OpenAI 兼容接口，支持多种模型：

{
  "llm": {
    "baseURL": "https://openrouter.ai/api/v1",
    "apiKey": "sk-or-xxx",
    "model": "anthropic/claude-3-haiku"
  }
}

支持的模型：

• Claude: anthropic/claude-3-opus, anthropic/claude-3-sonnet, anthropic/claude-3-haiku
• Gemini: google/gemini-pro, google/gemini-1.5-pro
• Llama: meta-llama/llama-3.1-70b-instruct
• Mistral: mistralai/mistral-large

方案 2：本地模型

{
  "llm": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "llama3"
  }
}

本地模型推荐：

• Ollama: https://ollama.ai
• LM Studio: https://lmstudio.ai

方案 3：代理服务

代理服务可以将多种 API 转换为 OpenAI 格式：

| 代理服务 | 说明 | |----------|------| | one-api | 支持 OpenAI、Claude、Gemini 等 | | one-hub | one-api 的增强版 | | New API | 支持中转和镜像 |

🛠️ 支持的 API 错误处理

插件会自动处理以下错误：

| 错误码 | 处理方式 | |--------|----------| | 429 (Rate Limit) | 自动重试，等待后再次请求 | | 401 (Unauthorized) | 提示 API Key 无效 | | 402 (Payment Required) | 提示余额不足 | | 404 (Not Found) | 提示模型或 API 地址错误 | | 5xx (Server Error) | 自动重试 3 次 | | Timeout | 30 秒超时，自动重试 |

🔑 权限设置

1. 完全磁盘访问

用途：读取 iMessage 数据库

开启方法：

1. 系统偏好设置 → 隐私与安全性 → 完全磁盘访问
2. 点击 + 按钮
3. 添加 Terminal.app 或 OpenCode.app
4. 重启应用

2. 自动化权限

用途：控制 Messages 应用

开启方法：

• 首次使用时自动请求
• 点击"好"授权

3. 通讯录访问（可选）

用途：解析联系人姓名

开启方法：

1. 系统偏好设置 → 隐私与安全性 → 通讯录
2. 添加 Terminal.app 或 OpenCode.app

🛡️ 安全机制

授权发送者

只有配置的 allowedSenders 发送的消息会被处理，其他号码的消息会被忽略。

危险命令阻止

以下模式会被自动阻止：

• rm -rf / 及其变体
• mkfs 命令
• dd if= 命令
• Fork 炸弹
• 远程脚本执行 (curl | sh)

响应格式

所有响应以 🤖｜ 开头，区分插件消息和你自己的消息。

📋 使用示例

系统状态

你：uptime
回复：🤖｜10:30  up 5 days, 12:34, 3 users, load averages: 1.23 1.45 1.56

项目部署

你：cd ~/myapp && git pull && npm run build
回复：🤖｜Already up to date.
     > [email protected] build
     > vite build
     ✓ 42 modules transformed.

日志查看

你：tail -50 ~/Library/Logs/ai.opencode.desktop/main.log
回复：🤖｜2026-02-18T10:30:00.000Z INFO Server ready...

进程管理

你：ps aux | grep node
回复：🤖｜neal  1234  0.1  1.2  123456  78901  ??  S   10:00AM   0:05.23 node server.js

🐛 故障排除

"No allowed senders configured"

添加你的手机号或 Apple ID 到 ~/.oh-my-imsg.json：

{
  "allowedSenders": ["+8613800138000"]
}

消息未接收

1. 检查权限是否授予
2. 确认 Messages 应用正在运行
3. 查看调试日志：设置 "debug": true

日志输出过多/刷屏

如果看到大量日志输出到 OpenCode 界面：

1. 关闭调试模式：设置 "debug": false（默认值）
2. 调试日志只会写入文件，不会输出到界面
3. 只有警告和错误才会显示在界面上

{
  "debug": false
}

权限被拒绝

1. 移除并重新添加完全磁盘访问
2. 重启 Terminal/OpenCode
3. 必要时重启电脑

命令超时

增加 commandTimeout：

{
  "commandTimeout": 60000
}

📊 日志功能

日志文件位置：~/.oh-my-imsg.log

# 查看日志
tail -50 ~/.oh-my-imsg.log

# 或在 OpenCode 中
/imessage-remote-logs

# 按级别过滤
/imessage-remote-logs level="error" lines=100

🔧 开发

bun install
bun run build
bun run typecheck

📜 许可证

MIT License - 详见 LICENSE

Overview

This plugin enables remote control of your OpenCode Desktop via iMessage. Send shell commands from your iPhone and receive results instantly - perfect for:

• 🏠 Home server management
• 🚀 Quick deployments on the go
• 📊 Checking system status remotely
• 🔧 Emergency troubleshooting

Features

• 🔒 Secure: Only processes messages from authorized senders
• ⚡ Efficient: Default standby mode, no resource usage when idle
• 📱 Native: Works with built-in iMessage, no third-party apps needed
• 🎯 Simple: Natural language triggers in Chinese
• 🛡️ Safe: Dangerous commands are automatically blocked
• 📋 Complete: Full command execution with output returned

Installation

Prerequisites

• macOS 12.0 or later
• OpenCode Desktop v1.2.6+
• Bun runtime
• iMessage configured with your Apple ID

Quick Install

# Install the plugin
bunx oh-my-imsg install

# Or install from GitHub
bunx github:neal/oh-my-imsg install

Manual Install

1. Clone the repository:

git clone https://github.com/neal/oh-my-imsg.git
cd oh-my-imsg
bun install
bun run build

2. Add to your OpenCode config (~/.config/opencode/opencode.jsonc):

{
  "plugin": ["oh-my-imsg"]
}

3. Copy command files:

cp -r dist/command/* ~/.config/opencode/command/

Usage

Starting Remote Control

In OpenCode Desktop, type any of these:

• i-start
• i-start
• 开始 iMessage 遥控

Or use the command:

/i-start

Stopping Remote Control

In OpenCode Desktop, type any of these:

• i-stop
• i-stop
• 关闭 iMessage 遥控

Or use the command:

/i-stop

Checking Status

/i-status

Sending Commands via iMessage

Once listening is active, send shell commands from your iPhone:

ls -la ~/Projects

You'll receive the output:

🤖｜total 32
drwxr-xr-x   8 neal  staff   256 Feb 18 10:00 .
drwxr-xr-x  35 neal  staff  1120 Feb 18 08:00 ..
...

Configuration

Edit ~/.oh-my-imsg.json:

{
  // Your phone number (with country code) or Apple ID email
  "allowedSenders": [
    "+8613800138000",
    "[email protected]"
  ],
  
  // How often to check for new messages (milliseconds)
  "pollInterval": 5000,
  
  // Maximum time for command execution (milliseconds)
  "commandTimeout": 30000,
  
  // Enable debug logging
  "debug": false,
  
  // LLM API configuration (optional, for natural language chat)
  // Supports OpenAI-compatible APIs
  "llm": {
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-xxx",
    "model": "gpt-4o-mini",
    "maxTokens": 500
  }
}

LLM API Configuration

The plugin supports any OpenAI-compatible API:

| Provider | baseURL | model example | |----------|---------|---------------| | OpenAI | https://api.openai.com/v1 | gpt-4o-mini, gpt-4o | | Claude (OpenRouter) | https://openrouter.ai/api/v1 | anthropic/claude-3-haiku | | Gemini (OpenRouter) | https://openrouter.ai/api/v1 | google/gemini-pro | | Local Ollama | http://localhost:11434/v1 | llama3, mistral |

Note: OpenCode plugin API has security restrictions that prevent using built-in models. External API is required for natural language chat. Shell commands (prefixed with $) work without LLM API.

Non-Compatible API Solutions

Some APIs (Anthropic Claude native, Google Gemini native) don't use OpenAI format. Solutions:

Option 1: Use OpenRouter (Recommended)

OpenRouter provides unified OpenAI-compatible interface:

{
  "llm": {
    "baseURL": "https://openrouter.ai/api/v1",
    "apiKey": "sk-or-xxx",
    "model": "anthropic/claude-3-haiku"
  }
}

Supported models: anthropic/claude-3-opus, google/gemini-pro, meta-llama/llama-3.1-70b-instruct

Option 2: Use Local Models

{
  "llm": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "llama3"
  }
}

Local model options: Ollama, LM Studio

Option 3: Use Proxy Services

| Service | Description | |---------|-------------| | one-api | Supports OpenAI, Claude, Gemini | | one-hub | Enhanced one-api | | New API | Supports relays and mirrors |

Per-Project Configuration

Create .oh-my-imsg.json in your project directory for project-specific settings.

Permissions

Required Permissions

1. Full Disk Access

Required for: Reading iMessage database

How to enable:

1. System Preferences → Privacy & Security → Full Disk Access
2. Click the + button
3. Add Terminal.app or OpenCode.app
4. Restart the application

2. Automation Permission

Required for: Controlling Messages app

How to enable:

• Will be requested automatically on first use
• Click "OK" when prompted

3. Contacts Access (Optional)

Required for: Resolving contact names

How to enable:

1. System Preferences → Privacy & Security → Contacts
2. Add Terminal.app or OpenCode.app

Permission Verification

Run this command to test:

osascript -e 'tell application "Messages" to get name of every chat'

If you see chat names, permissions are correctly configured.

Security

Authorized Senders

Only messages from configured allowedSenders are processed. Messages from other numbers are silently ignored.

Dangerous Commands Blocked

The following patterns are automatically blocked:

• rm -rf / and variants
• mkfs commands
• dd if= commands
• Fork bombs
• Remote script execution (curl | sh)

Response Format

All responses are prefixed with 🤖｜ to distinguish plugin messages from your own.

Example Use Cases

System Status

You: uptime
Bot: 🤖｜10:30  up 5 days, 12:34, 3 users, load averages: 1.23 1.45 1.56

Project Deployment

You: cd ~/myapp && git pull && npm run build
Bot: 🤖｜Already up to date.

> [email protected] build
> vite build

✓ 42 modules transformed.
dist/index.js  125.00 KiB

Log Checking

You: tail -50 ~/Library/Logs/ai.opencode.desktop/main.log
Bot: 🤖｜2026-02-18T10:30:00.000Z INFO Server ready...
...

Process Management

You: ps aux | grep node
Bot: 🤖｜neal  1234  0.1  1.2  123456  78901  ??  S   10:00AM   0:05.23 node server.js

Troubleshooting

"No allowed senders configured"

Add your phone number or Apple ID to ~/.oh-my-imsg.json:

{
  "allowedSenders": ["+8613800138000"]
}

Messages not being received

1. Check permissions are granted
2. Verify Messages app is running
3. Check debug logs: set "debug": true in config

Permission denied errors

1. Remove and re-add Full Disk Access
2. Restart Terminal/OpenCode
3. Reboot if necessary

Commands timing out

Increase commandTimeout in config:

{
  "commandTimeout": 60000
}

Development

Build

bun install
bun run build

Type Check

bun run typecheck

Local Testing

Add to your OpenCode config:

{
  "plugin": ["file:///path/to/oh-my-imsg"]
}

API Reference

Tools Provided

| Tool | Description | |------|-------------| | i-start | Start listening for remote commands | | i-stop | Stop listening | | i-status | Check current status | | imessage-remote-config | Update configuration | | imessage-remote-test-send | Test sending a message | | imessage-remote-logs | View plugin logs for debugging | | imessage-remote-clear-logs | Clear log file | | imessage-remote-debug | Enable/disable debug mode |

Logging

The plugin writes logs to ~/.oh-my-imsg.log for debugging.

View logs:

# In OpenCode
imessage-remote-logs

# Or directly
tail -50 ~/.oh-my-imsg.log

Enable debug mode:

imessage-remote-debug enabled=true

Filter by log level:

imessage-remote-logs level="error" lines=100

Log levels:

• INFO - General information
• WARN - Warnings
• ERROR - Errors
• DEBUG - Detailed debug info (requires debug mode)

Events Hooked

| Event | Description | |-------|-------------| | chat.message | Detect trigger keywords | | event | Handle session events |

License

MIT License - see LICENSE for details.

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Acknowledgments

• OpenCode Team for the excellent plugin API
• Apple for AppleScript and Messages automation

Made with ❤️ for the OpenCode community