PhyAgentOS — Configuration

Config File Location

~/.PhyAgentOS/config.json is the default configuration file, created automatically by paos onboard.

CLI flags→ config.json→ Built-in defaults

Priority order: CLI flags always override config file values, which override built-in defaults.

Custom config path: Set the PAOS_CONFIG environment variable to point to a different config file. export PAOS_CONFIG=/path/to/my_config.json

`agents.defaults`

Default agent settings: model selection, workspace path, conversation limits, and generation temperature.

"agents": {
  "defaults": {
    "model": "openrouter/openai/gpt-4o-mini",
    "workspace": "~/.PhyAgentOS/workspace",
    "max_turns": 50,
    "temperature": 0.7
  }
}

Key	Type	Description
`model`	string	LLM model identifier in `provider/model-name` format. Examples: `openrouter/openai/gpt-4o-mini`, `openai/gpt-4o`, `azure/gpt-4`
`workspace`	string	Default workspace directory path. `~` is expanded to the home directory.
`max_turns`	int	Maximum number of Planner-Critic loops per task. Acts as a safety limit to prevent infinite loops.
`temperature`	float	LLM sampling temperature (0.0–2.0). Lower = more deterministic, higher = more creative.

`providers`

Configure LLM API providers. At least one provider must be configured for the agent to function.

OpenRouter

"providers": {
  "openrouter": {
    "api_key": "sk-or-v1-..."
  }
}

OpenAI

"providers": {
  "openai": {
    "api_key": "sk-..."
  }
}

Azure

"providers": {
  "azure": {
    "api_key": "...",
    "api_base": "https://your-resource.openai.azure.com",
    "api_version": "2024-02-15-preview"
  }
}

Custom (OpenAI-compatible)

"providers": {
  "custom": {
    "api_key": "...",
    "api_base": "https://your-llm-service.example.com/v1"
  }
}

Required Keys

Every provider needs an api_key. Custom providers also require api_base — the URL of your OpenAI-compatible endpoint.

Multiple Providers

You can configure multiple providers simultaneously. The agent uses the provider matching the model prefix (e.g., openrouter/ → openrouter config).

`tools`

Enable or disable individual built-in tools that the agent can invoke. Disable unused tools to reduce the model's decision space.

"tools": {
  "execute_robot_action": true,
  "target_navigation": true,
  "read_file": true,
  "write_file": true,
  "check_workspace": true,
  "update_task": true,
  "search_lessons": true,
  "get_time": true
}

Tool	Description
`execute_robot_action`	Dispatch an action to `ACTION.md` for the watchdog to execute
`target_navigation`	Navigate to a visual target using perception feedback
`read_file`	Read any workspace file (ENVIRONMENT.md, TASK.md, etc.)
`write_file`	Write or update workspace files
`check_workspace`	List all files in the workspace and their last-modified timestamps
`update_task`	Update task status and sub-task progress in TASK.md
`search_lessons`	Search LESSONS.md for past failure patterns
`get_time`	Get the current system time for timestamped actions

Security note: Tools operate within the workspace boundary. The agent cannot read or write files outside the configured workspace directory.

`embodiments`

Configure robot deployment mode. Single mode runs one robot; Fleet mode coordinates multiple robots with shared state.

Single Mode

"embodiments": {
  "mode": "single"
}

Single mode needs nothing else. The default workspace handles one robot. Start the watchdog with one --driver flag.

Fleet Mode

"embodiments": {
  "mode": "fleet",
  "shared_workspace": "/tmp/paos_fleet/shared",
  "instances": [
    {
      "robot_id": "go2_edu_001",
      "driver": "go2_edu",
      "workspace": "/tmp/paos_fleet/robot_a"
    },
    {
      "robot_id": "franka_001",
      "driver": "rekep_real",
      "workspace": "/tmp/paos_fleet/robot_b"
    }
  ]
}

Key	Type	Description
`mode`	string	`"single"` for one robot; `"fleet"` for multi-robot coordination
`shared_workspace`	string	Fleet only. Path to the shared workspace holding global ENVIRONMENT.md, TASK.md, ORCHESTRATOR.md, and LESSONS.md
`instances`	array	Fleet only. Array of robot instances, each with `robot_id`, `driver`, and `workspace`
`instances[].robot_id`	string	Unique identifier for this robot. Used to route actions and track state
`instances[].driver`	string	Driver name to use for this robot instance
`instances[].workspace`	string	Per-robot workspace path for ACTION.md and EMBODIED.md

`channels`

Configure external messaging channels for the gateway service. Each channel enables remote interaction with the agent.

Telegram

"channels": {
  "telegram": {
    "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "chat_id": "-1001234567890"
  }
}

Slack

"channels": {
  "slack": {
    "bot_token": "xoxb-...",
    "channel": "#robot-control"
  }
}

Feishu (Lark)

"channels": {
  "feishu": {
    "app_id": "cli_a...",
    "app_secret": "..."
  }
}

Channel	Required Keys	Notes
`telegram`	`bot_token`, `chat_id`	Get your bot token from @BotFather
`slack`	`bot_token`, `channel`	Create a Slack app at api.slack.com/apps
`feishu`	`app_id`, `app_secret`	Create a Feishu bot in the Feishu Open Platform

`gateway`

Configure the gateway service parameters: HTTP listen address, port, and API request timeout.

"gateway": {
  "port": 8080,
  "host": "0.0.0.0",
  "request_timeout": 30
}

Key	Type	Default	Description
`port`	int	8080	HTTP server listen port
`host`	string	0.0.0.0	HTTP server bind address. Use `127.0.0.1` for local-only access
`request_timeout`	int	30	Maximum time in seconds to wait for an LLM API response

Minimal Config Templates

Copy-paste starting points. Replace placeholder values with your actual keys and paths.

Single Mode (Minimal)

{
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-4o-mini",
      "workspace": "~/.PhyAgentOS/workspace",
      "max_turns": 50
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "YOUR_OPENROUTER_API_KEY"
    }
  },
  "tools": {
    "execute_robot_action": true,
    "read_file": true,
    "write_file": true,
    "check_workspace": true
  },
  "embodiments": {
    "mode": "single"
  }
}

Fleet Mode (Minimal)

{
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-4o-mini",
      "workspace": "/tmp/paos_fleet/shared",
      "max_turns": 50
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "YOUR_OPENROUTER_API_KEY"
    }
  },
  "tools": {
    "execute_robot_action": true,
    "read_file": true,
    "write_file": true,
    "check_workspace": true
  },
  "embodiments": {
    "mode": "fleet",
    "shared_workspace": "/tmp/paos_fleet/shared",
    "instances": [
      {
        "robot_id": "go2_edu_001",
        "driver": "go2_edu",
        "workspace": "/tmp/paos_fleet/robot_a"
      },
      {
        "robot_id": "franka_001",
        "driver": "rekep_real",
        "workspace": "/tmp/paos_fleet/robot_b"
      }
    ]
  }
}