# Proxy Agent Playbook
This playbook provides copy-paste tool calls for configuring proxy behavior via `proxy_config`.
Use this document when you want the agent to switch proxy scope quickly and safely.
## 0. Summary
- **Purpose:** provide copy-ready agent tool calls for proxy scope management and rollback.
- **Audience:** operators and maintainers running ZeroClaw in proxied networks.
- **Scope:** `proxy_config` actions, mode selection, verification flow, and troubleshooting.
- **Non-goals:** generic network debugging outside ZeroClaw runtime behavior.
---
## 1. Fast Path by Intent
Use this section for quick operational routing.
### 1.1 Proxy only ZeroClaw internal traffic
1. Use scope `zeroclaw`.
2. Set `http_proxy`/`https_proxy` or `all_proxy`.
3. Validate with `{"action":"get"}`.
Go to:
- [Section 4](#4-mode-a--proxy-only-for-zeroclaw-internals)
### 1.2 Proxy only selected services
1. Use scope `services`.
2. Set concrete keys or wildcard selectors in `services`.
3. Validate coverage using `{"action":"list_services"}`.
Go to:
- [Section 5](#5-mode-b--proxy-only-for-specific-services)
### 1.3 Export process-wide proxy environment variables
1. Use scope `environment`.
2. Apply with `{"action":"apply_env"}`.
3. Verify env snapshot via `{"action":"get"}`.
Go to:
- [Section 6](#6-mode-c--proxy-for-full-process-environment)
### 1.4 Emergency rollback
1. Disable proxy.
2. If needed, clear env exports.
3. Re-check runtime and environment snapshots.
Go to:
- [Section 7](#7-disable--rollback-patterns)
---
## 2. Scope Decision Matrix
| `zeroclaw` | ZeroClaw internal HTTP clients | No | Normal runtime proxying without process-level side effects |
| `services` | Only selected service keys/selectors | No | Fine-grained routing for specific providers/tools/channels |
| `environment` | Runtime + process environment proxy variables | Yes | Integrations that require `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` |
---
## 3. Standard Safe Workflow
Use this sequence for every proxy change:
1. Inspect current state.
2. Discover valid service keys/selectors.
3. Apply target scope configuration.
4. Verify runtime and environment snapshots.
5. Roll back if behavior is not expected.
Tool calls:
```json
{"action":"get"}
{"action":"list_services"}
```
---
## 4. Mode A — Proxy Only for ZeroClaw Internals
Use when ZeroClaw provider/channel/tool HTTP traffic should use proxy, without exporting process-level proxy env vars.
Tool calls:
```json
{"action":"set","enabled":true,"scope":"zeroclaw","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":["localhost","127.0.0.1"]}
{"action":"get"}
```
Expected behavior:
- Runtime proxy is active for ZeroClaw HTTP clients.
- `HTTP_PROXY` / `HTTPS_PROXY` process env exports are not required.
---
## 5. Mode B — Proxy Only for Specific Services
Use when only part of the system should use proxy (for example specific providers/tools/channels).
### 5.1 Target specific services
```json
{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request","channel.telegram"],"all_proxy":"socks5h://127.0.0.1:1080","no_proxy":["localhost","127.0.0.1",".internal"]}
{"action":"get"}
```
### 5.2 Target by selectors
```json
{"action":"set","enabled":true,"scope":"services","services":["provider.*","tool.*"],"http_proxy":"http://127.0.0.1:7890"}
{"action":"get"}
```
Expected behavior:
- Only matched services use proxy.
- Unmatched services bypass proxy.
---
## 6. Mode C — Proxy for Full Process Environment
Use when you intentionally need exported process env vars (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) for runtime integrations.
### 6.1 Configure and apply environment scope
```json
{"action":"set","enabled":true,"scope":"environment","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":"localhost,127.0.0.1,.internal"}
{"action":"apply_env"}
{"action":"get"}
```
Expected behavior:
- Runtime proxy is active.
- Environment variables are exported for the process.
---
## 7. Disable / Rollback Patterns
### 7.1 Disable proxy (default safe behavior)
```json
{"action":"disable"}
{"action":"get"}
```
### 7.2 Disable proxy and force-clear env vars
```json
{"action":"disable","clear_env":true}
{"action":"get"}
```
### 7.3 Keep proxy enabled but clear environment exports only
```json
{"action":"clear_env"}
{"action":"get"}
```
---
## 8. Common Operation Recipes
### 8.1 Switch from environment-wide proxy to service-only proxy
```json
{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request"],"all_proxy":"socks5://127.0.0.1:1080"}
{"action":"get"}
```
### 8.2 Add one more proxied service
```json
{"action":"set","scope":"services","services":["provider.openai","tool.http_request","channel.slack"]}
{"action":"get"}
```
### 8.3 Reset `services` list with selectors
```json
{"action":"set","scope":"services","services":["provider.*","channel.telegram"]}
{"action":"get"}
```
---
## 9. Troubleshooting
- Error: `proxy.scope='services' requires a non-empty proxy.services list`
- Fix: set at least one concrete service key or selector.
- Error: invalid proxy URL scheme
- Allowed schemes: `http`, `https`, `socks5`, `socks5h`.
- Proxy does not apply as expected
- Run `{"action":"list_services"}` and verify service names/selectors.
- Run `{"action":"get"}` and check `runtime_proxy` and `environment` snapshot values.
---
## 10. Related Docs
- [README.md](./README.md) — Documentation index and taxonomy.
- [network-deployment.md](./network-deployment.md) — end-to-end network deployment and tunnel topology guidance.
- [resource-limits.md](./resource-limits.md) — runtime safety limits for network/tool execution contexts.
---
## 11. Maintenance Notes
- **Owner:** runtime and tooling maintainers.
- **Update trigger:** new `proxy_config` actions, proxy scope semantics, or supported service selector changes.
- **Last reviewed:** 2026-02-18.
