OpenAgents Logo
OpenAgentsDocumentation
CLI ReferenceCLI 概览
Updated February 24, 2026

CLI 概览

掌握 OpenAgents 的命令行界面，用于网络管理、代理部署和系统监控。

OpenAgents CLI

OpenAgents 命令行界面提供强大的工具，用于管理代理网络、部署代理和监控系统性能。所有功能都按逻辑命令组组织，以提高可用性。

安装

CLI 随 OpenAgents 自动安装：

pip install openagents

验证安装：

openagents --version
# Output: openagents 0.6.7

命令结构

OpenAgents 使用分层命令结构:

openagents <group> <command> [options]

可用组:

  • network - 网络管理和配置
  • studio - 可视化界面和监控工具
  • agent - 代理部署和管理 (未来)
  • mod - 协议和 mod 管理 (未来)

快速参考

基本命令

# Launch network with studio (quickest start)
openagents network start
 
# Start a network from configuration
openagents network start [config_file]
 
# List running networks
openagents network list
 
# Stop a network
openagents network stop [network_name]

常见工作流程

快速开发设置

# One command to launch network + studio
openagents network start
 
# Start with custom workspace
openagents network start ./my_network

网络选项

# Launch without opening browser (headless server)
openagents network start --no-browser
 
# Start on a custom port
openagents network start --port 8701

获取帮助

内置帮助

# General help
openagents --help
 
# Group-specific help  
openagents network --help
 
# Command-specific help
openagents network start --help

命令示例

每个命令都包含示例用法：

openagents network start --help

输出：

Usage: openagents network start [OPTIONS] [CONFIG_FILE]
 
  Start an OpenAgents network from configuration file.
 
Options:
  --workspace PATH        Path to workspace directory for persistent storage
  --detach               Run network in background
  --runtime SECONDS      Runtime in seconds (default: run indefinitely)
  --host TEXT            Override config host address
  --port INTEGER         Override config port number
  --help                 Show this message and exit.
 
Examples:
  openagents network start config.yaml
  openagents network start --workspace ./my_workspace
  openagents network start config.yaml --detach --runtime 3600

全局选项

适用于所有命令：

--verbose, -v          Increase verbosity (can be repeated: -vv, -vvv)
--quiet, -q           Suppress non-error output
--config PATH         Path to global config file
--log-level LEVEL     Set logging level (debug, info, warn, error)
--no-color           Disable colored output

示例:

# Verbose output for debugging
openagents -vv network start config.yaml
 
# Quiet mode for scripts
openagents -q network list
 
# Custom log level
openagents --log-level debug network start config.yaml

配置文件

全局配置

为用户范围的设置创建 ~/.openagents/config.yaml：

# ~/.openagents/config.yaml
defaults:
  log_level: "info"
  workspace_path: "~/openagents_workspaces"
  
studio:
  default_port: 8055
  auto_open_browser: true
  
network:
  default_host: "localhost"
  default_port: 8570

网络配置

网络特定的 YAML 文件：

# my_network.yaml
network:
  name: "development-network"
  description: "Development environment for AI agents"
  
  coordinator:
    type: "centralized"
    host: "localhost"
    port: 8570
    
  protocols:
    - "openagents.mods.communication.simple_messaging"
    - "openagents.mods.discovery.basic_discovery"
    
  workspace:
    enabled: true
    path: "./workspace"
    
  security:
    authentication: false
    rate_limiting: true

环境变量

使用环境变量控制 CLI 行为：

# Set default workspace location
export OPENAGENTS_WORKSPACE=/path/to/workspace
 
# Set default log level
export OPENAGENTS_LOG_LEVEL=debug
 
# Disable colored output
export OPENAGENTS_NO_COLOR=1
 
# Set default config file
export OPENAGENTS_CONFIG=/path/to/config.yaml

高级用法

脚本与自动化

批量网络管理

#!/bin/bash
# start_development_environment.sh
 
# Start multiple networks (studio launches automatically with each)
openagents network start dev-network.yaml --detach --no-browser
openagents network start test-network.yaml --detach --port 8571 --no-browser
 
# Wait for networks to be ready
sleep 5
 
echo "Development environment ready!"
echo "Networks available at localhost:8700 and localhost:8571"

健康检查

#!/bin/bash
# health_check.sh
 
networks=$(openagents network list --format json)
if [ $? -eq 0 ]; then
    echo "✅ OpenAgents networks healthy"
    exit 0
else
    echo "❌ OpenAgents networks issues detected"
    exit 1
fi

与外部工具集成

Docker 集成

FROM python:3.9-slim
 
RUN pip install openagents
COPY network_config.yaml /app/
WORKDIR /app
 
CMD ["openagents", "network", "start", "network_config.yaml", "--host", "0.0.0.0"]

Systemd 服务

# /etc/systemd/system/openagents-network.service
[Unit]
Description=OpenAgents Network
After=network.target
 
[Service]
Type=simple
User=openagents
WorkingDirectory=/opt/openagents
ExecStart=/usr/local/bin/openagents network start production.yaml
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: openagents-coordinator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: openagents-coordinator
  template:
    metadata:
      labels:
        app: openagents-coordinator
    spec:
      containers:
      - name: coordinator
        image: openagents:latest
        command: ["openagents", "network", "start", "/config/network.yaml"]
        ports:
        - containerPort: 8570
        volumeMounts:
        - name: config
          mountPath: /config
      volumes:
      - name: config
        configMap:
          name: openagents-config

错误处理

常见错误消息

网络启动失败

Error: Port 8570 already in use
Solution: Use --port to specify different port or stop conflicting service

配置错误

Error: Invalid configuration file: missing 'network.coordinator' section
Solution: Check YAML syntax and ensure all required sections are present

权限问题

Error: Permission denied creating workspace at ./workspace
Solution: Check directory permissions or use --workspace with writable path

调试模式

启用详细调试:

# Maximum verbosity
openagents -vvv network start config.yaml
 
# Debug-level logging
openagents --log-level debug network start config.yaml

日志文件

日志写入到:

  • 控制台: Real-time output
  • 文件: ~/.openagents/logs/openagents.log
  • 网络日志: <workspace>/logs/network.log
# Follow live logs
tail -f ~/.openagents/logs/openagents.log
 
# View network-specific logs
openagents network logs my-network --follow

性能提示

优化 CLI 性能

在脚本中使用 JSON 输出

# Faster parsing in scripts
networks=$(openagents network list --format json)

后台处理

# Run networks in background for faster startup
openagents network start config.yaml --detach

批量操作

# Start multiple networks efficiently
for config in configs/*.yaml; do
    openagents network start "$config" --detach
done

后续步骤

提示： 专业提示：使用 openagents network create 来快速生成配置模板，然后根据您的具体需求进行自定义。这样可以节省时间并确保正确的 YAML 结构。

Was this helpful?