docs: add examples directory with LLM and OpenClaw tool invocation patterns#42
docs: add examples directory with LLM and OpenClaw tool invocation patterns#42Bandwe wants to merge 1 commit intoopenclaw:mainfrom
Conversation
…tterns - Add examples/ directory with 4 workflow examples: - llm-basic.lobster: Simple LLM invocation - llm-with-approval.lobster: LLM calls with human approval gates - openclaw-tool-call.lobster: Calling OpenClaw tools (llm-task, sessions.list, etc.) - data-pipeline.lobster: Data passing between steps without temp files - Add examples/README.md with detailed documentation and common patterns - Update main README.md with examples section reference - Enhance 'Calling LLMs from workflows' section with workflow examples - Enhance 'Calling OpenClaw tools from workflows' section with multiple methods Fixes openclaw#26
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aeaa5df9c5
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| # Step 2: Request approval if the operation is costly | ||
| - id: approval | ||
| approval: "About to run an LLM query. Proceed?" | ||
| when: $check-cost.json.needsApproval |
There was a problem hiding this comment.
when: expression syntax
evaluateCondition only accepts true, false, $step.approved, and $step.skipped in src/workflows/file.ts:461-479. This example uses $check-cost.json.needsApproval here (and later a ternary), so lobster run will throw Unsupported condition before it ever reaches the approval or LLM steps. As written, the new approval workflow is not runnable for any input.
Useful? React with 👍 / 👎.
| # Step 1: Create initial data | ||
| - id: init | ||
| run: > | ||
| echo '${items}' | json |
There was a problem hiding this comment.
json as a Lobster stage, not a shell binary
run: steps execute in the system shell, but this package only installs lobster, openclaw.invoke, and clawd.invoke as executables (package.json). The json command exists only as an in-process Lobster stage in src/commands/stdlib/json.ts, so echo ... | json fails with json: command not found on a normal install. That makes the very first step of this advertised example impossible to start.
Useful? React with 👍 / 👎.
| pipeline: > | ||
| llm.invoke | ||
| --provider openclaw | ||
| --prompt "Format this summary as a bullet list: ${summarize.json}" |
There was a problem hiding this comment.
$step.json instead of ${step.json} here
${...} placeholders are only expanded for workflow args in resolveArgsTemplate (src/workflows/file.ts:423-427); previous-step outputs are substituted later via bare $step.json / $step.stdout (src/workflows/file.ts:430-437). Because this line uses ${summarize.json}, the second LLM call receives the literal text ${summarize.json} instead of the first step's output, so the chaining example silently does the wrong thing. The same unsupported syntax appears throughout the new docs/examples.
Useful? React with 👍 / 👎.
| openclaw.invoke | ||
| --tool llm-task | ||
| --action json | ||
| --args-json '{"prompt": "${prompt}"}' |
There was a problem hiding this comment.
--args-json
Workflow ${arg} substitution is a plain string replace (src/workflows/file.ts:423-427). Embedding it directly inside JSON here means prompts containing quotes, backslashes, or newlines produce invalid --args-json, and openclaw.invoke immediately rejects that via JSON.parse in src/commands/stdlib/openclaw_invoke.ts:61-65. Inputs like He said "hi" will therefore make this example fail before it reaches OpenClaw.
Useful? React with 👍 / 👎.
1 participant
Fixes #26
Summary
This PR adds comprehensive examples for calling LLMs and OpenClaw tools from Lobster workflows, addressing the confusion in issue #26.
Changes
New examples/ directory
Added 4 ready-to-run workflow examples:
Documentation
examples/README.md - Comprehensive guide with:
README.md updates:
Key improvements over existing docs
Testing
All examples follow the patterns tested in test/llm_invoke.test.ts and test/llm_task_invoke.test.ts.
/cc @gotexis