docs: http_request tool broken by three zero-value config defaults

[walterpembery]

Summary

• Problem: The http_request tool fails silently in multiple independent ways when config values are left at their default zero values
• Why it matters: Each failure looks like a different error type, making diagnosis difficult. Users can spend significant time debugging what is ultimately three config values that need non-zero defaults
• What changed: Added a ## Docker Deployment section to docs/troubleshooting.md documenting all three issues
• What did not change: No code changes; docs-only

The Three Bugs

When enabling [http_request] in config.toml, three separate config values all default to zero, each independently breaking the tool in a different way:

1. Empty allowed_domains = []

Contrary to what you might expect, an empty allowlist does not mean "allow all" — it means http_request immediately errors with:

HTTP request tool is enabled but no allowed_domains are configured

Fix: Add domains explicitly, e.g.:

allowed_domains = [github.com, api.github.com, en.wikipedia.org]

2. timeout_secs = 0 → every request fails immediately

A zero timeout causes every outbound request to fail at the transport layer before any data is exchanged. Error looks like a network failure.

Fix:

timeout_secs = 30

3. max_response_size = 0 → all responses silently discarded

A zero max response size causes every response to be truncated to zero bytes. The request succeeds, but the tool returns an empty string. No error is surfaced.

Fix:

max_response_size = 524288  # 512KB, adjust to taste

Full working [http_request] config

[http_request]
enabled = true
allowed_domains = ["github.com", "api.github.com", "en.wikipedia.org"]
max_response_size = 524288
timeout_secs = 30

Label Snapshot (required)

• Risk label: risk: low
• Size label: size: XS
• Scope labels: docs
• Module labels: tool: http_request

Change Metadata

• Change type: docs
• Primary scope: docs

Linked Issue

• Related: N/A (issues disabled on repo)

Validation Evidence (required)

All three bugs reproduced and verified on macOS (arm64), native launchd deployment, ZeroClaw 0.1.0:

• Empty allowlist: confirmed error message
• timeout_secs = 0: confirmed immediate transport failure
• max_response_size = 0: confirmed empty response, tool returned empty string; setting to 524288 resolved

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No

Privacy and Data Hygiene (required)

• Data-hygiene status: pass

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No — docs only
• Migration needed? No

Human Verification (required)

• Verified: all three bugs reproduced individually and fixed; http_request confirmed working end-to-end after all three fixes applied
• What was not verified: whether these defaults differ by platform or install method

Side Effects / Blast Radius (required)

• Docs only

Rollback Plan (required)

• Revert the docs change; no production config changes in this PR

Risks and Mitigations

• Risk: Default values may differ by install method (Docker vs native vs bootstrap script) — the three zeros may not apply universally
  • Mitigation: PR body is descriptive rather than prescriptive; treat as a diagnosis guide

[github-actions]

Thanks for contributing to ZeroClaw.

For faster review, please ensure:

• PR template sections are fully completed
• cargo fmt --all -- --check, cargo clippy --all-targets -- -D warnings, and cargo test are included
• If automation/agents were used heavily, add brief workflow notes
• Scope is focused (prefer one concern per PR)

See CONTRIBUTING.md and docs/pr-workflow.md for full collaboration rules.

[github-actions]

PR intake checks found warnings (non-blocking)

Fast safe checks found advisory issues. CI lint/test/build gates still enforce merge quality.

• Incomplete required PR template fields: validation commands, security risk/mitigation, privacy status, rollback plan

Action items:

1. Complete required PR template sections/fields.
2. Remove tabs, trailing whitespace, and merge conflict markers from added lines.
3. Re-run local checks before pushing:
   • ./scripts/ci/rust_quality_gate.sh
   • ./scripts/ci/rust_strict_delta_gate.sh
   • ./scripts/ci/docs_quality_gate.sh

Run logs: https://github.com/openagen/zeroclaw/actions/runs/22529266994

Detected blocking line issues (sample):

• none

Detected advisory line issues (sample):

• none

[github-actions]

Hi @walterpembery, friendly automation nudge from PR hygiene.

This PR has had no new commits for 180h and still needs an update before merge:

• No CI Required Gate run was found for the current head commit.

Recommended next steps

1. Rebase your branch on main.
2. Push the updated branch and re-run checks (or use Re-run failed jobs).
3. Post fresh validation output in this PR thread.

Maintainers: apply no-stale to opt out for accepted-but-blocked work.
Head SHA: 6a321f1044d8