Claude Remote Agent

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的地方）

远程主机

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

身份验证方法

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个）

用法示例

配置后，自然地与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         # Test SSH connection to a host

# Policy Checking
claude-remote-agent check-policy  ""

# SSH Alias Management
claude-remote-agent alias list
claude-remote-agent alias add  -H  -u  [-p 
] [-i ]
claude-remote-agent alias remove 

# Add Host (creates SSH alias + agent config)
claude-remote-agent add-host  -H  -u  [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 /"

安全策略

危险命令（自动检测）

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
• 检查SSH是否在远程主机上运行： ssh @
• 验证端口是否正确（默认值：22）

“身份验证失败”

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

“找不到命令：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 ""

支持的平台

文档

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

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

许可证

麻省理工学院