[hieptl]

HUMAN:

I verified the changes.

---

AGENT:

Why

The openhands-automation skill tells custom scripts to read secrets with a get_secret() helper that only uses AGENT_SERVER_URL. The automation service sets that variable in local mode only (backends/local.py). OpenHands Cloud and Enterprise run the service in cloud mode, where a run gets OPENHANDS_CLOUD_API_URL, SANDBOX_ID and SESSION_API_KEY instead (backends/cloud.py, dispatcher.py), and user secrets are served by the app server at /api/v1/sandboxes/{SANDBOX_ID}/settings/secrets/{name} — the same endpoint OpenHandsCloudWorkspace.get_secrets() calls.

On Enterprise, a Slack DM automation built from the skill's own no-LLM example failed with unknown url type: '/api/settings/secrets/SLACK_BOT_TOKEN'. Pointing it at the sandbox's agent server instead returned 404, because nothing fills that store in cloud mode, and the OpenHands agent ended up hardcoding the Slack token into main.py.

Summary

• All three get_secret() copies (the SKILL.md helper, plus the deterministic-script section and the complete no-LLM example in custom-automation.md) now branch on AGENT_SERVER_URL, the same signal the service's presets use to detect local mode. When it is set, the agent-server lookup is unchanged; otherwise the helper calls the sandbox-scoped endpoint on OPENHANDS_CLOUD_API_URL with the same X-Session-API-Key header. A missing cloud variable raises a KeyError that names it instead of an opaque URL error.
• The run environment table documents OPENHANDS_CLOUD_API_URL and SANDBOX_ID and marks AGENT_SERVER_URL as local Agent Canvas only; the prose and troubleshooting lines that described the old lookup now match.
• skills/index.js regenerated with npm run build:skills.

Issue Number

OHE-3347

How to Test

1. From the repo root, run the stub check below. It extracts every get_secret() copy from the two docs, so it exercises exactly what gets copied into a script, and calls each one against a local stub server in both modes.
   • On main, cloud mode reproduces the reported failure for all three copies: ValueError: unknown url type: '/api/settings/secrets/SLACK_BOT_TOKEN'.
   • On this branch, cloud mode requests /api/v1/sandboxes/<SANDBOX_ID>/settings/secrets/<name> and local mode still requests /api/settings/secrets/<name>, both with the session key header.
2. uv run --group test pytest tests/ — 1091 passed, 23 skipped.
3. python scripts/sync_extensions.py --check passes, and npm run build:skills leaves skills/index.js unchanged.

Stub check and output

python3 - <<'EOF'
import os, re, threading
from http.server import BaseHTTPRequestHandler, HTTPServer

class Stub(BaseHTTPRequestHandler):
    def do_GET(self):
        print(f"    GET {self.path}  X-Session-API-Key={self.headers['X-Session-API-Key']}")
        self.send_response(200); self.end_headers(); self.wfile.write(b"xoxb-test\n")
    def log_message(self, *args): pass

srv = HTTPServer(("127.0.0.1", 0), Stub)
threading.Thread(target=srv.serve_forever, daemon=True).start()
base = f"http://127.0.0.1:{srv.server_port}"

docs = "".join(open(p).read() for p in (
    "skills/openhands-automation/SKILL.md",
    "skills/openhands-automation/references/custom-automation.md"))
helpers = re.findall(r"^def get_secret\(.*?^        return r\.read\(\)\.decode\(\)\.strip\(\)$", docs, re.S | re.M)

modes = {
    "cloud": {"OPENHANDS_CLOUD_API_URL": base, "SANDBOX_ID": "sbx-1", "SESSION_API_KEY": "sk-1"},
    "local": {"AGENT_SERVER_URL": base, "SESSION_API_KEY": "sk-1"},
}
for i, src in enumerate(helpers, 1):
    ns = {}
    exec("import os, urllib.request\n" + src, ns)
    for mode, env in modes.items():
        for k in ("AGENT_SERVER_URL", "OPENHANDS_CLOUD_API_URL", "SANDBOX_ID"):
            os.environ.pop(k, None)
        os.environ.update(env)
        print(f"copy {i} {mode}:")
        try:
            print(f"    -> {ns['get_secret']('SLACK_BOT_TOKEN')!r}")
        except Exception as e:
            print(f"    -> {type(e).__name__}: {e}")
EOF

Output on this branch:

copy 1 cloud:
    GET /api/v1/sandboxes/sbx-1/settings/secrets/SLACK_BOT_TOKEN  X-Session-API-Key=sk-1
    -> 'xoxb-test'
copy 1 local:
    GET /api/settings/secrets/SLACK_BOT_TOKEN  X-Session-API-Key=sk-1
    -> 'xoxb-test'
copy 2 cloud:
    GET /api/v1/sandboxes/sbx-1/settings/secrets/SLACK_BOT_TOKEN  X-Session-API-Key=sk-1
    -> 'xoxb-test'
copy 2 local:
    GET /api/settings/secrets/SLACK_BOT_TOKEN  X-Session-API-Key=sk-1
    -> 'xoxb-test'
copy 3 cloud:
    GET /api/v1/sandboxes/sbx-1/settings/secrets/SLACK_BOT_TOKEN  X-Session-API-Key=sk-1
    -> 'xoxb-test'
copy 3 local:
    GET /api/settings/secrets/SLACK_BOT_TOKEN  X-Session-API-Key=sk-1
    -> 'xoxb-test'

Not exercised against a live Cloud or Enterprise sandbox. The endpoint contract comes from the app server's sandbox router (X-Session-API-Key auth, text/plain body), which the SDK's OpenHandsCloudWorkspace.get_secrets() and the prompt/plugin presets already rely on.

Video/Screenshots

N/A — documentation-only change. The stub output above shows the before/after behavior.

Notes

• Scope is the skill's guidance only. The same local-only lookup is still in:

  • the get_secret() helper of the shipped automation scripts (skills/{slack-channel-monitor,news-digest,github-pr-reviewer,github-issue-to-pr,github-repo-monitor,github-agents-md-maintainer,gitlab-issue-to-mr,jira-issue-to-pr}/scripts/main.py);
  • the SDK templates in custom-automation.md, which pass AGENT_SERVER_URL as cloud_api_url;
  • the relative LookupSecret URLs in references/security.md.

  These need their own changes (several of the scripts have tests), so they are left for follow-ups.

• docs: turn automation creation into a phased interview, close reliability gaps #455 edits the same two files and keeps the old helper, so it will need a rebase after this lands.

[openhands-release-bot]

🚀 Released in v0.26.0.