使用说明

Claude远程代理

MCP（模型上下文协议）服务器，使Claude CLI能够通过SSH实时与远程Linux、macOS和Windows系统交互。

隐私和凭证安全

您的凭据永远不会离开您的计算机。

此MCP服务器完全在您的本地计算机上运行，并使用标准SSH直接连接到您的远程主机：

仅限本地存储：所有配置、凭据和SSH密钥都存储在本地 ~/.config/claude-remote-agent/ 和 ~/.ssh/
无第三方共享：您的密码、SSH密钥和主机凭据永远不会发送给Anthropic、Claude或任何外部服务
标准SSH：使用您现有的SSH基础架构-与您使用的密钥和配置相同 ssh 命令
SSH代理支持：可以用你的跑步 ssh-agent 所以私钥永远不会在未加密的情况下接触磁盘
直接连接：SSH连接直接从您的计算机连接到远程主机，无需代理或中继服务器

它是如何工作的：

Your Machine                          Remote Hosts
┌─────────────────────┐               ┌─────────────┐
│ Claude CLI          │               │ my-server   │
│   ↓                 │    SSH        │             │
│ MCP Server (local)  │──────────────→│ (your host) │
│   ↓                 │   Direct      │             │
│ ~/.ssh/id_ed25519   │  Connection   └─────────────┘
│ ~/.config/cra/      │
└─────────────────────┘

克劳德只看到结果命令（stdout/stderr），而不是SSH密钥或密码。

需求

本地计算机（运行Claude CLI的地方）

要求	版本	注释
Node.js	18.0+	运行MCP服务器所需
npm	8.0+	附带Node.js
Claude CLI	最新版本	通过安装 `npm install -g @anthropic-ai/claude-code`
SSH客户端	任何	OpenSSH（包括在macOS/Linux上），Windows 10+内置
SSH密钥	-	建议用于无密码身份验证

远程主机

要求	注意事项
SSH服务器	OpenSSH或兼容，侦听端口22（或自定义端口）
用户帐户	具有预期操作的适当权限
Shell	bash、sh、zsh或PowerShell（Windows）

Windows远程主机：

必须启用OpenSSH服务器（设置>应用程序>可选功能>OpenSSH服务器）
或者通过PowerShell（管理员）： Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
启动服务： Start-Service sshd; Set-Service -Name sshd -StartupType Automatic

安装

步骤1：安装代理

Linux/macOS：

# Clone the repository
git clone https://github.com/haxorthematrix/claude-remote-agent
cd claude-remote-agent

# Install dependencies and build
npm install
npm run build

# Link globally (makes 'claude-remote-agent' command available)
npm link

# Initialize configuration
claude-remote-agent init

Windows（PowerShell）：

# Install Node.js if needed (pick one)
winget install OpenJS.NodeJS.LTS
# or: choco install nodejs-lts -y
# or: scoop install nodejs-lts

# Clone and build
git clone https://github.com/haxorthematrix/claude-remote-agent
cd claude-remote-agent
npm install
npm run build

# Link globally
npm link

# Initialize configuration
claude-remote-agent init

步骤2：在Claude CLI注册

claude mcp add remote-agent -- claude-remote-agent serve

这将在Claude CLI中注册MCP服务器。当克劳德需要时，服务器会自动启动。

步骤3：配置远程主机

编辑 ~/.config/claude-remote-agent/hosts.yaml:

hosts:
  my-server:
    hostname: 192.168.1.100
    port: 22
    user: myuser
    auth:
      type: key                    # Options: key, password, agent
      key_path: ~/.ssh/id_ed25519  # For type: key
    policy:
      confirmation_required: destructive_only  # Options: never, destructive_only, always

或者从现有SSH配置导入：

# View your SSH aliases
claude-remote-agent alias list

# Then add them to hosts.yaml manually, or use the CLI
claude-remote-agent add-host my-server -H 192.168.1.100 -u myuser -i ~/.ssh/id_ed25519

步骤4：测试连接

claude-remote-agent test my-server

身份验证方法

类型	配置	描述
`key`	`key_path: ~/.ssh/id_ed25519`	SSH私钥（推荐）
`agent`	（无需额外配置）	使用正在运行的SSH代理（SSH代理）
`password`	`password: secret`	密码验证（不推荐，以纯文本存储）

SSH代理示例：

hosts:
  my-server:
    hostname: 192.168.1.100
    user: myuser
    auth:
      type: agent  # Uses SSH_AUTH_SOCK

特性

核心能力

SSH命令执行：直接从Claude在远程主机上运行命令
文件操作：通过SFTP在远程系统上读取、写入和编辑文件
文件传输：在本地和远程主机之间上传和下载文件
会话管理：维护多命令工作流的有状态shell会话
主机组：同时跨多个主机执行命令

连接性

多平台支持：Linux、macOS和Windows远程主机
代理跳转/堡垒主机：通过跳转服务器连接以实现安全的网络访问
连接池：高效的连接重用，实现快速操作
SSH别名管理：通过MCP工具创建和管理~/.ssh/config条目

安全

每台主机的安全策略：可配置的确认级别和命令过滤
命令允许列表/阻止列表：对允许的命令进行细粒度控制
危险指令检测：自动检测破坏性操作
输出消毒：日志中机密（密码、API密钥、令牌）的自动编校
审计日志：通过会话关联全面跟踪所有操作

MCP工具（共21个）

工具	说明
`remote_execute`	在远程主机上执行命令
`remote_file_read`	从远程主机读取文件内容
`remote_file_write`	将内容写入远程主机上的文件
`remote_file_edit`	使用查找/替换功能编辑现有文件
`remote_upload`	将本地文件上传到远程主机
`remote_download`	从远程主机下载文件
`remote_session_start`	启动持久shell会话
`remote_session_execute`	在现有会话中运行命令
`remote_session_end`	关闭会话
`remote_session_list`	列出活动会话
`remote_list_hosts`	列出已配置的主机和组
`remote_host_info`	获取主机配置详细信息
`remote_detect_system`	检测操作系统和系统功能
`remote_install_agent`	在远程主机上安装代理
`remote_check_policy`	检查命令是否被允许
`ssh_alias_list`	列出SSH配置别名
`ssh_alias_add`	添加SSH配置条目
`ssh_alias_remove`	删除SSH配置条目
`config_reload`	从磁盘重新加载配置
`audit_log_query`	查询审核日志
`remote_permissions_status`	检查跳过权限模式

用法示例

配置后，自然地与Claude交谈：

You: Check disk space on my-server
Claude: [Uses remote_execute] Here's the disk usage on my-server:
        /dev/sda1: 45% used (23GB free)

You: List all running docker containers on my-server
Claude: [Uses remote_execute with 'docker ps']
        CONTAINER ID   IMAGE          STATUS
        a1b2c3d4       nginx:latest   Up 2 days
        ...

You: Read the nginx config on my-server
Claude: [Uses remote_file_read] Here's /etc/nginx/nginx.conf:
        ...

You: Restart nginx on my-server
Claude: This will restart nginx. Proceed? [Confirms with user]
        [Uses remote_execute] nginx restarted successfully.

CLI参考

# MCP Server
claude-remote-agent serve              # Start MCP server (used by Claude CLI)

# Configuration
claude-remote-agent init               # Initialize config directory
claude-remote-agent list               # List configured hosts

# Connection Testing
claude-remote-agent test <host>        # Test SSH connection to a host

# Policy Checking
claude-remote-agent check-policy <host> "<command>"

# SSH Alias Management
claude-remote-agent alias list
claude-remote-agent alias add <name> -H <hostname> -u <user> [-p <port>] [-i <keyfile>]
claude-remote-agent alias remove <name>

# Add Host (creates SSH alias + agent config)
claude-remote-agent add-host <name> -H <hostname> -u <user> [options]

配置参考

主机配置(`~/.config/claude-remote-agent/hosts.yaml`)

hosts:
  # Basic host
  my-server:
    hostname: 192.168.1.100
    port: 22                          # Optional, default: 22
    user: myuser
    auth:
      type: key
      key_path: ~/.ssh/id_ed25519
    policy:
      confirmation_required: destructive_only
    labels:                           # Optional metadata
      environment: production
      role: webserver

  # Host via bastion/jump server
  internal-db:
    hostname: 10.0.0.50
    user: dbadmin
    auth:
      type: key
      key_path: ~/.ssh/id_ed25519
    proxy_jump: bastion               # Name of another host to jump through

  # Bastion host
  bastion:
    hostname: bastion.example.com
    user: jump-user
    auth:
      type: key
      key_path: ~/.ssh/bastion_key

# Host groups for batch operations
groups:
  web-servers:
    - my-server
    - web-2
  databases:
    - internal-db

全局配置(`~/.config/claude-remote-agent/config.yaml`)

global:
  default_timeout: 300                # Command timeout in seconds

  connection_pool:
    max_connections_per_host: 5
    idle_timeout: 600
    keepalive_interval: 30

  audit:
    enabled: true
    log_path: ~/.config/claude-remote-agent/audit.log
    log_commands: true
    log_output: true
    max_output_logged: 10000

  default_policy:
    confirmation_required: destructive_only
    blocked_commands:
      - "rm -rf /"
      - "mkfs.*"
    blocked_patterns:
      - "chmod -R 777 /"

安全策略

级别	行为
`never`	无需确认（用于受信任的开发环境）
`destructive_only`	仅对rm、kill、reboot等进行确认。（推荐）
`write_only`	确认任何写入/修改操作
`always`	确认每个命令（用于生产）

危险命令（自动检测）

Linux/macOS： rm、rmdir、kill、killall、pkill、关机、重启、暂停、断电、systemctl停止/重启、docker rm/stop

窗户： del、rd、rmdir、format、taskkill、停止进程、停止服务、关机、重新启动计算机

审计日志

所有操作都记录到 ~/.config/claude-remote-agent/audit.log:

{
  "timestamp": "2024-01-15T10:30:45Z",
  "session_id": "session-abc123",
  "tool": "remote_execute",
  "host": "my-server",
  "user": "myuser",
  "action": "systemctl status nginx",
  "exit_code": 0,
  "duration_ms": 245,
  "success": true
}

自动密码重置： 密码、API密钥、令牌、私钥、AWS凭据和其他机密会在日志中自动编辑。

故障排除

“连接被拒绝”或“连接超时”

验证主机是否可访问： ping <hostname>
检查SSH是否在远程主机上运行： ssh <user>@<hostname>
验证端口是否正确（默认值：22）

“身份验证失败”

检查用户名是否正确
对于密钥认证：验证密钥路径和权限(chmod 600 ~/.ssh/id_*)
对于代理身份验证：验证ssh代理是否正在运行(ssh-add -l)
手动测试： ssh -i <keyfile> <user>@<hostname>

“找不到命令：claude远程代理”

跑 npm link 在项目目录中
或者使用完整路径： node /path/to/claude-remote-agent/dist/cli.js

MCP服务器没有响应

检查Claude CLI配置： cat ~/.claude.json
验证服务器是否启动： claude-remote-agent serve （应等待输入）
检查构建中的错误： npm run build

远程主机上的权限被拒绝

检查用户是否具有所需权限
对于sudo命令，请确保用户在sudoers中
检查安全策略是否阻止该命令： claude-remote-agent check-policy <host> "<command>"

支持的平台

远程操作系统	包管理器	服务管理器
Ubuntu/Debian	apt	systemd
RHEL/Cents/Fedora	dnf/yum	systemd
Arch Linux	pacman	systemd
Alpine Linux	apk	systemd
macOS	Homebrew	launchd
Windows 10/11	winget，choco，独家新闻	Windows服务

文档

看规格.md 完整规格包括：

建筑细部
所有MCP工具模式
配置选项
安全模型
未来路线图

许可证

麻省理工学院