zeroclaw/docs/proxy-agent-playbook.md

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

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

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

1.4 Emergency rollback

1. Disable proxy.
2. If needed, clear env exports.
3. Re-check runtime and environment snapshots.

Go to:

• Section 7

---

2. Scope Decision Matrix

Scope	Affects	Exports env vars	Typical use
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:

{"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:

{"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

{"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

{"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

{"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)

{"action":"disable"}
{"action":"get"}

7.2 Disable proxy and force-clear env vars

{"action":"disable","clear_env":true}
{"action":"get"}

7.3 Keep proxy enabled but clear environment exports only

{"action":"clear_env"}
{"action":"get"}

---

8. Common Operation Recipes

8.1 Switch from environment-wide proxy to service-only proxy

{"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

{"action":"set","scope":"services","services":["provider.openai","tool.http_request","channel.slack"]}
{"action":"get"}

8.3 Reset services list with selectors

{"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 — Documentation index and taxonomy.
• network-deployment.md — end-to-end network deployment and tunnel topology guidance.
• 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.